Guide · Open source
How to use lazysizes: lazy load images and iframes
Updated · written with AI from the project's own documentation and checked against our catalogue data
lazysizes is a JavaScript script that delays loading images and iframes until they are about to appear on screen, so pages load faster. It is aimed at web developers who add it to their own pages, not at people using a website builder. After this guide you will be able to add lazysizes to a page, mark up images and iframes for lazy loading, and use automatic sizes for responsive images.
lazysizesaFarkas/lazysizes · ★ 17.7k · MIT Install options & downloads Quick start
- 1Install or download lazysizes. Run npm install lazysizes --save, or download lazysizes.min.js from the project's homepage link in the README.
- 2Include the script. Add a script tag with async, or import 'lazysizes' in your JavaScript bundle.
- 3Add the lazyload class. Put class="lazyload" on each img or iframe you want to load lazily.
- 4Replace src with data-src. Move the image or embed URL into data-src, or use data-srcset for responsive images.
- 5Enable automatic sizes if needed. Add data-sizes="auto" to responsive images that use width descriptors, and set a CSS width so the display width can be calculated.
- 6Test in the browser. Load the page, scroll down, and confirm the images appear as they approach the viewport.
Install lazysizes with npm or bower
The README offers two ways to get lazysizes: download the lazysizes.min.js script and include it in your webpage, or install it with a package manager. The project's install method is a package manager, and the README lists no prerequisites.
- npm: install it with the command below
- bower: alternatively use the bower command below
npm install lazysizes --saveInclude the script in your page
If you use a plain HTML page, add a script tag that loads lazysizes.min.js. If you use a bundler, you can import lazysizes in your JavaScript instead. The README warns that you should never import or require the *.min.js files from the npm package when using import.
- Plain HTML: load the script with an async script tag
- JavaScript modules: import 'lazysizes' and optionally import plugins such as 'lazysizes/plugins/parent-fit/ls.parent-fit'
<script src="lazysizes.min.js" async=""></script>Mark up images for lazy loading
lazysizes needs no JavaScript configuration. Add the class lazyload to each img or iframe you want to load lazily, and use data-src or data-srcset in place of src or srcset. You can optionally keep a src attribute with a low quality image as a placeholder.
- Use data-src for a single image
- Use data-srcset with width descriptors (300w, 600w) or pixel density descriptors (1x, 2x) for responsive images
- Add the lazyload class to iframes too, with data-src pointing to the embed URL
<img data-src="image.jpg" class="lazyload" />Use automatic sizes for responsive images
Set data-sizes to auto and lazysizes calculates the sizes attribute from the current display width of the image. This only works with data-srcset that uses width descriptors. The display width must be calculable before the image loads, so an image with width: auto will not work well.
If the calculated width is below 40, which can be changed with the minSize option, lazysizes walks up the DOM tree to a parent that is over 40 and uses that value. A common CSS rule that helps is shown in the bullets.
- Rule suggested by the README: img[data-sizes="auto"] { display: block; width: 100%; }
- You can change the calculated width with the lazybeforesizes event
- The parent fit plugin is the README's option for fitting images to a container, including object-fit cases
<img
data-sizes="auto"
data-srcset="responsive-image1.jpg 300w,
responsive-image2.jpg 600w,
responsive-image3.jpg 900w"
class="lazyload" />Handle browsers that need a polyfill for responsive images
lazysizes builds on the responsive image standard, but the README says full cross-browser responsive image support needs a polyfill. Options it names include picturefill, the respimg polyfill plugin, and the responsive image on demand plugin. Alternatively, you can define a fallback src with data-src and skip the polyfill.
- Full support: a polyfill such as picturefill
- Partial support: the respimg polyfill plugin or the responsive image on demand plugin
- No polyfill: combine data-srcset with data-src as a fallback
What people use it for
- Photo galleries with many images, where images load as the visitor scrolls
- Long article pages with inline images and embedded videos
- Carousels, sliders and infinite scroll lists where content appears after user interaction
- Responsive image markup in which sizes is calculated automatically from the layout
Frequently asked questions
Is lazysizes free to use?
lazysizes is released under the MIT licence, as listed on its project page. The licence text itself is not included in the source provided here, so check the repository for its full terms.
How do I install lazysizes?
The README gives two install commands: npm install lazysizes --save and bower install lazysizes --save. You can also download lazysizes.min.js and include it with a script tag.
Does lazysizes need configuration?
No. According to the README, lazysizes does not need any JavaScript configuration. You add the lazyload class with a data-src or data-srcset attribute to your images and iframes.
Does lazysizes work with responsive images?
Yes. It supports picture and srcset markup and can calculate the sizes attribute automatically with data-sizes="auto". For full cross-browser support, the README says you need a polyfill such as picturefill.
Will lazysizes hurt my SEO?
The README says lazysizes does not hide images from Google, and it reveals all images instantly when the user agent cannot scroll. It describes itself as SEO friendly.
What are the alternatives to lazysizes?
The project lists vanilla-lazyload, lozad.js, yall.js and lazyload as comparable projects. Compare them against your own needs for responsive images and visibility detection.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
lazysizes suits developers who maintain image-heavy pages, galleries, or carousels and want lazy loading with little configuration and automatic sizes for responsive images. It is a poor fit if you need full cross-browser responsive image support without a polyfill, images with a fixed, pre-known width, or a no-code website builder plugin.
Install options & downloads