jQuery 'onImagesLoad' Plugin

Official documentation for the jQuery 'onImagesLoad' plugin

Current Version: 1.2.2 - Last Updated: May 13, 2013 - Regularly verified as compatible with the newest jQuery libraries (currently, version 1.10.2)

'onImagesLoad' is a simple jQuery plugin that will callback a function when:

'All' images within the entire $(selector) have loaded
'Each' item within the $(selector) has loaded its own images

Examples

Example 1 - Callback when all images have loaded on the entire page
Example 2 - Using the 'all' callback vs. the 'each' callback
Example 3 - Attaching to individual images
Example 4 - Combination of Examples 1, 2, and 3
Example 5 - Attaching to dynamic content

Options
Compatible Browsers
Other Info
Ideas for Improvement
Feedback

Options

The options can be an object with the following properties below, OR it can be a function. If it is a function, it is assumed to be the 'all' callback function option (as described below). See example 1 versus example 2.

The 'all' Callback

Data Type: function (default=null)
This function is invoked only once: when all images within all items of the $(selector) have loaded.
- For example, if the selector is $('.imageHolder') and the page has multiple items with class 'imageHolder', this function is invoked only when all images of every imageHolder section have loaded
- See Example 2 for more details.
This callback function takes one argument which will contain the $(selector) with all images loaded.
Previously named 'selectorCallback' which will still work for reverse compatibility.

The 'each' Callback

Data Type: function (default=null)
This function is invoked when all images within a single item of $(yourSelector) have loaded.
Each object selected in the $(selector) gets its own callback.
- For example, if the selector is $('.imageHolder') and the page has multiple items with class 'imageHolder', each imageHolder item will fire its own callback independently.
- See Example 2 for more details.
This callback function takes one argument which will contain the DOM object with all images loaded.
Previously named 'itemCallback' which will still work for reverse compatibility.

callbackIfNoImagesExist

Data Type: boolean (default=false)
If true, the callbacks will be invoked even if no images exist within the $(selector).
If false, the callbacks will not be invoked if no images exist within the $(selector).

Compatible Browsers

This plugin has been verified as working in the following browsers:

Internet Explorer 6+
Mozilla Firefox (latest)
Opera (latest)
Google Chrome (latest)
Safari (latest)
AppleWebKit (latest)

*Any browser not listed simply has not yet been tested. Please let us know about your experiences with other browsers by leaving feedback.

Other Info

Requires the jQuery library
- Tested with all versions of jQuery 1.2.6+
Small size: the minified version is only 1.08 KB without comments (gzipped even smaller)
Correctly works with chaining and multiple selectors.
Can be used anytime an image is or is not already loaded, including fully loaded pages and AJAX calls that add new images to the DOM.
- See Example 5 for more details.
If an image does not load (i.e. broken link, bad connection, etc.), the callbacks will not get fired.

Ideas for Improvement

* note: these ideas may be useless and not make any sense.

Handle images that do not load (i.e. broken link, bad connection, etc.) by utilizing the onError event.
Include CSS background images?
More callbacks? (i.e. one for each image that loads regardless of the $(selector), one for status, etc.) This may just make the plugin bloated.
Need to unbind events?
Perhaps support ANY element that contains the javascript onLoad event (i.e. window, frame, script, etc.), not strictly images?
You have an idea? See the feedback tab…

Feedback

Please post comments, problems, and suggestions to jQuery.com's onImagesLoad plugin page at https://plugins.jquery.com/project/onImagesLoad