A Progressive Image improves the user's perceived page load time by deferring the loading of large images. Each Progressive Image contains both a low-res placeholder image that is part of the initial HTML, plus a second, full-resolution image that loads at a later time.
React Usage
ProgressiveImage has two important props:
placeholder, which holds the URL of the placeholder imagesrc, which holds the URL for the full image.
ProgressiveImage requires as a child a function with input args image and isLoading. It should return an ReactElement, typically ResponsiveImage or FluidImage - this way you can control how the image is rendered.
ShareThe trigger prop on the component can then control what triggers the component to load the full image:
trigger "inView"
Giving the trigger prop a value of inView makes the component only load the full image when it scrolls into the viewport. This is the default behavior.
When using inView option, you can specify also options for intersection observer, using intersectionOptions.
Intersection options are:
- root
- rootMargin
- threshold
More information about the options and defaults: https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API
The preview has been updated.
trigger "immediate"
Giving the trigger prop a value of immediate makes the page load the full image as soon as possible when the image is rendered. This is useful for images "above the fold" at the top of the page.
trigger with delay
Giving the trigger prop a value that is a number will delay the loading of the image by that number of milliseconds.
The preview has been updated.
srcSet and sizes options
ProgressiveImage can also use srcSet and sizes props, which function the same as those properties of the HTML <img> tag. By default, both options are empty strings.
The preview has been updated.
Using isLoading
You can use isLoading to respond to whether the image is yet loading. For instance, this example uses isLoading with the style property to give the image an opacity of 0.1 (and thus will make it very translucent) until it begins to load:
The preview has been updated.
Vanilla usage
The vanilla JS component puts the class swan-progressive-image onto an <img> tag. This <img> can (and likely should!) also be a Responsive Image or Fluid Image.
The src attribute for the <img> represents the placeholder version, which the page will load immediately. The data-src attribute holds the URL for the full-sized image.
The vanilla component comes in three variations:
- the default version, which loads only when it scrolls into the viewport.
- the "immediate" version, which makes the page load the full image as soon as possible, typically at the DOMready event. This is useful for images "above the fold" at the top of the page.
- the "eager" version, which makes the page load the full image as soon as the page reaches the "load" event. This is useful for images that are near the top of the page.