Lazy Load

Lazy Load delays loading of images on page while they are outside of viewport until user scrolls to them.

It will make the page load faster, improve scrolling performance and also save traffic.

Note, that lazy images and elements should be inside of scrollable <div class="page-content"> to work correctly

Usage

With Images

To use lazy load on images:

  1. specify image source into data-src attribute instead of src attribute
  2. add lazy class to the image
<div class="page-content">
  ...
  <img data-src="path/to/image.jpg" class="lazy">
  ...
</div>
After lazy image successfully loaded, or in case of error loading the image file, the lazy class will be replaced with lazy-loaded class.

With Background Images

It is also possible to use lazy load for background images, in this case:

  1. specify element's background image source into data-background
  2. add lazy class to element
<div class="page-content">
  ...
  <div data-background="path/to/image.jpg" class="lazy">
      ...
  </div>
  ...
</div>
After lazy image successfully loaded, or in case of error loading the image file, the lazy class will be replaced with lazy-loaded class.

With Fade-in Effect

If you want to add fade-in effect when image is loaded, you need to add additional lazy-fade-in class to image/element:

<div class="page-content">
  ...
  <img data-src="path/to/image.jpg" class="lazy lazy-fade-in">
  <div data-background="path/to/image.jpg" class="lazy lazy-fade-in">
      ...
  </div>
  ...
</div>

Lazy Load App Parameters

It is possible to control some default lazy loading behavior using global app parameters by passing lazy loading related parameters under lazy parameter:

ParameterTypeDefaultDescription
placeholderstringLazy load image placeholder source to show while image is not yet loaded. By default it is 1x1 px image
thresholdnumber0By default images are loaded when they appear on the screen. Use this parameter if you want to load images earlier. Setting it to 50 will load image when it 50 pixels before it appears on viewport
sequentialbooleantrueIf enabled, then lazy images will be loaded one by one when they appear in viewport
observerbooleantrueIf enabled, it will use Intersection Observer if it is supported by browser.

For example:

var app = new Framework7({
  lazy: {
    threshold: 50,
    sequential: false,
  },
});

Lazy Load App Methods

If you add lazy load images manually after page initialization (e.g. after Ajax request) then Lazy Load won't be initialized automatically and won't work as expected. In this case you need to init it manually using the following method:

app.lazy.create(pageEl) - initialize lazy loading on page

  • pageEl - HTMLElement or string (with CSS Selector) of page which contains lazy load images. Required.

And if you want to destroy/disable it later:

app.lazy.destroy(pageEl) - destroy/disable lazy loading on page

  • pageEl - HTMLElement or string (with CSS Selector) of page which contains lazy load images. Required.

If you want to force any lazy image/element to load you may use the following method:

app.lazy.loadImage(imageEl, callback) - force to load lazy image

  • imageEl - HTMLElement or string (with CSS Selector) of lazy image or element (element with lazy class). Required.
  • callback - function - callback function that will be executed when image file loaded or in case of error loading this file.

Lazy Load Events

Lazy load will fire the following DOM events on lazy element and events on app instance:

DOM Events

EventTargetDescription
lazy:loadLazy Element<... class="lazy">Event will be triggered in the beginning of image file loading
lazy:loadedLazy Element<... class="lazy">Event will be triggered after image file successfully loaded
lazy:errorLazy Element<... class="lazy">Event will be triggered in case of error loading image file

App Instance Events

Lazy load emits events on app instance as well.

EventTargetArgumentsDescription
lazyLoadapplazyElEvent will be triggered in the beginning of image file loading. As an argument it receives lazy loading HTML element
lazyLoadedapplazyElEvent will be triggered after image file successfully loaded. As an argument it receives lazy loading HTML element
lazyErrorapplazyElEvent will be triggered in case of error loading image file. As an argument it receives lazy loading HTML element

Trigger Lazy Load Manually

It is possible to force lazy handler to check lazy images by triggering lazy event on lazy image/element. It is useful in case you have added lazy elements dynamically and want to check should them be loaded or not without scrolling the page. For example:

$$('img.lazy').trigger('lazy');
$$('div.lazy').trigger('lazy');

Examples

img.demo-lazy {
  width: 100%;
  height: auto;
  display: block;
}
div.demo-lazy {
  background: #aaa;
  background-size: cover;
  height: 60vw;
}
<div class="page-content">
  <div class="block block-strong">
    <p> <img data-src="https://cdn.framework7.io/placeholder/nature-500x500-1.jpg" width="1500" height="1500" class="lazy lazy-fade-in demo-lazy"/></p>
    <p>Lorem ipsum ...</p>
    <p> <img data-src="https://cdn.framework7.io/placeholder/nature-500x500-2.jpg" width="1500" height="1500" class="lazy lazy-fade-in demo-lazy"/></p>
    <p>Aenean id congue orci...</p>
    <p> <img data-src="https://cdn.framework7.io/placeholder/nature-500x500-3.jpg" width="1500" height="1500" class="lazy lazy-fade-in demo-lazy"/></p>
    <p>Pellentesque aliquam maximus ...</p>
    <p> <img data-src="https://cdn.framework7.io/placeholder/nature-500x500-4.jpg" width="1500" height="1500" class="lazy lazy-fade-in demo-lazy"/></p>
    <p>Duis ullamcorper velit id enim rutrum...</p>
    <p> <img data-src="https://cdn.framework7.io/placeholder/nature-500x500-5.jpg" width="1500" height="1500" class="lazy lazy-fade-in demo-lazy"/></p>
    <p>Suspendisse potenti...</p>
    <p> <img data-src="https://cdn.framework7.io/placeholder/nature-500x500-6.jpg" width="1500" height="1500" class="lazy lazy-fade-in demo-lazy"/></p>
    <p>Lorem ipsum ...</p>
    <p> <img data-src="https://cdn.framework7.io/placeholder/nature-500x500-7.jpg" width="1500" height="1500" class="lazy lazy-fade-in demo-lazy"/></p>
    <p>Aenean id congue orci...</p>
    <p> <img data-src="https://cdn.framework7.io/placeholder/nature-500x500-8.jpg" width="1500" height="1500" class="lazy lazy-fade-in demo-lazy"/></p>
    <p>Lorem ipsum ...</p>
    <p> <img data-src="https://cdn.framework7.io/placeholder/people-500x500-1.jpg" width="1500" height="1500" class="lazy lazy-fade-in demo-lazy"/></p>
    <p>Pellentesque aliquam maximus ...</p>
    <p> <img data-src="https://cdn.framework7.io/placeholder/nature-500x500-10.jpg" width="1500" height="1500" class="lazy lazy-fade-in demo-lazy"/></p>
    <p>Duis ullamcorper velit...</p>
    <p><b>Using as background image:</b></p>
    <div data-background="https://cdn.framework7.io/placeholder/people-500x500-10.jpg" class="lazy lazy-fade-in demo-lazy"></div>
    <p>Suspendisse potenti...</p>
  </div>
</div>