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.

Share!


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.

Responsivity

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.

Customizable

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
delay

Adds delay to the image loading time.

threshold

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.

animation

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.

['flipInX', 'flipInY', 'fadeIn', 'fadeInUp', 'fadeInDown', 'fadeInLeft', 'fadeInRight', 'fadeInUpBig', 'fadeInDownBig', 'fadeInLeftBig', 'fadeInRightBig', 'slideInDown', 'slideInLeft', 'slideInRight', 'bounceIn', 'bounceInDown', 'bounceInUp', 'bounceInLeft', 'bounceInRight', 'rotateIn', 'rotateInDownLeft', 'rotateInDownRight', 'rotateInUpLeft', 'rotateInUpRight', 'lightSpeedIn', 'rollIn']
event

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

placeholder

Base64 image that is used when the image is loading.

container

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

retina

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"

triggermanually

Whether or not to trigger the first image loading manually.

updatemanually

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

backgroundcolor

Displays a background color before loading the image.

xs

Image Object for Mobile

sm

Image Object for Tablet

md

Image Object for Desktop

lg

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

delay

Set the delay to 4 seconds:

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

threshold

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"

animation

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

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

event

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:

placeholder

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

container

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

retina

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

triggermanually

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

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

$('#yourImageId').trigger('bttrlazyloading.load');
Type: Boolean, Default: false

updatemanually

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

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

$('#yourImageId').trigger('bttrlazyloading.load');
Type: String, Default: #EEE

backgroundcolor



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

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)

destroy()

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

setRanges()

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

setOptions()

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

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

bttrlazyloading.load

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

$('#yourImageId').trigger('bttrlazyloading.load');

bttrlazyloading.afterLoad

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

bttrlazyloading.error

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>

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