jQuery 'onImagesLoad' Plugin

Official documentation for the jQuery 'onImagesLoad' plugin

Current Version: 1.1.1 - Last Updated: January 27, 2010 - Regularly verified as compatible with the newest jQuery libraries (currently, version 1.4.1)

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

All images within each item of the $(selector) have loaded (the 'itemCallback')
All images within the entire $(selector) have loaded (the 'selectorCallback')

Examples

Example 1 - Callback when all images have loaded on the entire page
Example 2 - Using the 'selectorCallback' vs. the 'itemCallback'
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

itemCallback

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.

selectorCallback

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.

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
Internet Explorer 7
Internet Explorer 8
Mozilla Firefox 2
Mozilla Firefox 3
Opera 9
Google Chrome (recently added)
Safari (recently added)

*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 from 1.2.6 through 1.4.1 (the most recent version)
Small size: the minified version is only 940 bytes (439 bytes gzipped)
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 http://plugins.jquery.com/project/onImagesLoad