Lazy loads images with IntersectionObserver


stars 🌟issues ⚠️updated 🛠created 🐣size 🏋️‍♀️
387Jun 11, 2021Mar 14, 2018Minified + gzip package size for @power-elements/lazy-image in KB


Published on webcomponents.org npm (scoped) Build Status Contact me on Codementor


Lazily load your images!

🚛 Get it!

npm -i -S @power-elements/lazy-image

📦 Load it!

<!-- From CDN -->
<script async type="module" src="https://unpkg.com/@power-elements/lazy-image/lazy-image.js"></script>

<!-- From local installation -->
<script async type="module" src="/node_modules/@power-elements/lazy-image/lazy-image.js"></script>

<!-- In a Module -->
<script type="module">
  import '/node_modules/@power-elements/lazy-image/lazy-image.js';
  // ...

💪 Use it!

<lazy-image src="image.jpg" alt="Lazy Image">
  <svg slot="placeholder"><use xlink:href="#placeholder-svg"></use></svg>

The optional placeholder could be any element. Inline SVG, Pure CSS graphics, or an <img src="data:foo"/> would work best.

💄 Style it!

You should give your <lazy-image> elements some specific dimensions, since it absolutely positions its shadow children. In most cases, you should set the wrapping element as well as the --lazy-image- custom properties to the known display dimensions of your image.

html {
  --lazy-image-width: 640px;
  --lazy-image-height: 480px;

lazy-image {
  width: var(--lazy-image-width);
  height: var(--lazy-image-height);

<lazy-image src="https://fillmurray.com/640/480"></lazy-image>

<lazy-image> exposes a set of custom properties for your customizing delight:

Property Purpose Default
--lazy-image-width Width of the internal image and placeholder elements 100%
--lazy-image-height Height of the internal image and placeholder elements 100%
--lazy-image-fit object-fit property of the internal image and placeholder elements contain
--lazy-image-fade-duration Duration of the fade in from the placeholder to the image. Set to 0 to disable fading. 0.3s
--lazy-image-fade-easing ease property of the opacity transition for the image and placeholder ease

Browser support

lazy-image manages the loading of your images via an Intersection Observer. In browsers where an Intersection Observer is not present, your images will be loaded immediately much like standard <img/> elements. Conditionally delivering the IntersectionObserver polyfill along with your lazy-images to your users will ensure that all users experience the benefits of loading images lazily. Stay lazy, friend!

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.