Tailwind CSS Lazy loading

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

Basic example

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

Scroll down to see an image

HTML
javascript

        
            
      <div
        class="mt-5 h-[500px] w-full overflow-y-scroll"
        data-te-lazy-load-init>
        <div class="grid h-[800px] place-items-center">
          <p>Scroll down to see an image</p>
          <p class="my-4">
            <svg
              xmlns="http://www.w3.org/2000/svg"
              fill="none"
              viewBox="0 0 24 24"
              stroke-width="1.5"
              stroke="currentColor"
              class="h-16 w-16">
              <path
                stroke-linecap="round"
                stroke-linejoin="round"
                d="M9 12.75l3 3m0 0l3-3m-3 3v-7.5M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
            </svg>
          </p>

          <img
            data-te-lazy-load-init
            data-te-lazy-src="https://tecdn.b-cdn.net/img/Photos/Slides/img%20(102).webp"
            data-te-lazy-placeholder="https://place-hold.it/1321x583?text=Loading"
            alt="Small Apartment"
            class="my-5 !mt-[50%] w-full" />

          <video
            class="w-full"
            data-te-lazy-load-init
            data-te-lazy-src="https://tecdn.b-cdn.net/img/video/Sail-Away.mp4"
            data-te-lazy-delay="1000"
            data-te-lazy-placeholder="https://place-hold.it/838x471?text=Loading"
            muted="muted"
            autoplay="autoplay"></video>
        </div>
      </div>

        
            
      // Initialization for ES Users
      import {
        LazyLoad,
        initTE,
      } from "tw-elements";
      
      initTE({ LazyLoad });

Hey there 👋 we want to make TW elements a community-driven project. It's open source and free, and we would like it to stay that way. If you enjoy it, help the project grow by sharing it with your peers. Every share counts, thank you!

Share via Reddit Share via StumbleUpon

Offset

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

Scroll more down to load a picture.

HTML
javascript

        
            
      <img
        data-te-lazy-load-init
        data-te-lazy-src="https://tecdn.b-cdn.net/img/Photos/Slides/img%20(102).webp"
        data-te-lazy-delay="1000"
        data-te-lazy-offset="500"
        data-te-lazy-placeholder="https://place-hold.it/1321x583?text=Loading"
        alt="Small Apartment"
        class="w-full" />

        
            
      // Initialization for ES Users
      import {
        LazyLoad,
        initTE,
      } from "tw-elements";
      
      initTE({ LazyLoad });

Error

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

HTML
javascript

        
            
      <img
        data-te-lazy-load-init
        data-te-lazy-src="sample"
        data-te-lazy-delay="1000"
        data-te-lazy-placeholder="https://place-hold.it/1321x583?text=Loading"
        data-te-lazy-error="https://place-hold.it/1321x583?text=Error"
        alt="Small Apartment"
        class="w-full" />

        
            
      // Initialization for ES Users
      import {
        LazyLoad,
        initTE,
      } from "tw-elements";
      
      initTE({ LazyLoad });

Animations

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

HTML
javascript

        
            
      <img
        data-te-lazy-load-init
        data-te-lazy-src="https://tecdn.b-cdn.net/img/Photos/Slides/img%20(102).webp"
        data-te-lazy-delay="1000"
        data-te-lazy-placeholder="https://place-hold.it/1321x583?text=Loading"
        data-te-lazy-animation="[zoom-in_1s_ease-in-out]"
        alt="Small Apartment"
        class="mb-3 w-full" />

      <img
        data-te-lazy-load-init
        data-te-lazy-src="https://tecdn.b-cdn.net/img/Photos/Slides/img%20(102).webp"
        data-te-lazy-delay="1000"
        data-te-lazy-placeholder="https://place-hold.it/1321x583?text=Loading"
        data-te-lazy-animation="[tada_1s_ease-in-out]"
        alt="Small Apartment"
        class="w-full" />

        
            
      // Initialization for ES Users
      import {
        LazyLoad,
        initTE,
      } from "tw-elements";
      
      initTE({ LazyLoad });

Container

Initialize a set of elements at once by adding data-te-lazy-load-init attribute to their container. If you set data-te-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.

HTML
javascript

        
            
      <div
        data-te-lazy-load-init
        data-te-lazy-placeholder="https://place-hold.it/1321x583?text=Loading"
        data-te-lazy-error="https://place-hold.it/1321x583?text=Error">
        <img
          data-te-lazy-src="."
          data-te-lazy-delay="1000"
          alt="Small Apartment"
          class="mb-3 w-full" />
        <img
          data-te-lazy-src="https://tecdn.b-cdn.net/img/Photos/Slides/img%20(102).webp"
          data-te-lazy-delay="1000"
          data-te-lazy-animation="[tada_1s_ease-in-out]"
          alt="Small Apartment"
          class="mb-3 w-full" />
        <video
          class="w-full"
          data-te-lazy-src="https://tecdn.b-cdn.net/img/video/Sail-Away.mp4"
          data-te-lazy-animation="[zoom-in_1s_ease-in-out]"
          muted="muted"
          autoplay="autoplay"></video>
      </div>

        
            
      // Initialization for ES Users
      import {
        LazyLoad,
        initTE,
      } from "tw-elements";
      
      initTE({ LazyLoad });

Import

Importing components depends on how your application works. If you intend to use the TW elements ES format, you must first import the component and then initialize it with the initTE method. If you are going to use the UMD format, just import the tw-elements package.

javascript
umd

ES UMD

        
            
        import { LazyLoad, initTE } from "tw-elements";
        initTE({ LazyLoad });

        
            
        import "tw-elements";

Usage

Via data attributes

Simply add data-te-lazy-load-init attribute to the image to initialize the lazy loading component. For ES format, you must first import and call the initTE method.

HTML

        
            
        <img
          data-te-lazy-load-init
          data-te-lazy-src="https://tecdn.b-cdn.net/img/Photos/Slides/img%20(102).webp"
          data-te-lazy-placeholder="https://place-hold.it/1321x583?text=Loading"
          alt="Small Apartment"
          class="my-5 w-full" />

Via JavaScript

javascript
umd

ES UMD

        
            
        const myLazyLoading = new LazyLoad(document.getElementById('lazy-loading'), options);

        
            
        const myLazyLoading = new te.LazyLoad(document.getElementById('lazy-loading'), options);

Options

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

Name	Type	Default	Description
`lazyAnimation`	String	`'[fade-in_1s_ease-in-out]'`	Defines animation during element showing. Don't forget to include the animation in object `safelist` in `theme` of your `tailwind.config.js` file.
`lazyDelay`	Number	`500`	Defines delay after which element will show.
`lazyError`	String	`-`	Defines a picture that is shown if an error with showing element occurs.
`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.
`lazySrc`	String	`-`	Defines the source of an element.

Methods

Method	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)`

javascript
umd

ES UMD

        
            
        const myLazyLoadingEl = document.getElementById('myLazyLoading');
        const lazyLoading = new LazyLoad(myLazyLoadingEl);
        lazyLoading.dispose();

        
            
        const myLazyLoadingEl = document.getElementById('myLazyLoading');
        const lazyLoading = new te.LazyLoad(myLazyLoadingEl);
        lazyLoading.dispose();

Events

Event type	Description
`onLoad.te.lazy`	This event fires immediately when an image is loaded.
`onError.te.lazy`	This event fires immediately when an error with loading image occurs.

JavaScript

        
            
        const myLazyLoadingEl = document.getElementById('myLazyLoad')
        myLazyLoadingEl.addEventListener('onLoad.te.lazy', function (e) {
            // do something...
        })

Tailwind Lazy loading method

Basic example

Offset

Error

Animations

Container

Tailwind Lazy loading method - API

Import

Usage

Via data attributes

Via JavaScript

Options

Methods

Events

Tailwind Lazy loading method

Tailwind CSS Lazy loading

Basic example

Offset

Error

Animations

Container

Related resources

Tailwind Lazy loading method - API

Import

Usage

Via data attributes

Via JavaScript

Options

Methods

Events