Responsively Lazy

Responsively Lazy is a dependency-free JavaScript library for lazy-loading responsive images, background images, and HTML blocks using a valid-HTML approach that never removes the src attribute. It reads a data-responsively-lazy attribute listing image versions (with widths and optional WebP/AVIF formats) and requests only the version needed as the element approaches the viewport.

What is Responsively Lazy?

Responsively Lazy is a tiny (2.5kb gzipped and minified) JavaScript library that enhances <img> tags with responsive lazy loading while keeping the HTML valid for search engines, social networks, and older browsers. It takes an image with a normal src (the high-resolution fallback) plus a data-responsively-lazy attribute that lists alternative image versions, and it outputs the best-matching version when the image nears the viewport. The library works in browsers that support srcset (about 97.6% as of December 2023) and is created by Ivo Petkov.

Key Features

• Valid HTML and SEO friendly — The library never removes the src attribute, so search engines and social networks still see a complete image; it also works without <noscript>.
• WebP and AVIF support — In data-responsively-lazy, each image version can declare a format (webp or avif) after its width, and the first format the browser supports is used.
• Customizable load threshold — The data-responsively-lazy-threshold attribute lets you control how close an image must be to the viewport before loading, in pixels or percentages.
• Background image lazy loading — Set data-responsively-lazy-type="background" to lazy-load CSS background images with the same responsive version list.
• HTML block lazy loading — Set data-responsively-lazy-type="html" to lazy-load arbitrary HTML (including JavaScript) into a container.
• Runs on DOM changes — The library observes new content automatically and also exposes a responsivelyLazy.run() method to trigger loading manually.
• Zero dependencies and install flexibility — No external libraries needed; install via npm (npm install responsively-lazy) or include the minified file from a CDN.

Who is it for?

• Front-end developers building content-heavy pages who want to reduce initial image payloads without sacrificing SEO.
• Performance-minded web teams that need automatic handling of responsive images, including next-gen formats like WebP and AVIF.
• CMS and template authors who want a drop-in lazy loading solution that works with existing <img> markup and doesn't require changing the HTML structure.
• Developers working on image-heavy sites such as portfolios, photography blogs, or e-commerce product pages who need background image lazy loading too.

How does Responsively Lazy work?

Include the JavaScript file (via CDN or a local script) and then add a data-responsively-lazy attribute to an <img> tag. The attribute contains comma-separated image versions like images/400.jpg 400w, images/600.jpg 600w. The library uses the srcset attribute as a baseline, calculates the current viewport width, and loads the smallest version that is large enough for the element's displayed size — only when the element gets close to the viewport. It also listens for DOM changes and lets you call responsivelyLazy.run() to re-scan the page.

Use cases

• High-traffic blogs and news sites: Serve appropriately sized images to readers on mobile vs. desktop while keeping the default src for crawlers.
• Photography portfolios: Lazy-load background images and gallery thumbnails to speed up initial page load and save bandwidth.
• E-commerce stores: Support WebP/AVIF product images with a fallback src for older browsers and social sharing bots.
• Single-page apps: Trigger lazy loading on dynamically injected content via the built-in DOM change listener and responsivelyLazy.run().

FAQ

Does Responsively Lazy work without JavaScript?

No. The lazy loading itself requires JavaScript and browsers that support srcset (about 97.6% as of December 2023). If JavaScript is disabled or the browser doesn't support srcset, the image in the src attribute is displayed instead, which is why the page recommends keeping a high-resolution image there.

Is Responsively Lazy free?

Yes. The library is released under the MIT license, so it is free to use in personal and commercial projects. No pricing tiers or paid features are mentioned on the page.

How do I specify WebP or AVIF images?

In the data-responsively-lazy attribute, append the format after each version's size: images/400.avif 400w avif, images/400.webp 400w webp, images/400.jpg 400w. The browser's first supported format for the chosen width is used, giving you automatic fallback behavior.

Does Responsively Lazy work with background images?

Yes. Set data-responsively-lazy-type="background" on an element and provide the same comma-separated list of versions with widths. The library will load the background image responsively when the element approaches the viewport.

Can I lazy load HTML content?

Yes. Set data-responsively-lazy-type="html" and put the HTML (even with JavaScript) inside the data-responsively-lazy attribute. The library will inject it when the element is near the viewport.