Pssst, yeah you! Have a look on my lastest Open Source project: WordPress Hybrid Client: Create free iOS/Android mobile applications for WordPress

BttrLazyLoading Responsive Lazy Loading plugin for JQuery

BttrLazyLoading is a Jquery plugin that allows your web application to only load images within the viewport. It also allows you to have different version of an image for 4 different screen sizes.


Demos Project on Github

Lazy loading

BttrLazyLoading allows your Web application to defer image loading until images are scrolled to. That way the page loading time decreases considerably.


BttrLazyLoading makes sure that you always have the appropriate image loaded for any type of screen: phones ( <768px), tablets (≥768px), desktops (≥992px) and large Desktops (≥1200px).

Retina ready

BttrLazyLoading uses a naming convention @2x to display Retina images when the option is enabled.


With more than 10 options (such as animations or background color) and 4 events, BttrLazyLoading is fully customizable to adapt to most needs.

Options can be set for one or several images at the same time or for the whole page at once (using the setOptions global function)

Name description

Adds delay to the image loading time.


By default images are loaded when they appear on the screen. If you want images to load earlier use threshold parameter. For instance setting a threshold to 200 end up loading the image 200 pixels before it appears on viewport.


Adds an animation when the image appears. You have access to all of the following animations created by Animate.css or use Null if you do not want any animation.

Check animate.css demo page to know the list of available animations.

Defines the event that will be used to trigger the image loading/update.


Base64 image that is used when the image is loading.


You can also use this plugin for images inside scrolling container, such as div with scrollbar. By default the container is the window.


Enables a better quality on Retina screens.

BttrLazyLoading uses a naming convention @2x to display Retina images. BttrLazyLoading will therefore seek "yourImage@2x.gif" on Retina screens instead of "yourImage.gif"


Whether or not to trigger the first image loading manually.


Whether or not to trigger the image update manually (needed when the window resizes for example).


Displays a background color before loading the image.


Image Object for Mobile


Image Object for Tablet


Image Object for Desktop


Image Object for Large Desktop

BttrLazyLoading options can be set in two different ways: using jQuery data on the image element or directly on the instantiation.

Set options using data attributes

                    <img id="yourImageId" class="bttrlazyloading" data-bttrlazyloading-xs-src="img/768x200.gif" data-bttrlazyloading-sm-src="img/345x250.gif" data-bttrlazyloading-md-src="img/455x350.gif"
                        data-bttrlazyloading-lg-src="img/360x300.gif" data-bttrlazyloading-animation="rotatedIn" data-bttrlazyloading-retina="true" data-bttrlazyloading-delay="2000" data-bttrlazyloading-event="mouseover"
                        data-bttrlazyloading-container="document.body" data-bttrlazyloading-threshold="500" data-bttrlazyloading-placeholder="data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg=="

For an optimized user experience 'width' and 'height' are necessary (the plugin cannot know the dimensions of your images before they load).

                    <img id="yourImageId" class="bttrlazyloading" data-bttrlazyloading-xs-src="img/768x200.gif" data-bttrlazyloading-xs-width="768" data-bttrlazyloading-xs-height="200" data-bttrlazyloading-sm-src="img/345x250.gif"
                        data-bttrlazyloading-sm-width="345" data-bttrlazyloading-sm-height="250" data-bttrlazyloading-md-src="img/455x350.gif" data-bttrlazyloading-md-width="455" data-bttrlazyloading-md-height="350"
                        data-bttrlazyloading-lg-src="img/360x300.gif" data-bttrlazyloading-lg-width="360" data-bttrlazyloading-lg-height="300" />

Set options on Instantiation

                    $("#yourImageId").bttrlazyloading({ xs: { src: "img/720x200.gif", width: 720, height: 200 }, sm: { src: "img/360x200.gif", width: 360, height: 200 }, md: { src: "img/470x200.gif", width: 470, height: 200 }, lg: { src: "img/570x200.gif",
                        width: 570, height: 200 }, retina: true, animation: 'fadeInUp', delay: 1000, event: 'click', container: 'document.body', threshold: 666, placeholder: 'test' })

Plugin dependencies: BttrLazyLoading depends on jQuery (meaning jQuery must be included before the plugin files) and Animate.css (optional) for animations..

                    <script src="jquery.min.js"></script> <link rel="stylesheet" type="text/css" href="bttrlazyloading.min.css" /> <link rel="stylesheet" type="text/css"
                        href="animate.min.css" /> <script src="jquery.bttrlazyloading.min.js"></script>

The following demos are using the same element attributes:

                    <img id="yourImageId" class="bttrlazyloading" data-bttrlazyloading-xs='{"src": "img/720x200.gif", "width" : 720, "height" : 200}' data-bttrlazyloading-sm='{"src":
                        "img/360x200.gif", "width" : 360, "height" : 200}' data-bttrlazyloading-md='{"src": "img/470x200.gif", "width" : 470, "height" : 200}' data-bttrlazyloading-lg='{"src":
                        "img/570x200.gif", "width" : 570, "height" : 200}' />

Surprise that there is no src attribute? Answer here

A 2 seconds delay has been added to all images for the demos.
Type: Integer, Default: 0


Set the delay to 4 seconds:

                                    $('#yourImageId').bttrlazyloading({ delay: 4000 });
Type: Integer, Default: 0


The image will be automatically triggered after you scrolled 200px down from the top of the image.

                                    $('#yourImageId').bttrlazyloading({ threshold: -200 });

If you want the image loaded before you even see it Set the threshold to a positive integer.

                                    $('#yourImageId').bttrlazyloading({ threshold: 200 });
Type: String, Default: "bounceIn"


Here we will use the 'rollIn' animation to show how to overwrite the default "bounceIn" animation.

                                    $('#yourImageId').bttrlazyloading({ animation: 'rollIn' });
Type: String, Default: "scroll"


By default the updating event window.onscroll. Using the "event" option you can listen to any window event such as "keydown" or "mousedown".

Press a key on your keyboard to load the image beside (if the image is already loaded, it means you have already pressed a key on your keyboard).

                                    $('#yourImageId').bttrlazyloading({ event: 'keydown' });
Type: String, Default:


Using the placeholder option you can add a custom loading image to replace the default image:

                                    $('#yourImageId').bttrlazyloading({ placeholder: 'data:image/gif;base64,R0lGODlhMgAyAKUAAO7u...' });
Type: String(Css selector), Default: window


Lorem ipsum dolor sit amet, consectetur adipiscing elit. In cursus quam nec auctor placerat. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Nulla ut metus malesuada, congue sem quis, aliquet risus. Pellentesque eget odio sed nibh imperdiet porta. Maecenas quis volutpat diam, at tempor sem. Mauris consequat dui eget nunc semper lobortis. Maecenas libero dui, aliquam ut nibh in, eleifend interdum nibh. Sed ullamcorper eros in sem sollicitudin, et pharetra nisi vulputate. Pellentesque nunc tellus, aliquet quis nisi nec, venenatis tempus nibh. Donec orci nulla, fringilla ac augue eget, lacinia convallis risus.

Sed vel dignissim turpis. Morbi posuere tortor sed purus mattis fermentum. Quisque libero arcu, sollicitudin vitae euismod vel, pharetra sit amet ante. Praesent molestie urna ut tortor pharetra venenatis. Pellentesque posuere, libero ac commodo mattis, sem orci semper erat, eget elementum ligula ante vel metus. Nunc non odio sit amet justo adipiscing iaculis. Duis sodales, dolor sit amet convallis tincidunt, purus velit tristique lorem, at convallis ligula ligula sit amet ligula. Suspendisse mauris ligula, tristique non dui id, laoreet rhoncus tellus.

Instead of using the window, you can specify another scrolling containers, such as a div with scrollbar.

                                    $('#yourImageId').bttrlazyloading({ container: '#option-container-wrapper' });
Type: Boolean, Default: false


You do not have a Retina display therefore you should not see any difference from other demos.
                                $('#yourImageId').bttrlazyloading({ retina: true });
Type: Boolean, Default: false


                                $('#yourImageId').bttrlazyloading({ triggermanually: true });

Forcing the loading of an image is as easy as that:

Type: Boolean, Default: false


                                $('#yourImageId').bttrlazyloading({ updatemanually: true });

Forcing the update of an image is as easy as that:

Type: String, Default: #EEE


PNG support (transparent background)

                                $('#yourImageId').bttrlazyloading({ backgroundcolor: '#1A6990', animation: 'fadeIn' }); $('#yourImageId').bttrlazyloading({ backgroundcolor: '#D08250', animation: 'fadeIn' }); $('#yourImageId').bttrlazyloading({ backgroundcolor:
                                    '#8FA92D', animation: 'fadeIn' }); $('#yourImageId').bttrlazyloading({ backgroundcolor: 'transparent', animation: 'fadeIn' });

Ranges define the size of your images for several types of screen. They can only be overwritten for the whole page (using the setRanges global function).

Name description

Ranges follows Bootstrap 3 grid sizes. xs for phones ( <768px), sm for small devices tablets (≥768px), md for medium devices desktops (≥992px) and lg for large devices desktops (≥1200px).

For most of the needs, the default value (Bootstrap 3 grid) does not need to be changed.

Returns: $(img)


The destroy function removes custom css, custom classes and unbind events but do not remove the image element.

                            # Get the BttrLazyLoading instance and destroy it. $('#yourImageId').bttrlazyloading('destroy');

Removing the image element

                            # Get the BttrLazyLoading instance, destroy it and remove the image element. $('#yourImageId').bttrlazyloading('destroy').remove();

Two global methods are available to interact with all BttrLazyLoading instances in the page.

Returns: bttrlazyloading Global


                            $.bttrlazyloading.setRanges({ xs: 767, sm: 768, md: 992, lg: 1200 });
Returns: bttrlazyloading Global


                            $.bttrlazyloading.setOptions({ retina: true, animation: 'fadeInUp', delay: 1000, event: 'click', container: 'document.body', threshold: 666, placeholder: 'test' });
Event Type description

This event is triggered just before the "bttrlazyloading.load" event.


This event is triggered when the image loads. You can trigger it manually like this:



This event is triggered just after the "bttrlazyloading.load" event.


This event is triggered when none of the images (xs, sm, md and lg) exist. The classic "error" event could therefore be triggered up to 8 times (4 times for a normal screen and 8 times for a Retina screen) while "bttrlazyloading.error" will be triggered only once.

More information in the option section: onError

Only one image size needed!

BttrLazyLoading always try to load the biggest version of the image available. Therefore the following example will work on every screen too.

                    <img id="yourImageId" class="bttrlazyloading" data-bttrlazyloading-md-src="img/455x350.gif" />

No src attribute?

Browsers are too quick for us! In order to provide the fastest loading time possible, browsers preload all of the images that they can identify

Choosing A Responsive Image Solution, Smashing Magazine

You may have noticed that none of our image elements have a "src" attribute. Well, that is normal! As describe here by the Smashing Magazine, the browsers preload the images even before the document ready event, which make it impossible for this plugin to process the information before the image loads.

Fallback for Non JavaScript Browsers

                    <img class="bttrlazyloading" data-bttrlazyloading-xs-src="img/768x200.gif" data-bttrlazyloading-xs-width="768" data-bttrlazyloading-xs-height="200" /> <noscript> <img class="bttrlazyloading"
                        src="img/768x200.gif" width="768" height="200"/> </noscript>

IE 9 appears to need this CSS

                    noscript { display: block; }

Convenient way to set data attributes

The following examples are equivalent:

                    <img id="yourImageId" class="bttrlazyloading" data-bttrlazyloading-xs-src="img/768x200.gif" data-bttrlazyloading-xs-width="768" data-bttrlazyloading-xs-height="200" />
                    <img id="yourImageId" class="bttrlazyloading" data-bttrlazyloading-xs='{"src": "img/768x200.gif", "width" : 768, "height" : 200}' />

In order to bring the best features to this plugin I encourage you to post a feedback (good or bad).