The native HTML loading attribute now has full browser support for Vista. Consider using FluidImage or ResponsiveImage with loading
if only simple lazy loading is required, as this is more performant.
Progressive Image
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.
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.
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.
Accessibility
- All images must have an
alt
attribute. Typically, thealt
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 emptyalt
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".
- Use an empty
- 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 putrole="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
<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.prop | type | required | description | default |
---|---|---|---|---|
intersectionOptions | IntersectionOptions | false | Options for configuring the intersection observer behavior. | null |
onError | ((evt: Event) => void) | null | false | Callback function to handle error events. | null |
placeholder | string | null | false | - | null |
trigger | NonNullable<number | "immediate" | "inView" | null> | null | false | 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 |
How does Progressive Image meet your needs?