- About
- Download / Install
- Usage
- Demo
- Advanced initialization
- Browsers with disabled JavaScript
- Options
- Events
- More than images
- Extendability
- Addons
- Example of page preparation in PHP
- Version History
- License
Mobile-oriented, fast and extensible jQuery plugin for lazy loading of images/videos with build-in support of jQueryMobile framework.
Currently tested in IE 6-11, Chrome 1-31, Firefox 1.5-27.0, Safari 3-7, Opera 10.6-18.0, iOS 5-7, Android 2.3-4.4, Amazon Kindle Fire 2 and HD 8.9.
Required jQuery 1.7+ or Zepto 1.0+.
| Dev version: | jquery.lazyloadxt.js | jquery.lazyloadxt.extra.js | jquery.lazyloadxt.simple.js |
| Minified version: | jquery.lazyloadxt.min.js | jquery.lazyloadxt.extra.min.js | jquery.lazyloadxt.simple.min.js |
Addons:
Install and manage Lazy Load XT using Bower
$ bower install lazyloadxt
Install and manage using NPM
$ npm install lazyloadxt
Get full snapshot of Lazy Load XT: lazy-load-xt-master.zip
If you have any feature to request or bug to report please use GitHub issues.
First of all it's necessary to load jQuery and Lazy Load XT script. There are three versions of Lazy Load XT:
-
jquery.lazyloadxt.js, standard version for lazy loading of images only. -
jquery.lazyloadxt.extra.js, version with included video addon for lazy loading of both images and videos. -
jquery.lazyloadxt.simple.js, version of minimal size with excluded support of on* handlers, lazy* events,blankImageoption and addons.
To make media elements (img, video, source, iframe) to be lazy loaded, rename src attribute to data-src.
It is highly recommended to set width and height attributes. Optionally you can add a placeholder src to bypass
HTML validators:
```html
<script src="jquery.js"></script>
<script src="jquery.lazyloadxt.js"></script>
<img data-src="lazy.jpg" width="100" height="100">
```
Demo: ressio.github.io/lazy-load-xt
There are two ways to initialize elements if auto initialization doesn't suit you:
$(window).lazyLoadXT();to initialize all elements matching$.lazyLoadXT.selector$(elements).lazyLoadXT();to initialize all selected elements.
For example, $(container).find(selector).lazyLoadXT(); initializes elements matching selector inside container.
You can pass optional argument to override default $.lazyLoadXT options. The following options only may be overridden:
srcAttr, edgeX, edgeY, visibleOnly, blankImage, classNojs.
Note: don’t forget to disable auto initialization with $.lazyLoadXT.autoInit=false; if you like to use manual
initialization of all elements.
As JavaScript may be disabled in the browser (e.g. it may be a feature phone with limited javascript support or browser
with Noscript addon), it is usually recommended to add a fallback image in <noscript> tag, mark initial image with
class="lazy" attribute and hide it using CSS (otherwise browsers with disabled javascript will display both images).
Lazy Load XT plugin removes this class (classNojs option) at image initialization. So, final code should be like:
```css
img.lazy {
display: none;
}
```
```html
<img class="lazy" data-src="lazy.jpg" width="100" height="100">
<noscript><img src="lazy.jpg" width="100" height="100"></noscript>
```
We recommend to keep the order of attributes in both <img> tags, because of such a code will be effectively gzipped.
Alternative approach is based on tagging images/videos with <script> tag. It is realized using
jquery.lazyloadxt.script.js addon and is described in corresponding addon’s section
(note that this approach is experimental and currently is not compatible with AJAX).
The plugin is very extensible and supports a lot of options that are stored in $.lazyLoadXT object:
```javascript
$.extend($.lazyLoadXT, {
edgeY: 200,
srcAttr: 'data-src'
});
```
You can either create this object before loading of jquery.lazyloadxt.js, or extend it after loading (but before
jQuery's ready event).
- autoInit: auto initialization of the plugin, that is processing of all elements matching
selectorselector in jQuery'sreadyevent, if it is disabled you have to do such initialization manually as explained in Advanced initialization section (defaulttrue) - selector: selector for elements that should be lazy-loaded (default
'img') - srcAttr: attribute containing actual
srcpath, see example below in [Hi-DPI (Retina) images] (#hi-dpi-retina-images) section (default'data-src') - classNojs: class name used to hide duplicated element (outside of
<noscript>tag) in the case of disabled JavaScript in browser, the plugin removes this class to make images visible (default'lazy') - blankImage: blank image for used until actual image is not loaded (default is transparent 1x1 gif image in
data-uri format
'data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7') - edgeY: expand visible page area (viewport) in vertical direction by specified amount of pixels,
so that elements start to load even if they are not visible, but will be visible after scroll by
edgeYpixels (default0) - edgeX: expand visible page area in horizontal direction by specified amount of pixels (default
0) - throttle: time interval (in ms) to check for visible elements, the plugin uses it to speed up page work in the
case of flow of page change events (default
99) - visibleOnly: added for compatibility with original
Lazy Load Plugin by Mika Tuupola, being disabled this option forces
the plugin to check element position only, but not to check that it is actually visible (default
true) - loadEvent: space-separated list of events when the plugin starts to found new elements matching
selector(default'pageshow'to check AJAX-loaded content in jQueryMobile and to support backward navigation in iPhone) - updateEvent: space-separated list of events when the plugin starts to check what elements are visible in
current viewport (default
'load orientationchange resize scroll') - forceEvent: space-separated list of events when the plugin starts to load all images independently of are
they visible or not (default
'') - oninit: handler called when the plugin push elements into internal list of "lazy" elements,
it may be either a function (DOM element is accessible using
thisobject) or an object withaddClassand/orremoveClassproperties (addClassis a space-separated list of class names that should be added to the elements, andremoveClasscontains class names that should be removed,removeClasshas higher priority in the case of identical class names) (defaultnull) - onshow: handler called when an element appears in viewport area, it may be either a function or an object by
analogy to
oninithandler, see example below in Spinner section (defaultnull) - onload: handler called when element is successfully loaded, it may be either a function or an object by analogy
to
oninithandler (defaultnull) - onerror: handler called when browser cannot load the element, it may be either a function or an object by analogy
to
oninithandler (defaultnull)
Lazy Load XT plugin triggers following events for loading elements (just before call to corresponding handler in
$.lazyLoadXT options):
lazyinit, the plugin push elements into internal list of "lazy" elementslazyshow, element appears in viewport arealazyload, element is successfully loadedlazyerror, browser cannot load the elementlazyloadall(triggered onwindowelement), internal list of lazy-loaded elements is empty, that is all elements are loaded or loading.
Unlike global handlers $.lazyLoadXT, using these events it's possible to assign individual handlers for media
elements.
Images are not the only page elements that may be lazy loaded. Though default value for $.lazyLoadXT.selector is
'img', you can append it by iframe to use lazy-loading for iframes, video for videos,
etc. Full list of supported tags include all tags with src attribute: <audio>, <embed>, <frame>,
<iframe>, <img>, <video>, <input type="image">.
We distribute special "extra" version of the plugin with additional code for lazyloading of <video> elements and
<iframe>ed YouTube videos. To use this version, it’s necessary to just load jquery.lazyloadxt.extra.js instead of
jquery.lazyloadxt.js.
Most of video hostings allow to embed videos as <iframe> elements (e.g. Youtube, Vimeo, DailyMotion, and even KickStarter)
and they may be lazy loaded in the way similar to images (by replacing src attribute by data-src):
```html
<script src="jquery.lazyloadxt.extra.js"></script>
```
```html
<iframe width="420" height="315" data-src="//www.youtube.com/embed/uOzO9O15gwI?rel=0" frameborder="0" allowfullscreen></iframe>
```
Demo: http://ressio.github.io/lazy-load-xt/demo/youtube-iframe.htm
It is easy too, just replace src attribute by data-src and poster by data-poster (if exists).
```html
<script src="jquery.lazyloadxt.extra.js"></script>
```
```html
<video data-poster="/path/to/poster.jpg" width="320" height="240" controls>
<source data-src="/path/to/video.mp4" type='video/mp4; codecs="avc1.42E01E, mp4a.40.2"'>
<source data-src="/path/to/video.ogv" type='video/ogg; codecs="theora, vorbis"'>
</video>
<video data-src="/path/to/video2.mp4" width="320" height="240" controls></video>
```
Demo: http://ressio.github.io/lazy-load-xt/demo/video-html5.htm
Lazy Load XT plugin may be easily extended using oninit, onshow, onload and onerror handlers. Some examples are
listed below.
To display animated spinner while image is loading, you can set/reset CSS class in onshow/onload events:
```css
/* CSS */
.lazy-hidden {
background:#eee url('/path/to/loading.gif') no-repeat 50% 50%;
}
```
```javascript
/* JS */
$.extend($.lazyLoadXT, {
onshow: { addClass: 'lazy-hidden' },
onload: { removeClass: 'lazy-hidden' },
onerror: { removeClass: 'lazy-hidden' }
});
```
Demo: http://ressio.github.io/lazy-load-xt/demo/spinner.htm
To add fade-in animation you can use following sample of onload event and CSS rules:
```css
/* CSS */
.lazy-hidden {
opacity: 0;
}
.lazy-loaded {
-webkit-transition: opacity 0.3s;
-moz-transition: opacity 0.3s;
-ms-transition: opacity 0.3s;
-o-transition: opacity 0.3s;
transition: opacity 0.3s;
opacity: 1;
}
```
```javascript
/* JS */
$.extend($.lazyLoadXT, {
oninit: { addClass: 'lazy-hidden' },
onload: { addClass: 'lazy-loaded', removeClass: 'lazy-hidden' }
});
```
Demo: http://ressio.github.io/lazy-load-xt/demo/fadein.htm
The code below allows you to use data-src-3x attribute for screens with 3x density (e.g. Samsung Galaxy S4),
data-src-2x for 2x density (e.g. iPhones 4+), and data-src-1.5x for 1.5x density (e.g. HTC Incredible S).
```javascript
/* JS */
(function($, dpr) {
if (dpr>1)
$.lazyLoadXT.srcAttr = 'data-src-' + (dpr > 2 ? '3x' : (dpr > 1.5 ? '2x' : '1.5x'));
})(jQuery, window.devicePixelRatio || 1);
```
Demo: http://ressio.github.io/lazy-load-xt/demo/retina.htm
But in real world it's better to set srcAttr function and choose most suitable image URL among existing ones. Or set
src attribute in lazyshow event, like it is done in Responsive images and srcset
addon.
If you use jQuery-based AJAX navigation and don't like to change existing AJAX callbacks,
you can apply lazy loading to new loaded content using ajaxComplete event. Note that $.lazyLoadXT.loadEvent = 'pageshow ajaxComplete'; may not work correctly because of content is not added to the page at the time of
ajaxComplete event, that's why it's better to postpone initialization by setTimeout:
```javascript
/* JS */
$(window).on('ajaxComplete', function() {
setTimeout(function() {
$(window).lazyLoadXT();
}, 50);
});
```
Demo: http://ressio.github.io/lazy-load-xt/demo/ajax.htm
Lazy Load XT uses Data-URI-encoded transparent image for images outside of viewport (though this image may be visible during fast page scroll or in print preview). As IE 6 and 7 don't support Data-URI, you can change image for that browsers:
```javascript
/* JS */
if (parseInt(navigator.userAgent.toLowerCase().split('msie')[1] || 8, 10) < 8)
$.lazyLoadXT.blankImage = '//upload.wikimedia.org/wikipedia/en/d/d0/Clear.gif';
```
Lazy Load XT may be easily extended to support other lazyloading-related things. Some examples are part of Lazy Load XT project and listed below.
Support of video elements in extra version of Lazy Load XT is just an addon that is combined with base version of the script. That is loading of
```html
<script src="jquery.lazyloadxt.extra.js">
```
is identical to loading of
```html
<script src="jquery.lazyloadxt.js">
<script src="jquery.lazyloadxt.video.js">
```
Options
$.lazyLoadXT.videoPoster name of attribute with path to background image (by default 'data-poster').
Note: this addon append iframe[data-src] to $.lazyLoadXT.selector, so if you change $.lazyLoadXT.srcAttr option,
selector option should be altered properly.
This addon allows to combine lazy loading and responsive images. Format of responsive images description is based on srcset attribute draft of HTML extension for adaptive images:
```html
<script src="jquery.lazyloadxt.js">
<script src="jquery.lazyloadxt.srcset.js">
```
```html
<img data-srcset="image-hd.jpg 2x, image-phone.jpg 360w, image-phone-hd.jpg 360w 2x">
<img data-srcset-base="image" data-srcset-ext=".jpg" data-srcset="-hd 2x, -phone 360w, -phone-hd 360w 2x">
```
If you like to have fallback image name to be data-srcset-base+data-srcset-ext (image.jpg in above example),
just put comma at the end of data-srcset tag: data-srcset="-hd 2x, -phone 360w, -phone-hd 360w 2x,". Note that
this addon doesn't require browser to support srcset attribute draft.
Demo: http://ressio.github.io/lazy-load-xt/demo/srcset.htm
Images and videos are not the only heavy parts of the page. Nowadays it's hard to find website that doesn't use
widgets for different social medias (like Twitter, Facebook, Google+, etc.). If integration with such resource is done
using <iframe> tag, you can use "extra" version of Lazy Load XT to make it lazy loaded:
```html
<script src="jquery.lazyloadxt.extra.js">
```
```html
<!-- Facebook Recommend Widget -->
<iframe data-src="http://www.facebook.com/plugins/like.php?href=http%3A%2F%2Fressio.github.io%2Flazy-load-xt&width&layout=button_count&action=recommend&show_faces=true&share=true&height=21"
scrolling="no" frameborder="0" style="border:none; overflow:hidden; height:21px;" allowTransparency="true"></iframe>
```
Demo: http://ressio.github.io/lazy-load-xt/demo/widget-iframe.htm
But in most cases JavaScript is used to embed widgets. Specially for this case we have universal
jquery.lazyloadxt.widget.js addon that allows to add some html code to the page when other element become visible.
The code should wrapped in html comment inside a div with assigned id attribute, and the element should have
data-lazy-widget attribute with value of that id:
```html
<script src="jquery.lazyloadxt.js">
<script src="jquery.lazyloadxt.widget.js">
```
```html
<!-- Google +1 Button -->
<div data-lazy-widget="gplus" class="g-plusone" data-annotation="inline" data-width="300"></div>
<div id="gplus"><!--
<script type="text/javascript">
(function() {
var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true;
po.src = 'https://apis.google.com/js/platform.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s);
})();
</script>
--></div>
```
Options:
$.lazyLoadXT.widgetAttr name of attribute with id of commented html code (by default 'data-lazy-widget').
Note: widgetAttr option should be set before loading of jquery.lazyloadxt.widget.js as it is used to alter
$.lazyLoadXT.selector option.
Demo: http://ressio.github.io/lazy-load-xt/demo/widget.htm
It is another issue of lazy loading: if user prints the page, only loaded images will be printed. This addon allows
to start loading of all images just after browser switch to print mode to render page. Note that this feature is
browser-dependent and currently it works correctly in IE only. In Chrome browser caches page state until user
change print options (printer, page orientation, margins, etc.). In Firefox and Safari addon works if user chooses
Print Preview before actual print (as they don't wait until images will be loaded). In Opera it works starting from
15.0 release (Presto didn't support both beforeprint event and matchMedia listeners).
```html
<script src="jquery.lazyloadxt.js">
<script src="jquery.lazyloadxt.print.js">
```
Demo: http://ressio.github.io/lazy-load-xt/demo/print.htm
This addon allows you to use lazy-loading technique for background images of any tag.
```html
<script src="jquery.lazyloadxt.js">
<script src="jquery.lazyloadxt.bg.js">
```
```html
<div data-bg="/path/to/image.png">...</div>
```
Above code set background-image CSS property to /path/to/image.png as soon div element becomes visible in
viewport area.
Options:
$.lazyLoadXT.bgAttr name of attribute with path to background image (by default 'data-bg'). Note: option
should be set before loading of jquery.lazyloadxt.bg.js as it is used to alter $.lazyLoadXT.selector option.
Demo: http://ressio.github.io/lazy-load-xt/demo/bg.htm
The main problem of lazy loading is necessity to duplicate <img> tag in <noscript> wrapper to support browsers with
disabled JavaScript. As an alternative way, jquery.lazyloadxt.script.js addon allows to prepend tag <img> tag by
<script> in the following form (without duplicating and renaming src to data-src):
```html
<script src="jquery.lazyloadxt.js">
<script src="jquery.lazyloadxt.script.js">
```
```html
<script>L()</script><img src="/path/to/image.jpg">
<script>Lb()</script>
<video>
<source src="/path/to/video.mp4">
</video>
<script>Le()</script>
<script>Lb('iframe')</script>
<iframe src="/path/to/iframe.htm"></iframe>
<script>Le()</script>
````
Here L() is function that should be called before self-closed tag like <img> and <input> (optional argument is
the tag name of lazy loaded element, by default 'img'), Lb() should be called before other tags like <video>
and <iframe> (optional argument is the tag name of lazy loaded element, by default 'video'), and Le() should be
called after corresponding closing tag.
Options:
$.lazyLoadXT.srcsetAttr name of attribute with responsive rules in srcset format, $.lazyLoadXT.srcsetBaseAttr name of attribute for URL prefix, $.lazyLoadXT.srcsetExtAttr name of attribute for URL suffix
Demo: http://ressio.github.io/lazy-load-xt/demo/script-tag.htm
This is very simple addon (just few lines of code) that loads all images after specified time after page loading. That is loading of images doesn't affect loading of CSSes and JavaScripts, and time to initial website rendering will be decreased.
```html
<script src="jquery.lazyloadxt.js">
<script src="jquery.lazyloadxt.autoload.js">
```
Options:
$.lazyLoadXT.autoLoad time interval between load page event and start of image loading (in ms, default is 50)
Demo: http://ressio.github.io/lazy-load-xt/demo/autoload.htm
Instead of manipulating <img> tags directly (that is to replace src by data-src,
add <noscript> fallback image, etc.), it's possible to do html page postprocessing using [your favorite] language.
Here is example of how to do it using PHP:
```php
/* PHP */
function addLazyLoading($html) {
$dom = new DOMDocument();
if(!@$dom->loadHTML('<?xml encoding="UTF-8">' . $html)) // trick to set charset
return $html;
foreach($dom->childNodes as $item)
if($item->nodeType === XML_PI_NODE) {
$dom->removeChild($item);
break;
}
$dom->encoding = 'UTF-8';
$images = $dom->getElementsByTagName('img');
$blankImage = 'data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7';
for($i = $images->length - 1; $i >= 0; $i--) {
$node = $images->item($i);
$clone = $node->cloneNode();
$noscript = $dom->createElement('noscript');
$noscript->appendChild($clone);
$node->parentNode->insertBefore($noscript, $node);
$node->setAttribute('data-src', $node->getAttribute('src'));
$node->setAttribute('src', $blankImage);
$node->setAttribute('class', trim($node->getAttribute('class') . ' lazy'));
}
$newHtml = $dom->saveHTML();
if(!$newHtml)
return $html;
return $newHtml;
}
```
- 0.8.6 (18.12.2013): New "widget" addon, support of per element options
- 0.8.5 (15.12.2013): New addons, "simple" version,
lazyloadallevent, slight reduce minified size - 0.8.4 (12.12.2013): Fixed check of removed elements,
support of
$.lazyLoadXT.videoPosterparameter, additional examples insrc(srcset polyfill, transparent placeholder for IE6/7) - 0.8.3 (10.12.2013): Speed up initialization,
new
forceEventoption, additional examples of extendability in/srcdirectory - 0.8.2 (08.12.2013): Built-in support of videos in
jquery.lazyloadxt.extra.js - 0.8.1 (06.12.2013): Add support of
lazyinit,lazyshow,lazyload, andlazyerrorevents - 0.8.0 (05.12.2013): Initial release
Lazy Load XT is licensed under the MIT license