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
*
* 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
.webp)
<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.
<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.
<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.
<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.
<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.
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.
<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
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.
$(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 | null | null |
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 | undefined | undefined |
Defines a picture that is shown before loading a proper element |
lazyError
|
String | undefined | undefined |
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)
|
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. |
const lazyLoadEl = document.getElementById('element');
lazyLoadEl.addEventListener('contentLoaded.mdb.lazyLoad', () => {
// do something
});