Image
The Image component is used to display images.
Image composes Box so you can use all the style props and add responsive
styles as well.
Import#
Usage#
Size#
The size of the image can be adjusted using the boxSize prop.
Image with border radius#
Fallback support#
You can provide a fallback image for when there is an error loading the src of
the image. You can also opt out of this behavior by passing the ignoreFallback
prop.
Improvements from v1#
Added support for the
fitprop to specify how to fit an image within its dimension. It uses theobject-fitproperty.Added support for the
alignprop to specify how to align the image within its dimension. It uses theobject-positionproperty.Added support for custom
fallbackcomponent.
Usage with SSR#
The Img Component provides a fallback for SSR applications which uses the
image directly without client side checks.
Props#
| Name | Type | Description | Default |
|---|---|---|---|
| align | SystemProps["objectPosition"] | How to align the image within its bounds. It maps to css `object-position` property. | - |
| crossOrigin | "" | "anonymous" | "use-credentials" | The key used to set the crossOrigin on the HTMLImageElement into which the image will be loaded. This tells the browser to request cross-origin access when trying to download the image data. | - |
| fallback | React.ReactElement | Fallback element to show if image is loading or image fails. | - |
| fallbackSrc | string | Fallback image `src` to show if image is loading or image fails. Note 🚨: We recommend you use a local image | - |
| fit | SystemProps["objectFit"] | How the image to fit within its bounds. It maps to css `object-fit` property. | - |
| htmlHeight | string | number | The native HTML `height` attribute to the passed to the `img` | - |
| htmlWidth | string | number | The native HTML `width` attribute to the passed to the `img` | - |
| ignoreFallback | boolean | If `true`, opt out of the `fallbackSrc` logic and use as `img` | - |
| onError | ((error: string | SyntheticEvent<HTMLImageElement, Event>) => void) | A callback for when there was an error loading the image `src` | - |
| onLoad | ((event: SyntheticEvent<HTMLImageElement, Event>) => void) | A callback for when the image `src` has been loaded | - |
| sizes | string | The image `sizes` attribute | - |
| src | string | The image `src` attribute | - |
| srcSet | string | The image `srcset` attribute | - |