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.
<figure> <img src="landscape.jpg" alt="A scenic landscape" /> <figcaption>A beautiful mountain landscape at sunset.</figcaption> </figure>

.bordered

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

Bordered figure example
The caption appears below a dividing line.
<figure class="bordered"> <img src="photo.jpg" alt="..." /> <figcaption>Caption with border separator.</figcaption> </figure>

.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 start example
Float start

This paragraph demonstrates text wrapping around a floated figure. The figure floats to the inline-start (left in LTR languages) and subsequent text flows around it naturally. This layout is common in editorial content where images accompany written text.

Additional paragraphs continue to wrap until they clear the floated element. This creates a natural reading flow that integrates images with text content.

<figure class="float-start" style="max-inline-size: 200px;"> <img src="photo.jpg" alt="..." /> <figcaption>Caption text</figcaption> </figure> <p>Text wraps around the figure...</p>

.float-end

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

Float end example
Float end

This paragraph demonstrates text wrapping around a figure floated to the end. In left-to-right languages, the figure appears on the right side with text flowing to its left.

This layout is useful when you want to draw attention to supporting imagery while maintaining readable text flow.

.full

Full container width.

Full width figure
A full-width figure spanning the entire container.

Special Variants

.code

Styled for code examples with filename in caption.

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

console.log(greet('World'));
example.js
<figure class="code"> <pre><code>function greet(name) { return `Hello, ${name}!`; }</code></pre> <figcaption>example.js</figcaption> </figure>

.quote

Styled for pull quotes with attribution.

The only way to do great work is to love what you do.
Steve Jobs
<figure class="quote"> <blockquote> The only way to do great work is to love what you do. </blockquote> <figcaption>Steve Jobs</figcaption> </figure>

Content Types

Figures can contain various types of content.

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

Figure 3: Introduction video with playback controls.

Canvas

Figure 4: Interactive canvas visualization.

SVG

Figure 5: SVG diagram showing opacity progression.

Iframe

Figure 6: Embedded external content.

Audio

Audio 1: Podcast episode - "Introduction to Web Development"

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
<figure> <!-- alt describes WHAT the image shows --> <img src="chart.png" alt="Bar chart comparing Q1-Q4 sales" /> <!-- figcaption provides CONTEXT about why it's shown --> <figcaption>Figure 1: Q4 sales exceeded targets by 15%.</figcaption> </figure>

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 Elements

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;