Image
Image with load state, blur-up placeholder, graceful fallback, and optional zoom
Category: display · WCAG 2.2-AA · image, media, display, loading
States
- loading
- loaded
- error
Props
| Prop | Type | Default | Description |
|---|---|---|---|
src | string | — | Image source URL. |
alt | string | | Alternative text describing the image. |
fallbackSrc | string | — | Image shown if src fails to load |
width | string | number | — | Intrinsic width in px, forwarded to the `<img>`. Set it together with `height` so the browser can reserve the box before the image loads (no layout shift). |
height | string | number | — | Intrinsic height in px, forwarded to the `<img>`. Pair with `width` to reserve the box and avoid layout shift. |
radius | 'none' | 'sm' | 'md' | 'lg' | 'full' | md | Corner radius of the image ('none' | 'sm' | 'md' | 'lg' | 'full'). |
zoom | boolean | false | When true, zooms the image on hover. |
removeWrapper | boolean | false | Render a bare <img> with no wrapper, placeholder, or zoom |
isBlurred | boolean | false | When true, renders a blurred backdrop behind the image. |
Design tokens
--cascivo-radius-none--cascivo-radius-sm--cascivo-radius-md--cascivo-radius-lg--cascivo-radius-full--cascivo-color-bg-subtle--cascivo-color-border--cascivo-space-12
When to use
- Displaying a content image that should show a placeholder while loading and degrade gracefully on error
- Photos, thumbnails, or media that benefit from a blur-up placeholder or hover zoom
- Any image where a broken src should fall back rather than show a broken-image icon
When not to use
- Identity thumbnails for a person or entity — use Avatar
- Purely decorative shapes or a fixed-ratio layout box with no load behavior — use AspectRatio
How to build an accessible Image in React →
Examples
Basic
<Image src="/photo.jpg" alt="A photo" width={320} height={240} />With fallback
<Image src="/broken.jpg" fallbackSrc="/placeholder.jpg" alt="A photo" />Blurred placeholder
<Image src="/photo.jpg" alt="A photo" isBlurred />Hover zoom
<Image src="/photo.jpg" alt="A photo" zoom />Related components
- Avatar — Use Avatar for identity thumbnails with an initials fallback
- AspectRatio — Use AspectRatio for a ratio box that does not own image load behavior