The lazy load component makes it easy to defer loading of an image until it scrolls into view — which applies to inline and background images. This is especially useful in reducing the amount of HTTP requests in a given page.

The difference between this component, and other libraries, is that lazy loading is applied to a parent wrapper. There are 2 reasons for this, the first is that it allows deferred loading of background images (ones defined in CSS), and the second is bulk loading of imgs within the element. Simply place a .lazy-load (or the value of lazyClass) class on the element we want to monitor.

<div class="item lazy-load">
    <img data-src="/img/image.png" alt="">
When lazy loading inline images, use the data-src attribute instead of src.

Once elements have been marked, the component can be initialized on a parent container.


// Or an element with overflow hidden
Lazy loading should be initialized without DOM ready, but after lazy elements have been declared, so that images don't flicker.

Retina Support

To display a higher quality image for retina/HD displays, use data-src-retina. If no retina equivalent is found, it will fallback to data-src.

<div class="item lazy-load">
    <img data-src="/img/image.png" data-src-retina="/img/image-hd.png" alt="">

Scrolling Threshold

When no threshold is set, images will immediately load when they appear on screen. Defining a threshold (in pixels) will start pre-loading any images that appear outside the viewport.

    threshold: 200 // load images 200px off screen (default is 150)

Flicker Prevention

By default, all inline images will be collapsed before being loaded. Because of this, a flicker or element shift may occur once the image is loaded. To prevent this, define a width and height for the image, either inline or through CSS. We may also define the src attribute with a transparent fill-in image.

<img src="/img/fake-image.png" data-src="/img/real-image.png" width="250" height="100">


  • Background images will be overridden by the .lazy-load class.
  • Elements that have been loaded will have the .lazy-load class removed.


Variable Default Description
$lazyLoad-class .lazy-load CSS class name for the individual lazy load element.
$lazyLoad-transition .3s The transition time for fading background images in and out.


Inherits all options from the parent Component.

Option Type Default Description
delay int 10000 The number of milliseconds to wait before force loading all images.
forceLoad bool false Force the loading of all images once the delay has passed.
lazyClass string .lazy-load The class name to search for and to remove while loading.
threshold int 150 The distance in pixels near the edge of the viewport to start pre-loading images.
throttle int 50 The number of milliseconds to throttle all loading events.


Inherits all events from the parent Component.

Event Arguments Description
loading Triggered before scrolling or resizing to check for elements to load.
loaded Triggered after scrolling or resizing to check for elements to load.
loadAll Triggered when elements have been force loaded.
showing element:element Triggered before an element (that may contain images) is lazy loaded.
shown element:element Triggered after an element is lazy loaded.
shutdown Triggered when all elements have been loaded, or when shutdown() is called.


Inherits all properties from the parent Component.

Property Type Description
container element The element to monitor scroll events on.
element element The element currently being loaded.
items collection A collection of elements to load. These elements are found using the query that instantiated the component.
loaded int A count of how many elements have been loaded.
timer int The load all timer.


Inherits all methods from the parent Component.

Method Description
inViewport(element:element) Check to see if an element is within the viewport or within the threshold.
load() Attempt to load any elements that are off screen but within the threshold.
loadAll() Force load all elements regardless of where they are in the page.
shutdown() Remove all loading events and disable the component. This will not load elements that have not been loaded.