Download the PHP package styletools/lazy without Composer

$lazy Lazy Loader

A lightweight and high performance lazy loader and element-in-view callback based on Intersection Observer V2 with an efficient polyfill for old browsers.

$lazy can be configured using an async script element.

The script element accepts the following parameters:

When using $async, $lazy can be used as a timing method with automated polyfill loading.

Documentation is available on pagespeed.pro/lazy.

Install via npm

Description

$lazy is designed as the ultimate lazy loader and element-in-view callback for frontend optimization (FEO). It provides state of the art features such as client-side Google .webp rewrite, the absolute best performance and the tiniest HTML footprint. $lazy supports all browsers including iPhone5 and IE9+. IE8 would be supported but isn't supported by Google's IntersectionObserver polyfill.

• 100% JSON control.
• tiny: the $z() version is merely 300 bytes in size.
• support for old browsers with a 0% performance hit for modern browsers.

Advanced control of IntersectionObserver

$lazy provides full control of the IntersectionObserver and supports the latest features.

To save size, the configuration can be provided as an array.

$lazy returns a DOM NodeList with elements watched by the observer.

Security

$lazy supports a strict Content-Security-Policy and can be controlled by a async HTML script tag.

Multiple configurations are supported via the attribute data-zz. The attributes accepts a JSON array with configurations.

Compressed srcset

$lazy enables to compress srcset to save HTML document size using the attribute data-z.

Advanced in-view and out-of-view callback

$lazy enables to make full use of the IntersectionObserver for any purpose and supports a simple in-view callback, an out-of-view callback or a custom IntersectionObserver callback.

By returning false from a custom inview callback, the observer will not be removed and will trigger the callback again when the element moves in or out of view. The third parameter is a boolean with the in-view status.

For advanced usage, the inview argument accepts an array with 3 index positions:

1. inview: a function to call when the element moves into view.
2. out-of-view a function to call when the element moves out of view
3. after_inview a function to call when using the default inview-method (the image resolver) after src and srcset have been rewritten.

When out-of-view is null, the inview method is used as the out-of-view callback.

The after_inview callback enables to easily extend resolved images by the default image resolver.

Custom IntersectionObserver callback

The third argument enables to manually define the IntersectionObserver callback which makes it possible to use $lazy for easy access to the functionality provided by IntersectionObserver.

Events

$lazy provides an extension that watches for mouseover, click and the custom z event to fire the in-view callback manually. This feature ensures that images are resolved in the case of issues with the IntersectionObserver polyfill and it enables to manually trigger the callback, for example before printing.

It is possible to manually define events to watch using the configuration parameter events or the array index 4.

Manually resolve images

$lazy enables to manually resolve images using the default image resolver by providing 1 as the in-view callback.

Client-side .webp rewrite

$lazy provides an extension to automatically rewrite images to .webp in browsers that support Google's WebP image format. The solution prevents a server-side redirect which improves performance.

The solution is fail safe and uses <img onerror> as a fallback to the original image when the .webp image is 404 or fails to load.

It is possible to manually disable the .webp rewrite for an image by defining the HTML attribute data-webp="no" or by using the $lazy configuration parameter webp or array index 3.

$lazybg supports .webp rewrites as well.

$lazybg lazy loading of background-image

$lazy provides a unique innovation to lazy load background-image in stylesheets using CSS Variables with a fallback for old browsers.

There are four options to resolve images:

1. manually define images via :root {} within the stylesheet
2. base64 encode image URLs
3. provide a JSON source list as resolver
4. provide a javascript function as resolver

Note: CSS variables are limited to DOMString. When using inline base64 encoding, the following characters need to be replaced in the encoded value:

/: —

=: •

Polyfill

$lazy provides support for Google's IntersectionObserver polyfill with 0% performance hit for modern browsers.

When using the polyfill extension, $lazy checks for the parameter window.$lazypoly when IntersectionObserver is not supported by the browser.

When window.$lazypoly is defined as a function, $lazy will fire it and expect a .then method to be resolved when the polyfill is loaded.

When window.$lazypoly is defined as a string, the string is passed to $async.js that could load anything.

$lazy as a timing method in $async

$lazy and the polyfill can be efficienty loaded using $async and it's just-in-time timing method. $lazy then becomes available as a timing method within $async which enables to load stylesheets and scripts using the IntersectionObserver.

$async enables to load the $lazy script and its optional polyfill from localStorage for exceptional speed.

Note: to use $lazy as a timing method in $async you need to set the ref of the lazy.js script to $z.

When including the $lazy script inline, the data-poly attribute enables to define a string to pass to $async to load a polyfill.