@nuclei-components/lazy-picture
v0.3.3
Published
A lazy loading picture element
Downloads
5
Maintainers
Readme
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.