A <figure>/<figcaption> pairing that wraps self-contained content (an image, illustration, chart, code listing, table) with an optional caption in one of three positions — below (default), above, or overlaid on the media. size scales the caption's type off the body/{size} ramp (the media is size-independent, as in Figma); the caption's own align matches Figma's Figcaption Align axis.
primitiv add figure installs it whichever mode you are reading.Preview
import { Figure } from "@/components/ui/figure";
<Figure captionPosition="below" size="md"> <Figure.Media> <img src="/chart.png" alt="Quarterly growth" /> </Figure.Media> <Figure.Caption align="start">Figure 1. Quarterly growth.</Figure.Caption></Figure>Density is set by a data-density ancestor — the Context system, not a Figure prop.
npx primitiv add figurepnpm dlx primitiv add figureyarn dlx primitiv add figurebunx primitiv add figureImport
import { Figure } from "@/components/ui/figure";No headless primitive — this one ships only as a copied styled surface, so primitiv add is the only way in, whichever mode you are reading.
<Figure> <Figure.Media /> <Figure.Caption /></Figure>Extends HTMLElement — every native attribute of that element is accepted and forwarded.
| Prop | Type | Default | Description |
|---|---|---|---|
| captionPosition | "below" | "above" | "overlay" | below | Caption placement relative to the media. |
| size | "xs" | "sm" | "md" | "lg" | "xl" | md | Caption type size, matching Figma's Size axis — it drives the nested Figcaption's body/{size} scale only; the media is size-independent. data-density scales each size further. |
Headless only — the copied file renders this part for you and exports no separate component, so there is nothing to import under Styled.
Extends HTMLDivElement — every native attribute of that element is accepted and forwarded.
No props of its own.
Headless only — the copied file renders this part for you and exports no separate component, so there is nothing to import under Styled.
Extends HTMLElement — every native attribute of that element is accepted and forwarded.
| Prop | Type | Default | Description |
|---|---|---|---|
| align | "start" | "center" | "end" | start | Caption text alignment, matching Figma's Figcaption Align axis. Direction-aware — start/end follow the reading direction, flipping under RTL. |
--primitiv-figure-caption-gap--primitiv-figure-media-radius--primitiv-figure-caption-color--primitiv-figure-overlay-scrim--primitiv-figure-overlay-caption-color--primitiv-figure-font-family--primitiv-figure-font-size--primitiv-figure-font-weight--primitiv-figure-line-height<figure> and Figure.Caption a real <figcaption>, so assistive tech associates the caption with its content — the caption is not just text that happens to sit nearby.<img> needs its alt, a chart its description. The <figcaption> names the figure, it does not replace the media's own alternative text.overlay caption sits over the media with a scrim for contrast, but the association is structural (figure/figcaption), so it survives regardless of where the caption is placed.captionPosition places the <figcaption>: below (the default) and above sit it outside the media, while overlay floats it over the bottom of the media with a scrim — the hero-image treatment. Figure.Caption takes an align for left/centre/right within the row.
import { Figure } from "@/components/ui/figure";
<Figure captionPosition="overlay"> <Figure.Media> <img src="/cover.jpg" alt="" /> </Figure.Media> <Figure.Caption align="center">On the cover</Figure.Caption></Figure>