Vanilla Breeze

figure

The figure element represents self-contained content with an optional caption, used for images, diagrams, code snippets, and quotations.

Description

The <figure> element represents self-contained content that is referenced from the main content but could be moved to an appendix or sidebar without affecting the document flow. It typically contains images, diagrams, code listings, or quotations along with an optional <figcaption>.

Vanilla Breeze provides variants for bordered figures, floating figures, code examples, and pull quotes.

When to Use

  • Images with captions - Photos, illustrations, diagrams with descriptive text
  • Code examples - Code snippets with file names or descriptions
  • Quotations - Pull quotes or block quotes with attribution
  • Videos - Embedded videos with titles or descriptions
  • Charts and graphs - Data visualizations with explanatory captions
  • Tables - Data tables with descriptive captions

When Not to Use

  • Decorative images that don't need captions
  • Inline images that are part of the text flow
  • Content that can't stand on its own

Variants

Default

Basic figure with content and optional caption.

A scenic landscape
A beautiful mountain landscape at sunset.

.bordered

Adds padding and border for a card-like appearance with separated caption.

Bordered figure example
The caption appears below a dividing line.

.centered

Centers the figure and caption for standalone display.

Centered figure
A centered figure with centered caption.

.float-start

Floats the figure to the start (left in LTR) with text wrapping.

.float-end

Floats the figure to the end (right in LTR) with text wrapping.

.full

Full container width.

Special Variants

.code

Styled for code examples with filename in caption.

function greet(name) {
  return `Hello, ${content}#123;name}!`;
}

console.log(greet('World'));
example.js

.quote

Styled for pull quotes with attribution.

The only way to do great work is to love what you do.
Steve Jobs

Sticky Caption

When a figure contains a horizontally-scrollable element like a wide table or code block, the <figcaption> automatically stays anchored at the left edge while the content scrolls. This is applied automatically — no class or attribute needed.

const config = { entry: "./src/index.js", output: { path: "/dist", filename: "bundle.js" }, module: { rules: [{ test: /\.css$/, use: ["style-loader", "css-loader"] }] } };
webpack.config.js — scroll horizontally to see the full line; the caption stays put.

Content Types

Figures can contain various types of content beyond images.

Image

Example image
Figure 1: A sample image with caption.

Picture (Responsive Image)

Responsive image in figure
Figure 2: A responsive image using the picture element.

Video

Use the poster attribute and a fallback paragraph for browsers without video support.

Canvas

Canvas elements require JavaScript to draw content. The figure wraps the canvas and provides a caption describing the visualization.

SVG

Inline SVG diagrams benefit from role="img" and an aria-label for accessibility.

Iframe

Wrap iframes in a responsive container to maintain aspect ratio. Always include a descriptive title attribute.

Audio

Native audio controls render even without a source file. Include a fallback message for older browsers.

Accessibility

Figure Role

The <figure> element has an implicit figure role when it contains a <figcaption>. Screen readers announce it as a figure with its caption.

Alt Text vs Caption

The alt attribute and <figcaption> serve different purposes:

  • alt - Describes the image content for screen readers
  • figcaption - Provides context visible to all users

Best Practices

  • Always include alt text on images within figures
  • Don't repeat the same information in alt and figcaption
  • Use figcaption for context, attribution, or additional details
  • Number figures if referenced in text (Figure 1, Figure 2)
  • Ensure figures make sense when read out of document order

Related

CSS Reference

Styles defined in /src/native-elements/figure/styles.css

Selector Properties
figure display: block; margin: 0;
figure > img/video/picture/iframe/canvas display: block; inline-size: 100%; block-size: auto;
figure.bordered padding; border; border-radius;
figure.centered margin-inline: auto; text-align: center;
figure.float-start float: inline-start; max-inline-size: 50%;
figure.float-end float: inline-end; max-inline-size: 50%;
figure.code Special pre/code/figcaption styling;
figure.quote Special blockquote/figcaption styling;
figure:has(:is(table, pre)) > figcaption position: sticky; inset-inline-start: 0;
↑