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

<template>
  <div class="page">
    <div class="navbar">
      <div class="navbar-bg"></div>
      <div class="navbar-inner">
        <div class="title">Lazy Load</div>
      </div>
    </div>
    <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 dolor sit amet, consectetur adipiscing elit. Morbi tempus viverra lectus sit amet lobortis.
          Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Quisque faucibus
          consectetur mauris eget lobortis. Maecenas efficitur efficitur mauris ac vehicula. Sed ut lectus laoreet,
          semper nisi vel, maximus massa. Duis at lorem vitae sem auctor condimentum a at neque. Phasellus vel
          scelerisque dui. Morbi varius nibh eu finibus rutrum.</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. Aliquam gravida nulla nec sollicitudin consectetur. Donec iaculis ipsum in purus
          tincidunt sagittis quis vehicula sapien. Vestibulum quis consectetur nibh. Pellentesque vehicula ligula
          sit amet commodo malesuada. Proin eget dolor sodales, egestas sapien sed, consectetur ante. Vivamus
          imperdiet porttitor condimentum. Aliquam sit amet tellus quis mauris dapibus convallis eu in nulla.
          Aliquam erat volutpat.</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 libero a tincidunt. Nunc rhoncus tellus ac congue commodo. Aenean malesuada
          ante sit amet erat efficitur vehicula ac id ipsum. Suspendisse sed purus vel nisl rhoncus feugiat et ut
          ante. Mauris vehicula ligula sed nisl vulputate, nec ullamcorper quam vehicula. Etiam eu turpis eget sem
          luctus rutrum at porta nulla. Ut posuere lorem et nisi faucibus molestie.</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, vel venenatis lacus laoreet. Sed id bibendum ligula, sed congue
          erat. Maecenas rhoncus posuere lorem ac consectetur. Duis accumsan, urna id pharetra tincidunt, libero
          nibh tincidunt enim, vestibulum suscipit turpis neque nec ante.</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. Curabitur et neque ac ante dapibus mollis tempor eget ex. Vivamus porttitor faucibus
          dui. Nulla eleifend hendrerit cursus. Sed elit nulla, pulvinar vitae diam eget, consectetur efficitur
          orci. Vivamus vel pharetra sapien. Suspendisse tortor tortor, iaculis at ullamcorper sit amet, vestibulum
          vel arcu. Aenean sed eleifend sapien. Praesent at varius metus.</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 dolor sit amet, consectetur adipiscing elit. Praesent laoreet nisl eget neque blandit
          lobortis. Sed sagittis risus id vestibulum finibus. Cras vestibulum sem et massa hendrerit maximus.
          Vestibulum suscipit tristique iaculis. Nam vitae risus non eros auctor tincidunt quis vel nulla. Sed
          volutpat, libero ac blandit vehicula, est sem gravida lectus, sed imperdiet sapien risus ut neque.</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. Aliquam gravida nulla nec sollicitudin consectetur. Donec iaculis ipsum in purus
          tincidunt sagittis quis vehicula sapien. Vestibulum quis consectetur nibh. Pellentesque vehicula ligula
          sit amet commodo malesuada. Proin eget dolor sodales, egestas sapien sed, consectetur ante. Vivamus
          imperdiet porttitor condimentum. Aliquam sit amet tellus quis mauris dapibus convallis eu in nulla.
          Aliquam erat volutpat.</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 dolor sit amet, consectetur adipiscing elit. Morbi tempus viverra lectus sit amet lobortis.
          Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Quisque faucibus
          consectetur mauris eget lobortis. Maecenas efficitur efficitur mauris ac vehicula. Sed ut lectus laoreet,
          semper nisi vel, maximus massa. Duis at lorem vitae sem auctor condimentum a at neque. Phasellus vel
          scelerisque dui. Morbi varius nibh eu finibus rutrum.</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 libero a tincidunt. Nunc rhoncus tellus ac congue commodo. Aenean malesuada
          ante sit amet erat efficitur vehicula ac id ipsum. Suspendisse sed purus vel nisl rhoncus feugiat et ut
          ante. Mauris vehicula ligula sed nisl vulputate, nec ullamcorper quam vehicula. Etiam eu turpis eget sem
          luctus rutrum at porta nulla. Ut posuere lorem et nisi faucibus molestie.</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 id enim rutrum, vel venenatis lacus laoreet. Sed id bibendum ligula, sed congue
          erat. Maecenas rhoncus posuere lorem ac consectetur. Duis accumsan, urna id pharetra tincidunt, libero
          nibh tincidunt enim, vestibulum suscipit turpis neque nec ante.</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. Curabitur et neque ac ante dapibus mollis tempor eget ex. Vivamus porttitor faucibus
          dui. Nulla eleifend hendrerit cursus. Sed elit nulla, pulvinar vitae diam eget, consectetur efficitur
          orci. Vivamus vel pharetra sapien. Suspendisse tortor tortor, iaculis at ullamcorper sit amet, vestibulum
          vel arcu. Aenean sed eleifend sapien. Praesent at varius metus.</p>
      </div>
    </div>
  </div>
</template>
<style>
  img.demo-lazy {
    width: 100%;
    height: auto;
    display: block;
  }

  div.demo-lazy {
    background: #aaa;
    background-size: cover;
    height: 60vw;
  }
</style>