Duolith docs

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

PropTypeDefaultMeans
srcstringThe image address. Each address is fetched and decoded once for the whole app (decision 0038).
altstringWhat the image shows, for screen readers. Required unless decorative (E0160).
decorativebooleanfalseThe 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.
placeholderstring"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.
lazybooleantrueWaits until the image is near the visible part of the screen before loading it.
zoomablebooleanfalsePressing the image opens it full screen in an ImageViewer (decision 0039).

Pieces

PieceMeans
fallbackShown, centred on the raised colour, when the image cannot be loaded. Without it, an image icon and the alt text.

States

StateLooks like
loadingThe placeholder colour fills the box.
loadedThe image fades in from a blur over 320 ms, or appears at once with reduced motion or when it was already decoded.
failedThe fallback piece, or the stock image icon and description, in muted text on raised.
focusedWhen zoomable, the focus outline inside the box.

Accessibility

roleimg 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".
nameThe alt prop.
focusNot focusable, unless zoomable: then Tab reaches its button.
keyboardWhen zoomable, Enter or Space opens the viewer.
notesPlacing 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 />