Responsive Image

React (Editable)

CopyFormat CodeLimited CodeShareCOLUMNReset

CopyFormat CodeLimited CodeShareCOLUMNReset

jsx

<BasicResponsiveImage aspectRatio={0.5} src="https://picsum.photos/400/200" alt="example image" />

<BasicResponsiveImage
  aspectRatio={0.5}
  src="https://picsum.photos/400/200"
  alt="example image"
/>

To use Responsive Image, you need to know the aspect ratio of the image. It can be calculated by dividing the image's height by its width:

e.g. 1) If your image is 16px wide and 9px tall, your ratio is 9 / 16 = 0.5625

e.g. 2) If your image is a square, your ratio is 1

<BasicResponsiveImage
  aspectRatio={1}
  src="some/href"
  alt="Alt text goes here"
/>

<!-- The padding-bottom value of "NN.N%" should be the aspect ratio multiplied by 100% -->
<div class="responsive-image-wrapper" style="padding-bottom:NN.N%">
  <img class="responsive-image" src="some/href" alt="Alt text goes here" />
</div>

Convenience Components

In React, BasicResponsiveImage will cover most use cases. It is created by combining basic components together, so if you find that the Convenience Component isn't exactly what you need, you can easily compose your own version!

BasicResponsiveImage consists of ResponsiveImageContainer and ResponsiveImage. You should provide your image's aspect ratio via the ratio prop on the ResponsiveImageContainer. BasicResponsiveImage forwards the ratio prop to the underlying ResponsiveImageContainer, and all the rest of the props to the ResponsiveImage.

<ResponsiveImageContainer aspectRatio={props.ratio}>
  <ResponsiveImage {...otherProps} />
</ResponsiveImageContainer>

Using srcset

Responsive Image can take advantage of the srcset and sizes attributes of the underlying <img> tag, to provide more responsive imagery, e.g.:

<BasicResponsiveImage
  aspectRatio={1}
  srcset="some/href 123w, some/href 456w"
  sizes="(max-width 345px) 234px, 789px"
  src={generatePhotoPlaceholderURL(400, 400)}
  alt="example image"
/>

Using a <picture> tag

To use a Responsive Image with a picture tag, use React's as property:

<BasicResponsiveImage aspectRatio={1} as="picture">
  <source
    srcSet="https://via.placeholder.com/400x400.webp?text=source+tag+using+webp"
    type="image/webp"
  />
  <img
    src="https://via.placeholder.com/400x400?text=img+tag+fallback"
    alt="img tag fallback"
  />
</BasicResponsiveImage>

Components

Guidelines

Developer Guidelines

• The <img> tags can, and often should, use the srcset attribute to provide both hi-res and lo-res versions of the image. You can read more info on srcset at MDN.

• In the vanilla API, the responsive-image-wrapper wrapper element must have an inline style that sets the padding-bottom, with a value equal to the image's aspect ratio, expressed as a percentage.

Accessibility Guidelines

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

SEO Considerations

• Each image should have a friendly file name, since the file name is used by Google for indexing. "blue-square-business-cards.jpg" is better than "UI_99760.jpg".

• Images should be compressed to minimize file size.

Related

FluidImage - an alternative image component used when you do not know the image's aspect ratio ahead of time