Basic Usage

You can call imgCheckbox without any parameters on any jQuery collection containing img elements.

$("img").imgCheckbox();

imgCheckbox automatically attaches to a parent form (if one is present).
The submit event is captured and values are injected. Hit submit to see the form serialized below.

Hit submit to see the form serialized.

imgCheckbox will use the name attribute from your img if one is present.
Otherwise (as above), the filename (without the extension) will be used.

Options

OptionTypeValuesDefault
checkMarkImage URL Supports anything your clients' browsers support in the background-image property (of a pseudo selector). SVG Data URI which draws a white tick on semi transparent green.
graySelected Boolean Convenience option: Adds the necessary CSS rules to apply a grayscale filter on selected images. true
scaleSelected Boolean Convenience option: Adds the necessary CSS rules to apply a downscaling filter on selected images. true
fixedImageSize String / Boolean Sets a fixed image size to all images (useful if images vary in size). Values can be "200px" or "120px 200px" (not percentages). false
checkMarkSize String / Boolean Sets a custom size for the image (Useful if your images are very large or very small and the default is not suitable). Values can be "30px" and "20px 30px" (note: percentages do not work). 30px
checkMarkPosition String Sets the position of the checkMark. Options are: top-left, top, top-right, left, center, right, bottom-left, bottom, bottom-right etc. (for more advanced positioning, the styles option can be used on span.imgCheckbox::before) top-left
scaleCheckMark Boolean Convenience option: Adds the necessary CSS rules to apply a zooming effect on the checkmark as it appears and disappears. true
fadeCheckMark Boolean Convenience option: Adds the necessary CSS rules to fade the checkmark in and out. false
addToForm jQuery / Boolean imgCheckbox can inject the checked elements into the form. If true, imgCheckbox will find a parent form and attach to it. Alternatively, a jQuery object can be passed in shadow checkboxes will be appended to and controlled within it (the images needn't even be within the form). true
preselect [Integer] To preselect certain elements, use this syntax:
{ preselect: [0,1,2]}
Alternatively, you may preselect all elements using the syntax:
{ preselect: true }		 []
radio Boolean Images function as radio/option buttons (rather than checkboxes). Only one can be selected. No element is automatically preselected (see preselect). false
canDeselect Boolean When the radio option is set to true, this option allows the selected image to be deselected. false
styles Object For advanced customisation, the full stylesheet is applied using this object. (see source)

Events

Event callbacks are accessible via the options object. Use the following syntax:

$("img").imgCheckbox({
    onload: function(){
        // Do something fantastic!
    },
    onclick: function(el){
    	var isChecked = el.hasClass("imgChked"),
	    imgEl = el.children()[0];  // the img element
	    
	console.log(imgEl.name + " is now " + (isChecked? "checked": "not-checked") + "!");
    }
});
EventExplanation
onload Fires when the initialisation of the imgCheckbox collection is complete.
onclick Fires when an element is clicked.

Methods

MethodUsageReturn
$.select() Selects the element (if it is a member of an imgCheckbox group). If the element is part of a radio group, the other elements will be deselected. jQuery
$.deselect() Deselects the element (if it is a member of an imgCheckbox group). Other elements are unaffected (even in radio groups). jQuery

Advanced Usage

Advanced customisation can be achieved by applying styles through the styles option.
Want to add a fancy CSS3 blur filter to selected images? No Problem...

$("img").imgCheckbox({
    "styles": {
        "span.imgCheckbox.imgChked img": {
            // It's important to note that overriding the "filter" property will remove grayscaling
            "filter": "blur(5px)",

            // This is just css: remember compatibility
            "-webkit-filter": "blur(5px)",

            // Let's change the amount of scaling from the default of "0.8"
            "transform": "scale(0.9)"
        }
    }
});


Github Github Basic Usage Options Events Methods Advanced Usage