Figuration v4.4 is now available!

Lazy lazy.js

Load images or embedded content only when they become visible within the viewport.

Overview

Lazy delays the loading of images outside of the viewport (visible part of the page) until the user scrolls them into view. In some cases this can help reduce both server load and overall bandwidth use.

Example

A lazy loaded image with delay and a fade in animation.

Test pattern
<img src="" data-cfw="lazy" data-cfw-lazy-delay="1000" data-cfw-lazy-animate="true" data-cfw-lazy-src="test.gif" width="360" height="202" alt="Test pattern">

Usage

Default Placeholder

In the case where the src attribute is missing, for set to an emtpy string, a placeholder image is inserted via a data:image string on the src attribute that equates to a 1x1px transparent GIF.

Default placeholder: <small>(no spaces or line-breaks when used)</small>

'data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7'

Image Dimensions

If you do not wish to have the document height change when an image is loaded, then it would be a good idea to specify the width and height dimensions of the image either through attributes or CSS.

Via Data Attributes

At a minimum, add data-cfw="lazy" along with a data-cfw-lazy-src="sourceURL" attribute to an image to replace the blank placeholder with the image found at sourceURL.

Via JavaScript

Enable manually with:

$('#myImg').CFW_Lazy();

Options

Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-cfw-lazy, as in data-cfw-lazy-src=image.png.

Name Type Default Description
src string null The URL or path for the source image to be displayed.
throttle integer 250 Timeout rate (milliseconds) for the throttle function helps to decrease function calls through scroll or resize events.
trigger string 'scroll resize'

How lazy load is triggered. You may pass multiple triggers; separate them with a space.

Custom event names are supported when standard browser events are not applicable.

delay integer 0 Delay time (milliseconds) to wait before loading image once the `show` method has been called.
animate boolean false If the image should appear with a fade-in animation when loaded.
threshold integer 0 Pixel offset from the viewport to use when calculating the invoking of the show method. Can be of positive of negative value. For example, setting threshold to 200 causes image to load 200 pixels before it appears within the viewport.
container string | node the window object Specifies a containing element, such as div with scrollbar, where the trigger event callbacks should be listened for.
invisible boolean false

There are cases when you have images which are in viewport but not :visible. To improve performance the lazy widget ignores .not(":visible") by default. If you want to load these images set invisible to true.

Browser Note

Webkit browsers will report images with without width and height as .not(":visible"). This causes images to appear only when you scroll a bit. Either fix your image tags or set invisible to true.

$('#myImg').CFW_Lazy({
src: 'image.png'
});

Methods

Method calls should be made on the image element.

Method Name Description
show Load the specified image source.
dispose Removes the event handlers from the element, leaving the image is its current state.
$('#myImg').CFW_Lazy('show');

Events

Event callbacks happen on the image element.

Event Type Description
init.cfw.lazy This event fires after the image item is initialized.
beforeShow.cfw.lazy This event is fired immediately when the show method is called.
afterShow.cfw.lazy This event is fired when a lazy loaded image source has been made visible to the user (will wait for specified effect to complete).
$('#myImg').on('afterShow.cfw.lazy', function() {
// do something...
});