Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/alexanderdickson/waitForImages
A jQuery plugin that lets you attach callbacks to useful image loading events.
https://github.com/alexanderdickson/waitForImages
jquery-plugin
Last synced: 10 days ago
JSON representation
A jQuery plugin that lets you attach callbacks to useful image loading events.
- Host: GitHub
- URL: https://github.com/alexanderdickson/waitForImages
- Owner: alexanderdickson
- License: mit
- Created: 2011-02-06T11:42:34.000Z (almost 14 years ago)
- Default Branch: master
- Last Pushed: 2022-05-30T09:26:01.000Z (over 2 years ago)
- Last Synced: 2024-04-29T13:40:24.271Z (7 months ago)
- Topics: jquery-plugin
- Language: JavaScript
- Homepage: http://alexanderdickson.com
- Size: 243 KB
- Stars: 1,304
- Watchers: 45
- Forks: 184
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE-MIT
Awesome Lists containing this project
- awesome-jquery - waitForImages - A jQuery plugin that lets you attach callbacks to useful image loading events. (Images / Data Table)
README
# waitForImages
Copyright (c) 2011-2018 Alexander Dickson [@alexdickson](http://twitter.com/alexdickson)
Licensed under the [MIT licenses](https://raw.github.com/alexanderdickson/waitForImages/master/LICENSE-MIT).
[http://alexanderdickson.com](http://alexanderdickson.com)
[Donate!](http://paypal.me/alexwilliamdickson)
[](http://travis-ci.org/alexanderdickson/waitForImages)
## Overview
Provides useful callbacks once descendant images have loaded.
waitForImages also supports both images referenced in CSS, such as the `background-image` property, and images referenced in element attributes such as `srcset`. Images referenced in attributes can also be a comma-separated list of images.
It can be useful when WebKit incorrectly reports element dimensions/offsets on document ready, because it has not calculated their descendant `img` dimensions yet.
Supports all browsers you probably care about.
## Get it
You can either grab the source yourself...
- [Production (minified)](https://raw.github.com/alexanderdickson/waitForImages/master/dist/jquery.waitforimages.min.js)
- [Development (unminified)](https://raw.github.com/alexanderdickson/waitForImages/master/dist/jquery.waitforimages.js)
...or you can use a hosted version...
- [Hosted on CDNJS (minified)](http://cdnjs.cloudflare.com/ajax/libs/jquery.waitforimages/1.5.0/jquery.waitforimages.min.js)
Alternatively, you can install with [`bower`](http://bower.io/)...
```bash
bower install waitForImages
```
...or [`npm`](https://www.npmjs.com/)...
```bash
npm install jquery.waitforimages
```
Of course, these need to be loaded after `jQuery` is made available. The current version should be supported by at least jQuery 1.8, or perhaps earlier. If you find incompatibility issues, please check out a previous tagged version.
## Usage
There are two ways to use waitForImages: with a standard callback system (previously the only API) or receiving a promise.
### Standard
Just provide a callback function and it will be called once all descendant images have loaded.
```javascript
$('selector').waitForImages(function() {
// All descendant images have loaded, now slide up.
$(this).slideUp();
});
```
You can also use the jQuery promise API.
```javascript
$('selector').waitForImages().done(function() {
// All descendant images have loaded, now slide up.
$(this).slideUp();
});
```
In the callbacks, `this` is a reference to the collection that `waitForImages()` was called on.
### Advanced
You can pass a second function as a callback that will be called for each image that is loaded, with some information passed as arguments.
```javascript
$('selector').waitForImages(function() {
alert('All images have loaded.');
}, function(loaded, count, success) {
alert(loaded + ' of ' + count + ' images has ' + (success ? 'loaded' : 'failed to load') + '.');
$(this).addClass('loaded');
});
```
Using the jQuery promises API, you can then use the `progress()` method to know when an individual image has been loaded.
```javascript
$('selector').waitForImages().progress(function(loaded, count, success) {
alert(loaded + ' of ' + count + ' images has ' + (success ? 'loaded' : 'failed to load') + '.');
$(this).addClass('loaded');
});
```
You can also set the third argument to `true` if you'd like the plugin to iterate over the collection and all descendent elements, checking for images referenced in the CSS (by default, it looks at the `background-image`, `list-style-image`, `border-image`, `border-corner-image` and `cursor` properties). If it finds any, they will be treated as a descendant image.
The callback will be called on the successful **and** unsuccessful loading of the image. Check the third argument to determine the success of the image load. It will be `true` if the image loaded successfully.
If you want to skip the first argument, pass `$.noop` or alternatively, pass an object literal to the plugin, instead of the arguments individually.
```javascript
$('selector').waitForImages({
finished: function() {
// ...
},
each: function() {
// ...
},
waitForAll: true
});
```
To use this with the promise API, simply pass one argument, which is `waitForAll`.
```javascript
$('selector').waitForImages(true).done(function() {
// ...
});
```
You may also set the CSS properties that possibly contain image references yourself. Just assign an array of properties to the plugin.
```javascript
$.waitForImages.hasImgProperties = ['backgroundImage'];
```
waitForImages also exposes two custom selectors, `img:has-src` and `img:uncached`, (both used in conjunction with the `img` selector), which allow you to select `img` elements with a valid `src` attribute or that are not already cached already by the browser, respectively.
```javascript
$('img').not(':has-src').remove();
$('img:uncached').attr('title', 'Loading Image');
```
## Feedback
Please use the [Issues](https://github.com/alexanderdickson/waitForImages/issues) for any bugs, feature requests, etc.
If you're having problems using the plugin, [ask a question on Stack Overflow](http://stackoverflow.com/questions/tagged/waitforimages).