@nuclei-components/lazy-picture

Lazy Picture

Installation

Simply install the lazy-picture component using npm.

$ npm i -S @nuclei-components/lazy-picture

Usage

To use the webcomponent you need to load it into your page, either by bundling it into your js bundle or by simply loading it via a script tag.

<script src="../dist/lazyPicture.js"></script>

As the support for webcomponents is already pretty good, if you need IE/Edge you will want to load a polyfill before loading the webcomponent.

I recommend the webcomponentsjs. To make sure the webcomponent is only loaded once the polyfill is done (when using the webcomponents-loader.js) you will want to wait for the WebComponentsReady event before loading the web component. This event is always fired, even in browser that fully support web components.

<script type="text/javascript" async>
  window.addEventListener('WebComponentsReady', function () {
    let script = document.createElement('script')
    script.setAttribute('src', '../dist/lazyPicture.js')
    document.head.appendChild(script)
  })
</script>

src

This is the default image source. When non of the <source> tags media queries fit, the browser will choose this image to display.

alt

This is the alternative text that is added to the image in case it does not load or a user views this with a screen reader.

Active

If active is set to true the image will be lazy-loaded immediately, even when not in view.

Threshold

If you use the load when in viewport functionality, you can use the threshold property to define how much of the image needs to be visible in the viewport to trigger a load event. The default is 0, so as soon as 1px of the the offset is in the viewport, the image will be loaded.

Offset

The offset property defines at what distance from the visible viewport, the image will be loaded. The default offset of 100px means that as soon as the images is within 100px of the viewport, it will be loaded. Set the offset to 0 to disable it.

Object fit

The fit property allows you to set the object-fit css property on the image element. Alternatively you can define the --lazy-picture-object-fit css custom property to set the object-fit. Make sure to NOT set the fit property if you want to define the object-fit via the css property. The default value is cover.

Events

loaded

When an image is loaded the loaded event is fired. The event has the following details:

detail: {
  src: …, // the source of the image (either the default from the src attribute or any of the <source> tags)
  width: …, // the original width of the image
  height: … // the original height of the image
}

Polyfill for IntersectionObserver

This packages uses the IntersectionObserver to detect if an image is in the viewport or not. If you want to use this in browsers that do not support the IntersectionObserver you need to include a polyfill: https://github.com/WICG/IntersectionObserver/tree/gh-pages/polyfill

If you want to use this package just for its lazy-loading or if you build your own detection which triggers loading by setting active to true, you do not need to use the polyfill.