Figure
Image or video with a caption. Wraps media and a short description in a single semantic block so assistive tech announces them together. Supports classless <figure> / <figcaption> markup and a .figure mirror class for contexts where the element cannot be used directly.
Usage
When to use
- An image or video needs a visible caption
- A piece of media is referenced elsewhere in the page and needs a self-contained block
- A floated image with caption is required inside body copy
When not to use
- Decorative images with no caption - use a plain
<img>withalt="" - Hero or banner imagery - use a dedicated hero or section component
- Galleries - use a carousel or grid of figures
Do
- Always provide meaningful
alttext on the image - Keep captions concise - one or two sentences
- Use logical float properties for RTL safety
Don't
- Don't rely on the caption to describe the image for non-sighted users -
altis still required - Don't float figures inside narrow columns where text reflow becomes awkward
API
Slots
| Slot | Required | Description |
|---|---|---|
media | - | Pre-rendered HTML for video, iframe, or other media. |
caption | - | Caption text. |
Props
| Prop | Type | Default | Description |
|---|---|---|---|
image | object | - | Image object with url and alt keys. When set, renders an <img> element. |
classes | array | - | Additional CSS class words merged into the root element. |
attributes | object | - | Additional HTML attributes spread on the root element. |
Classes
| Class | Capability | Default | Description |
|---|---|---|---|
.sm | Size | - | Small. |
.md | Size | Yes | Medium. |
.lg | Size | - | Large. |
.rounded | Shape | - | Rounded corners. |
.square | Shape | - | Sharp corners. |
.cover | Fit | - | Content fills the box, cropping overflow (object-fit: cover). |
.contain | Fit | - | Content scales within the box preserving aspect ratio (object-fit: contain). |
.left | Alignment | - | Anchored to the left. |
.right | Alignment | - | Anchored to the right. |
.flat | Elevation | Yes | No elevation. |
.raised | Elevation | - | Slight elevation. |
Examples
With video
Responsive video embed inside a figure with caption.
Float left
Figure floated to the left edge of body copy.
Float right
Figure floated to the right edge of body copy.
Accessibility
- WCAG 2.2 AA
- Images must include meaningful
alttext <figcaption>provides an accessible name for the figure- Sufficient color contrast for caption text