Lazy Load

Usage

With Images
With Background Images
With Fade-in Effect

Lazy Load App Parameters
Lazy Load App Methods
Lazy Load Events

DOM Events
App Instance Events

Trigger Lazy Load Manually
Examples

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:

specify image source into data-src attribute instead of src attribute
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:

specify element's background image source into data-background
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:

Parameter	Type	Default	Description
placeholder	string		Lazy load image placeholder source to show while image is not yet loaded. By default it is 1x1 px image
threshold	number	0	By 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
sequential	boolean	true	If enabled, then lazy images will be loaded one by one when they appear in viewport
observer	boolean	true	If 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

Event	Target	Description
lazy:load	Lazy Element<... class="lazy">	Event will be triggered in the beginning of image file loading
lazy:loaded	Lazy Element<... class="lazy">	Event will be triggered after image file successfully loaded
lazy:error	Lazy 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.

Event	Target	Arguments	Description
lazyLoad	app	lazyEl	Event will be triggered in the beginning of image file loading. As an argument it receives lazy loading HTML element
lazyLoaded	app	lazyEl	Event will be triggered after image file successfully loaded. As an argument it receives lazy loading HTML element
lazyError	app	lazyEl	Event 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>