<iframe src="https://www.googletagmanager.com/ns.html?id=GTM-5HGSQD2L" height="0" width="0" style="display:none;visibility:hidden" title="GTM"></iframe>

Progressive Image

Defers the loading of large images to improved the perception of page load times.
styleKeys: progressiveImagescriptsKeys: progressiveImage

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 image
  • src, 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.

The preview has been updated.

The 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.

The preview has been updated.

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.

Share

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.

Share

Accessibility

  • All images must have an alt attribute. Typically, the alt attribute should have a small description of the image itself. However, sometimes that attribute might be a blank value (alt=""):
    • Use an empty alt attribute if there is nearby HTML text that presents the same content as the image description. For instance, a product tile offers both a product image and the product name. The image does not also need the product name in its alt attribute, since this would mean that screen readers would say the same thing twice in a row: "Business Cards... Business Cards." In this case, the product image should use an empty alt attribute.
    • Use an empty alt attribute if the image is purely decorative, such as a page divider, or a > glyph at the end of a link.
    • For more information on how to properly use the alt attribute, the WC3 provides a handy flowchart, "An alt Decision Tree".
  • If an image should have empty alt attribute for accessibility reasons, but we cannot use an empty string for some reason (e.g. we need the image to have a descriptive string to help boost SEO for image searches), then as long as the image and its accompanying text are both inside the same link, you can put role="presentation" aria-hidden="true"onto the image. This signals to assistive technologies that the image is decorative and should be hidden from assistive technologies.

Implementation

  • Progessive Image can (and should) be used with other image types such as Responsive Image and Fluid Image. Progressive Image controls when and how the image loads, while Responsive and Fluid Image control how the image displays.
  • The vanilla JS version of this component will attempt to run at the DOM load event, which can occur before some React components are ready, especially if you are using Gatsby. Pages using React should use the React version of this component instead.

Props

ProgressiveImage
This component is implemented using the <div /> as the root element. You can utilize the native attributes supported by <div /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.
See core props for additional props that can be applied to this component.
proptyperequireddescriptiondefault
intersectionOptionsIntersectionOptionsfalse
Options for configuring the intersection observer behavior.
null
onError((evt: Event) => void) | nullfalse
Callback function to handle error events.
null
placeholderstring | nullfalse
-
null
triggerNonNullable<number | "immediate" | "inView" | null> | nullfalse
Specifies when to trigger the image loading. Can be one of 'immediate', 'inView', or a number (delay in milliseconds). Available options: immediate, inView, number
inView

Related

Was this page useful?

Thanks for your feedback!

Feel free to include your name if you wish to have a follow up conversation.


Published: Jan 31, 2022Last updated: Sep 18, 2024