Image

<Image src="/img/examples/image-retina.webp" alt="Canyon rock" borderRadius="medium" width="300px" height="100%" />

When src is valid and loads correctly, the Image component renders an <img> element with auto width and height, as if rendered natively. With the default browser behavior, this is likely to result in suboptimal quality on retina screens:

<Image src="/img/examples/image-retina.webp" alt="Canyon rock" />

To improve the quality, define the image size manually or use the srcSet attribute. Note that different image assets are provided for different pixel densities, and the browser will automatically pick which one to download:

<Image
  src="/img/examples/image.webp"
  alt="Canyon rock"
  imageAttributes={{ srcSet: "/img/examples/image-retina.webp 2x" }}
/>

You can pick the correct borderRadius for the Image based on the design tokens to better visually align it with the surrounding components. For circular images, use the Avatar component instead.

<Image
  src="/img/examples/image-retina.webp"
  alt="Canyon rock"
  borderRadius="large"
  width="300px"
/>

You can pass specific width and height values to the Image with literal css values.

<Image
  src="/img/examples/image-retina.webp"
  alt="Canyon rock"
  width="200px"
  height="calc(var(--rs-unit-x1) * 20)"
/>

Instead of using literal values, you can also pass number values to set the width as a multiplier of the x1 unit token.

<Image src="/img/examples/image-retina.webp" alt="Canyon rock" width={50} />

Another way to define the Image size is to use it with the View utility and the aspectRatio property. In this case, aspectRatio will set the Image size based on the passed ratio value and apply the cover display mode by default.

<View aspectRatio={16 / 9}>
  <Image
    src="/img/examples/image-retina.webp"
    alt="Canyon rock"
    width="300px"
  />
</View>

Image provides multiple fallback options that are shown based on the sizes defined for the image-retina. Using them is helpful whenever an error occurs during the Image load or src is not available in your data source. In both cases, you might want to show a placeholder.

When fallback is passed as a boolean, Image will render just a background.

<View width="300px" aspectRatio={16 / 9}>
  <Image fallback />
</View>

When fallback is passed as a string, Image will use it as a URL for a fallback image. In this case, another image will attempt to load instead of the original one.

<Image
  width="80px"
  height="80px"
  fallback="/img/examples/placeholder.webp"
  borderRadius="medium"
/>

When fallback is passed as a ReactNode, it will be used as a slot to render any component. For example, it can be used to render placeholder icons or error messages.

<Image
  width="80px"
  height="80px"
  fallback={<Icon svg={IconZap} size={6} />}
  borderRadius="medium"
/>

Note that fallback won't be visible if the Image doesn't have its sizes defined or is not using aspectRatio.

Image supports responsive syntax for the width and height properties. Use object syntax to control their values based on the viewport size. Responsive properties are mobile-first, so selecting a value for a viewport will also apply it to all wider viewports.

<Image width={{ s: "200px", l: "300px" }} />

• We recommend using the alt property for most images as long as you can provide a meaningful description for screen reader users. If alt is not passed, Image will be treated as decorative and will use the presentation role.