/// Media
Image
An <img> wrapper with fixed or fill sizing, object-fit, a sharp fallback placeholder, and an optional caption.
import { Image } from "@protocore/pds";Basics
Image wraps a plain <img> with fixed width / height and an object-fit (default cover). Corners stay sharp. It's a thin, framework-agnostic wrapper — no lazy-loading magic, just consistent sizing and a fallback.
Fallback
When src is absent or the image fails to load, Image swaps in a sharp placeholder box with a broken-image glyph and a mono label — no layout shift, no broken-image chrome. Pass a custom fallback node or a fallbackLabel to tune it.
Caption & fill
Add a caption to promote the wrapper to a semantic <figure> with a <figcaption>. Use fill (instead of width/height) to have the image cover a positioned parent — pair it with AspectRatio to lock the frame's ratio.
When to use it
Image is the general-purpose picture primitive — product shots, screenshots, chart exports, uploaded media. For a *person's* picture with initials fallback, use Avatar; for a fixed-ratio frame, wrap Image fill in AspectRatio; for decorative brand line work, use LineArt.
The fallback is the point: an admin console renders user-supplied URLs that break, and a broken-image icon looks like a bug. Image degrades to a deliberate placeholder instead. alt is required — pass "" for purely decorative images so screen readers skip them.
Usage
Do
- Always pass `alt` — a description, or `""` for decorative images.
- Use the fallback for user-supplied URLs that may 404.
- Wrap `fill` images in AspectRatio to reserve the space.
Don't
- Don't use it for avatars — Avatar has the initials fallback.
- Don't omit dimensions on a fixed image; reserve the space to avoid shift.
- Don't round the corners; keep them sharp.
Accessibility
- `alt` is a required prop — meaningful images describe themselves; decorative ones pass `alt=""`.
- The fallback placeholder is a `role="img"` with the `alt` (or `fallbackLabel`) as its accessible name, so a missing image is still announced.
- A `caption` renders inside a real `<figure>` / `<figcaption>`, associating the text with the image.
Image props
| Prop | Type | Default | Description |
|---|---|---|---|
alt * | string | — | Alternative text. Required for meaningful images; pass `""` for decorative. |
caption | ReactNode | — | Caption rendered under the image; promotes the wrapper to a `<figure>`. |
className | string | — | |
fallback | ReactNode | — | Custom fallback node shown when the image is missing or errors. |
fallbackLabel | string | No image | Mono label for the built-in placeholder (used when no `fallback` is given). |
fill | boolean | false | Fill the positioned parent (absolute inset:0) instead of using width/height. |
fit | enum | cover | `object-fit` for the rendered image. |
height | string | number | — | Height — number (px) or any CSS length. Ignored when `fill`. |
src | string | — | Image source. When absent or it fails to load, the fallback renders. |
style | CSSProperties | — | |
width | string | number | — | Width — number (px) or any CSS length. Ignored when `fill`. |