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

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.
  • 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

© 2008-2014 - Plugin by Cirkuit Networks, Inc. - http://www.cirkuit.net/
Images from http://www.freeimages.co.uk/