Skip to main content

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> with alt=""
  • Hero or banner imagery - use a dedicated hero or section component
  • Galleries - use a carousel or grid of figures

Do

  • Always provide meaningful alt text 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 - alt is still required
  • Don't float figures inside narrow columns where text reflow becomes awkward

API​

Slots​

SlotRequiredDescription
media-Pre-rendered HTML for video, iframe, or other media.
caption-Caption text.

Props​

PropTypeDefaultDescription
imageobject-Image object with url and alt keys. When set, renders an <img> element.
classesarray-Additional CSS class words merged into the root element.
attributesobject-Additional HTML attributes spread on the root element.

Classes​

ClassCapabilityDefaultDescription
.smSize-Small.
.mdSizeYesMedium.
.lgSize-Large.
.roundedShape-Rounded corners.
.squareShape-Sharp corners.
.coverFit-Content fills the box, cropping overflow (object-fit: cover).
.containFit-Content scales within the box preserving aspect ratio (object-fit: contain).
.leftAlignment-Anchored to the left.
.rightAlignment-Anchored to the right.
.flatElevationYesNo elevation.
.raisedElevation-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 alt text
  • <figcaption> provides an accessible name for the figure
  • Sufficient color contrast for caption text
  • image - bare image element styling
  • video - bare video element styling