Responsive Image

Responsive Image is the preferred method for rendering an image when you know the aspect ratio of your image ahead of time.

UsageGuidelinesAPI

Use Responsive Image to reserve space for an image and prevent page content from jumping around once the image loads.

Use Responsive Image...

When you know the aspect ratio of an image.
When you need the image to load immediately.

Don’t use Responsive Image…

When you don’t know the image’s aspect ratio ahead of time. Use Fluid Image instead.
When you can defer the loading of the image. Use Progressive Image instead.

ReactVanilla

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

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

<div
  class="swan-responsive-image-wrapper swan-aspect-ratio-container"
  style="padding-bottom: 50%"
>
  <div class="swan-aspect-ratio-content">
    <img
      src="https://picsum.photos/800/400"
      alt="example image"
      class="swan-responsive-image"
    />
  </div>
</div>

<div
  class="swan-responsive-image-wrapper swan-aspect-ratio-container"
  style="padding-bottom: 50%"
>
  <div class="swan-aspect-ratio-content">
    <img
      src="https://picsum.photos/800/400"
      alt="example image"
      class="swan-responsive-image"
    />
  </div>
</div>

BasicResponsiveImage

BasicResponsiveImage is a React convenience component that covers most use cases. It takes an aspectRatio prop with the image’s aspect ratio, plus any props like alt and src that can go onto an <img> tag.

The aspect ratio should be the image's height divided by its width:

e.g. 1) If your image is 160px wide and 90px tall, your aspect ratio is 90 / 160 = 0.5625

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

ReactVanilla

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

<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="swan-responsive-image-wrapper" style="padding-bottom:NN.N%">
  <img class="swan-responsive-image" src="some/href" alt="Alt text goes here" />
</div>

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

Multiple source images

Use the srcset prop to set the corresponding srcset attribute on the underlying <img> tag, so that you can provide both hi-res and lo-res versions of an image. The browser will only download the relevant version for the user’s screen size, resulting in better page performance. Refer to srcset at MDN.

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

<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

Use React’s as prop to have the component produce a <picture> tag instead. Refer to picture at MDN.

ReactVanilla

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

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

<div
  class="swan-responsive-image-wrapper swan-aspect-ratio-container"
  style="padding-bottom: 100%"
>
  <div class="swan-aspect-ratio-content">
    <picture class="swan-responsive-image"
      ><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"
    /></picture>
  </div>
</div>

<div
  class="swan-responsive-image-wrapper swan-aspect-ratio-container"
  style="padding-bottom: 100%"
>
  <div class="swan-aspect-ratio-content">
    <picture class="swan-responsive-image"
      ><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"
    /></picture>
  </div>
</div>

ResponsiveImageContainer

In the Vanilla API, or when you need more control over the code than BasicResponsiveImage provides, use the underlying components that BasicResponsiveImage is made of: a ResponsiveImageContainer around a ResponsiveImage.

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

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

In the React API, use the aspectRatio prop on the ResponsiveImageContainer, which is the outer wrapper around the image. All the other props, including srcset, go onto the child ResponsiveImage, which produces the <img> tag.

In the vanilla API, you must set an inline padding-bottom on the swan-responsive-image-wrapper element, whose value is the image's aspect ratio, expressed as a percentage. So an image with an aspect ratio of 0.5625 needs an inline padding-bottom: 56.25%.

Alt text

All Responsive Images need an alt attribute of some kind. Refer to “Alt text” guidelines.

Best practices

Do

Use descriptive, friendly file names like "blue-square-business-cards.jpg" for better Google indexing.
Compress images to minimize file size and increase performance.

Don't

Use unclear or generic file names like “biz_crd-99760.jpg”.

Props

BasicResponsiveImage

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.

prop	type	required	description	default
aspectRatio	`number`	true	The height / width ratio expressed as the result of dividing the content's height by its width Examples: 16:9 => 9 / 16 => 0.5625, 1:1 => 1 / 1 => 1.0	null

ResponsiveImageContainer

See core props for additional props that can be applied to this component.

prop	type	required	description	default
aspectRatio	`number`	true	The height / width ratio expressed as the result of dividing the content's height by its width Examples: 16:9 => 9 / 16 => 0.5625, 1:1 => 1 / 1 => 1.0	null

ResponsiveImage

This component is implemented using the <img /> as the root element. You can utilize the native attributes supported by <img /> 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.

Was this page useful?