vanilla-lazyload

When upgrading from version 12 to 13, replace callback_set with callback_reveal. While callback_set may still work temporarily, it is deprecated and scheduled for removal.

// FROM
new LazyLoad({ /* other options? */ callback_set: () => {} });
// TO
new LazyLoad({ /* other options? */ callback_reveal: () => {} });

To prevent layout shifts (CLS) when images or videos load, ensure they occupy space before they are loaded. If elements shrink to zero-height before loading, the layout will shift, making lazy loading inefficient.

Best Practices:

1. Set both width and height attributes on img and video elements.
2. If not using a placeholder image, apply display: block to every image via CSS.

To lazy load background images on elements like <div>, use the following data- attributes:

• data-bg: For a single background image.
• data-bg-hidpi: For HiDPI/Retina support.
• data-bg-multi: For multiple background images (comma-separated).
• data-bg-multi-hidpi: For multiple backgrounds with HiDPI support.
• data-bg-set: For using the CSS image-set() pattern.

Note: For SEO and accessibility, prefer using <img> tags for content images instead of background images.

When upgrading from version 15 to 16, apply the following changes:

Replace callback_reveal

Replace the callback_reveal callback with callback_loading.

Update load(element) method usage

The instance method load(element) has been replaced by a static method LazyLoad.load(element, settings). Note that the settings object can differ from your instance settings; if none are provided, defaults apply.

// FROM
myLazyLoad.load(element);

// TO
LazyLoad.load(element, {
  /* options here */
});

Replace auto_unobserve

Replace the auto_unobserve option with unobserve_completed.

const myLazyLoad = new LazyLoad({
  // FROM
  auto_unobserve: false,
  // TO
  unobserve_completed: false
});

Replace load_delay

Replace load_delay: ___ with cancel_on_exit: true.

LazyLoad supports various media types using specific data- attributes:

• Animated SVGs: Use the <object> tag with data-src.
• Videos: Use the <video> tag. You can lazy load the video source via <source data-src="..."> and the poster via data-poster="...".
• Iframes: Use the <iframe> tag with data-src.

<!-- Animated SVG -->
<object class="lazy" type="image/svg+xml" data-src="lazy.svg"></object>

<!-- Video -->
<video class="lazy" controls width="620" data-src="lazy.mp4" data-poster="lazy.jpg">
  <source type="video/mp4" data-src="lazy.mp4" />
  <source type="video/ogg" data-src="lazy.ogg" />
</video>

<!-- Iframe -->
<iframe class="lazy" data-src="lazyFrame.html"></iframe>

To optimize performance when dealing with many large containers (like horizontal scrolling rows), you can use a 'master' LazyLoad instance to observe the containers themselves. When a container enters the viewport, the callback_enter trigger can then instantiate a new LazyLoad instance specifically for that container.

var lazyLoadInstances = [];

var initOneLazyLoad = function (horizContainerElement) {
  var oneLL = new LazyLoad({
    container: horizContainerElement
  });
  lazyLoadInstances.push(oneLL);
};

// The 'master' instance observing the containers
var lazyLazy = new LazyLoad({
  elements_selector: ".horizContainer",
  callback_enter: initOneLazyLoad,
  unobserve_entered: true // Stop observing the container after it is initialized
});

When upgrading from version 13 to 14, replace callback_reveal with callback_loading. While callback_reveal may still work temporarily, it is deprecated and scheduled for removal.

// FROM
new LazyLoad({ /* other options? */ callback_reveal: () => {} });
// TO
new LazyLoad({ /* other options? */ callback_loading: () => {} });

When upgrading from version 16 to 17, follow these steps depending on your current implementation:

Target elements for lazy loading

If you were not previously setting the elements_selector option, you must now add the lazy class to your lazy images:

<!-- FROM -->
<img data-src="lazyImage.jpg" alt="Lazy image" />
<!-- TO -->
<img class="lazy" data-src="lazyImage.jpg" alt="Lazy image" />

Alternatively, you can configure the library to target all img tags by setting the elements_selector option:

const myLazyLoad = new LazyLoad({
  /* other options here */
  elements_selector: "img"
});

Remove cancel_on_exit

If you were using the cancel_on_exit: true option, you must remove it from your settings.

The project provides over 30 demos covering various use cases, including:

• Content Types: Basic images, images with inline/external SVG placeholders, responsive images (srcset, sizes, <picture> tag), background images (including image-set()), videos (with/without autoplay), iframes, and animated SVGs/PDFs.
• Loading Techniques: Asynchronous loading with <script async>, native lazy loading (conditional via use_native), and fading in images.
• Advanced Techniques: Lazy loading in CSS-only sliders, integrating with Swiper, executing functions when elements enter the viewport, and managing print layouts.
• API Methods: Using restore(), destroy(), update(), load(), and loadAll().
• Settings: Handling multiple or single scrolling containers.

You can find the source code for these demos in the demos folder of the repository.