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

Required ES init: LazyLoad *
* UMD autoinits are enabled by default. This means that you don't need to initialize the component manually. However if you are using MDBootstrap ES format then you should pass the required components to the initMDB method.

Basic example

Lazy Loading will automatically initialize after adding data-mdb-lazy-load-init attribute 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 mt-5" data-mdb-lazy-load-init 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-load-init
                  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 my-3"
                  style="margin-top: 50% !important"
                />

                <video
                  class="img-fluid"
                  data-mdb-lazy-load-init
                  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>
          
        
    
        
            
            // Initialization for ES Users
            import { LazyLoad, initMDB } from "mdb-ui-kit";
            
            initMDB({ LazyLoad });

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-load-init
              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"
            />
          
        
    
        
            
            // Initialization for ES Users
            import { LazyLoad, initMDB } from "mdb-ui-kit";
            
            initMDB({ LazyLoad });

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-load-init
                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"
              />
            
        
    
        
            
              // Initialization for ES Users
              import { LazyLoad, initMDB } from "mdb-ui-kit";
              
              initMDB({ LazyLoad });

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-load-init
                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"
              />
              <img
                data-mdb-lazy-load-init
                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"
              />
            
        
    
        
            
              // Initialization for ES Users
              import { LazyLoad, initMDB } from "mdb-ui-kit";
              
              initMDB({ LazyLoad });

Container

Initialize a set of elements at once by adding data-mdb-lazy-load-init attribute to their container. If you set options with with 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 mt-5"
                data-mdb-lazy-load-init
                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>
            
        
    
        
            
              // Initialization for ES Users
              import { LazyLoad, initMDB } from "mdb-ui-kit";
              
              initMDB({ LazyLoad });

Lazy loading - API

Import

Importing components depends on how your application works. If you intend to use the MDBootstrap ES format, you must first import the component and then initialize it with the initMDB method. If you are going to use the UMD format, just import the mdb-ui-kit package.

Edit in sandbox 
        
            
            import { LazyLoad, initMDB } from "mdb-ui-kit";
            initMDB({ LazyLoad });
          
        
    
        
            
            import 'mdb-ui-kit';

Usage

Via data attributes

Using the Lazy Load method doesn't require any additional JavaScript code - simply add data-mdb-lazy-load-init attribute to container element and use other data attributes to set all options. For ES format, you must first import and call the initMDB method.

Edit in sandbox 
        
            
            <img
              data-mdb-lazy-load-init
              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"
            />

Via JavaScript

Edit in sandbox 
        
            
            const lazyElement = new LazyLoad(document.getElementById('lazyElement'), { 
              lazySrc: '...',
              lazyPlaceholder: '...', 
              lazyError: '...', 
            });
          
        
    
        
            
            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 or JavaScript. For data attributes, append the option name to data-mdb-, as in data-mdb-lazy-src="".

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 
        
            
          const lazyLoadEl = document.getElementById('element');
          const lazyLoad = new LazyLoad(lazyLoadEl);
          lazyLoad.dispose();
          
        
    
        
            
          const lazyLoadEl = document.getElementById('element');
          const lazyLoad = new mdb.LazyLoad(lazyLoadEl);
          lazyLoad.dispose();

Events

Name Description
contentLoaded.mdb.lazyLoad This event fires after an image is loaded.
loadingError.mdb.lazyLoad This event fires when an error with loading image occurs.
Edit in sandbox 
        
            
        const lazyLoadEl = document.getElementById('element');
        lazyLoadEl.addEventListener('contentLoaded.mdb.lazyLoad', () => {
          // do something
        });