Lazy loading

Bootstrap 5 Lazy loading

Bootstrap 5 Lazy Loading is a feature, that allows you to load images or videos only when they are visible on the screen.

Note: Read the API tab to find all available options and advanced customization

Basic example

Lazy Loading will automatically initialize after adding .lazy class to your img or video element. It is important to add data-mdb-lazy-src attribute - otherwise, Lazy Load will throw an error.

Scroll down to see an image

Small Apartment
Edit in sandbox 
        
            
          <div class="container lazy mt-5" style="height: 500px; overflow-y: scroll">
            <div class="row text-center" style="height: 800px">
              <p>Scroll down to see an image</p>

              <p><i class="far fa-arrow-alt-circle-down fa-3x my-4"></i></p>

              <img
                data-mdb-lazy-src="https://mdbcdn.b-cdn.net/img/Photos/Slides/img%20(102).webp"
                data-mdb-lazy-placeholder="https://place-hold.it/1321x583?text=Loading"
                alt="Small Apartment"
                class="img-fluid lazy my-3"
                style="margin-top: 50% !important"
              />

              <video
                class="lazy img-fluid"
                data-mdb-lazy-src="https://mdbcdn.b-cdn.net/img/video/Sail-Away.mp4"
                data-mdb-lazy-delay="1000"
                data-mdb-lazy-placeholder="https://place-hold.it/838x471?text=Loading"
                muted="muted"
                autoplay="autoplay"
              ></video>
            </div>
          </div>

Offset

Use data-mdb-lazy-offset attribute to define an additional amount of pixels after which image or video will show.

Scroll more down to load a picture.

Small Apartment
Edit in sandbox 
        
            
          <img
            data-mdb-lazy-src="https://mdbcdn.b-cdn.net/img/Photos/Slides/img%20(102).webp"
            data-mdb-lazy-offset="800"
            data-mdb-lazy-placeholder="https://place-hold.it/1321x583?text=Loading"
            alt="Small Apartment"
            class="img-fluid lazy"
          />

Error

Use data-mdb-lazy-error to define a picture that will show if image or video doesn't load.

Example image
Edit in sandbox 
        
            
          <img
            data-mdb-lazy-src="sample"
            data-mdb-lazy-delay="1000"
            data-mdb-lazy-placeholder="https://place-hold.it/1321x583?text=Loading"
            data-mdb-lazy-error="https://place-hold.it/1321x583?text=Error"
            alt="Example image"
            class="img-fluid lazy"
          />

Animations

Use data-mdb-lazy-animation to specify which animation you want to activate when element loads.

Small Apartment
Small Apartment
Edit in sandbox 
        
            
          <img
            data-mdb-lazy-src="https://mdbcdn.b-cdn.net/img/Photos/Slides/img%20(102).webp"
            data-mdb-lazy-delay="1000"
            data-mdb-lazy-placeholder="https://place-hold.it/1321x583?text=Loading"
            data-mdb-lazy-animation="zoom-in"
            alt="Small Apartment"
            class="img-fluid lazy"
          />
          <img
            data-mdb-lazy-src="https://mdbcdn.b-cdn.net/img/Photos/Slides/img%20(102).webp"
            data-mdb-lazy-delay="1000"
            data-mdb-lazy-placeholder="https://place-hold.it/1321x583?text=Loading"
            data-mdb-lazy-animation="shake"
            alt="Small Apartment"
            class="img-fluid lazy"
          />

Container

Initialize a set of elements at once by adding .lazy class to their container. If you set data-mdb-lazy attributes in the parent, all of img and video elements inside will inherit them. You can overwrite them by declaring these attributes in inner elements.

Example image Small Apartment
Edit in sandbox 
        
            
          <div
            class="container lazy mt-5"
            data-mdb-lazy-placeholder="https://place-hold.it/1321x583?text=Loading"
            data-mdb-lazy-error="https://place-hold.it/1321x583?text=Error"
          >
            <img data-mdb-lazy-src="." alt="Example image" class="img-fluid mb-3" />
            <img data-mdb-lazy-src="https://mdbcdn.b-cdn.net/img/Photos/Slides/img%20(102).webp" alt="Small Apartment" class="img-fluid mb-3"/>
            <video
              class="img-fluid"
              data-mdb-lazy-src="https://mdbcdn.b-cdn.net/img/video/Sail-Away.mp4"
              muted="muted"
              autoplay="autoplay"
            ></video>
          </div>

Lazy loading - API

Usage

Via data attributes

Edit in sandbox 
        
            
        <img
          data-mdb-lazy-src="https://mdbootstrap.com/img/Photos/Slides/img%20(102).webp"
          data-mdb-lazy-delay="1000"
          data-mdb-lazy-placeholder="https://place-hold.it/1321x583?text=Loading"
          data-mdb-lazy-animation="shake"
          alt="Example image"
          class="img-fluid lazy"
        />

Via JavaScript

Edit in sandbox 
        
            
        const lazyElement = new mdb.LazyLoad(document.getElementById('lazyElement'), { 
          lazySrc: '...',
          lazyPlaceholder: '...', 
          lazyError: '...', 
        });

Via jQuery

Note: By default, MDB does not include jQuery and you have to add it to the project on your own.

Edit in sandbox 
        
            
        $(document).ready(() => {
          $('.example-class').lazyLoad(options); 
        });

Options

Options can be passed via data attributes, JavaScript, or jQuery. For data attributes, append the option name to data-mdb-, as in data-mdb-lazy-delay="".

Name Type Default Description
lazySrc String '...' Defines the source of an element
lazyDelay Number 500 Defines delay after which element will show
lazyAnimation String 'fade-in' Defines animation during element showing
lazyOffset Number 0 Defines an additional offset after which element will show
lazyPlaceholder String - Defines a picture that is shown before loading a proper element
lazyError String - Defines a picture that is shown if an error with showing element occurs

Methods

Name Description Example
dispose Removes an instance of the lazy element lazyElement.dispose()
getInstance Static method which allows you to get the lazy load instance associated to a DOM element. LazyLoad.getInstance(lazyLoadEl)
getOrCreateInstance Static method which returns the lazy load instance associated to a DOM element or create a new one in case it wasn't initialized. LazyLoad.getOrCreateInstance(lazyLoadEl)
Edit in sandbox 
        
            
        mdb.LazyLoad.getInstance(document.getElementById('example-element')).dispose();

Events

Name Description
onLoad.mdb.lazy This event fires immediately when an image is loaded.
onError.mdb.lazy This event fires immediately when an error with loading image occurs.
Edit in sandbox 
        
            
        const lazyLoadInstance =
        mdb.lazyLoad.getInstance(document.getElementById('example-element'));
        lazyLoadInstance.addEventListener('onLoad.mdb.lazy', () => {
          // do something
        });

Import

MDB UI KIT also works with module bundlers. Use the following code to import this component:

Edit in sandbox 
        
             import { LazyLoad } from 'mdb-ui-kit';