Lazy Image

The "Lazy Image" component is a dead simple component to lazy load images.

It leverages the native lazy-loading when available and the IntersectionObserver API as fallback to lazy load images. It also allows you to trigger "manually" their loading.

An <img/> tag is per default use to display the image but optionally it could parse SVG too.

Table of contents


This component could be added to your web application using the following methods.

If you are using our Starter Kit this template is included. You don't need to install it so therefore you should skip the "Installation" chapter.

Using from a CDN

It's recommended to use unpkg to use the DeckDeckGo lazy image component from a CDN. To do so, add the following include script in the main HTML file of your project:

<script type="module" src=""></script> <script nomodule="" src=""></script>

Install from NPM

Install it in your project from npm using the following command:

npm install @deckdeckgo/lazy-img

Framework integration

The Stencil documentation provide examples of framework integration for Angular, React, Vue and Ember.

That being said, commonly, you might either import or load it:


import '@deckdeckgo/lazy-img';


import { defineCustomElements as deckDeckGoElement } from '@deckdeckgo/lazy-img/dist/loader'; deckDeckGoElement();


The "Lazy Image" Web Component could be integrated using the tag <deckgo-lazy-img/>.

<deckgo-lazy-img img-src="/assets/twitter.svg"> </deckgo-lazy-img>


No slots are available for this component.


This component offers the following options which could be set using attributes:

img-srcstringThe image source (= URI) to lazy load
img-src-setstringThe attribute "srcset" (= multiple URI) to lazy load in case you would like to provide multiple images for responsiveness
img-error-srcstringAn optional image which could be displayed in case the main image would not be resolved
img-sizesstringThe set of media conditions to indicates what image size would be best to choose
img-altstringThe image alternate text
img-widthnumberThe image width
img-heightnumberThe image height
svg-srcstringThe SVG image source (= URI) to lazy load and to parse (no <img/> tag will be use to render the svg)
aria-labelstringIf you are using the above SVG option, provide the accessibility information using this attribute
observer-root-marginstring100px 0pxA string which specifies a set of offsets to add to the root's bounding_box when calculating intersections, effectively shrinking or growing the root for calculation purposes. More info.
observer-thresholdnumber or number[]Either a single number or an array of numbers between 0.0 and 1.0, specifying a ratio of intersection area to total bounding box area for the observed target. More info.
intrinsicsizestringAn intrinsicsize for the native lazy-loading (see Native lazy-loading for the web)
custom-loaderbooleanIn case you would like to take care by yourself to apply the load of the image. If turn to true then the component will emit an event customLoad when the image intersect the viewport instead of displaying it (doesn't apply for svg but only for img-src and img-src-set)


The following theming options will affect this component if set on its host or parent.

CSS4 variableDefaultNote
--deckgo-lazy-img-max-heightImage max height
--deckgo-lazy-img-max-width100%Image max width
--deckgo-lazy-img-min-heightImage min height
--deckgo-lazy-img-min-widthImage min width
--deckgo-lazy-img-pointer-eventsnoneImage pointer events
--deckgo-lazy-img-heightImage height
--deckgo-lazy-img-widthImage width
--deckgo-lazy-img-floatImage float
--deckgo-lazy-img-paddingImage padding
--deckgo-lazy-img-vertical-alignImage vertical alignment
--deckgo-lazy-img-displayThe display property of the image
--deckgo-lazy-img-border-radiusIn case you would like to specify a border radius for the image
--deckgo-lazy-img-object-fitThe property object-fit of the image
--deckgo-lazy-img-opacity-not-loaded0The opacity of the image when not loaded
--deckgo-lazy-img-opacity-loaded1The opacity of the image when loaded
--deckgo-lazy-img-transitionopacity 0.15s linearThe animation of the image, notably use to display smoothly the image when loaded
--deckgo-lazy-img-box-shadowImage box-shadow


This component also export an async method lazyLoad() in case you would like to trigger "manually" the loading of the image.

const element = document.querySelector('deckgo-lazy-img'); await element.lazyLoad();


The <deckgo-lazy-img/> will bubble the following events:

customLoadEmitted if component property custom-loader is set to true and if an image (img-src or img-src-set) as to be loaded.CustomEvent<DeckDeckGoCustomLoad>

Where DeckDeckGoCustomLoad contains the shadowed image element and both information img-src and img-src-set.


In case the browser would not support the native native lazy-loading or the Intersection Observer API, images are going to be loaded without any delay when the component load respectively if the browser does not implement the Intersection Observer API images are displayed and not lazy loaded.

Trying it out

This component lazy load images when these are not presented in the viewport. If you would use this component in a simple test containing only a couple of images, respectively no content or no real use case where the images are effectively offscreen, assign a default height to components in order to ensure that some are effectively placed outside of the window [#128].