Image
A picture in a box of a fixed shape, with a placeholder while it loads, a fade-in, and a fallback when it cannot load.
Stability: experimental
Props
| Prop | Type | Default | Means |
src | string | | The image address. Each address is fetched and decoded once for the whole app (decision 0038). |
alt | string | | What the image shows, for screen readers. Required unless decorative (E0160). |
decorative | boolean | false | The image adds nothing a screen reader user needs, so it gets an empty description. |
ratio | "1:1" | "4:3" | "3:2" | "16:9" | "3:4" | "2:3" | "4:3" | The box's shape. It fills the width it is given and keeps this ratio, so nothing moves when the image arrives. |
fit | "cover" | "contain" | "cover" | cover fills the box and crops; contain shows the whole image, with the raised colour around it. |
placeholder | string | "raised" | The colour shown while loading: a theme colour name, or a colour such as #9fbf9f (usually the image's own average colour). |
radius | "none" | "sm" | "md" | "lg" | "full" | "md" | The corner radius; full with ratio 1:1 is a circle. |
lazy | boolean | true | Waits until the image is near the visible part of the screen before loading it. |
zoomable | boolean | false | Pressing the image opens it full screen in an ImageViewer (decision 0039). |
Pieces
| Piece | Means |
fallback | Shown, centred on the raised colour, when the image cannot be loaded. Without it, an image icon and the alt text. |
States
| State | Looks like |
loading | The placeholder colour fills the box. |
loaded | The image fades in from a blur over 320 ms, or appears at once with reduced motion or when it was already decoded. |
failed | The fallback piece, or the stock image icon and description, in muted text on raised. |
focused | When zoomable, the focus outline inside the box. |
Accessibility
| |
| role | img named by alt; a decorative image has an empty alt and is skipped. When zoomable, it sits in a button named "<alt>, open full screen". |
| name | The alt prop. |
| focus | Not focusable, unless zoomable: then Tab reaches its button. |
| keyboard | When zoomable, Enter or Space opens the viewer. |
| notes | Placing Image with neither alt nor decorative is E0160. |
Theme tokens
color.raised color.muted space.1 space.3 radius.none radius.sm radius.md radius.lg radius.full text.caption
Example
<Image src="/photos/lake.svg" alt="A lake below mountains" ratio="16:9" zoomable />