Figures and captions

Use figure for self-contained content that the surrounding text refers to. Images, diagrams, code samples, and quotations can all be figures.

Wrap the content and add a visible caption with figcaption:

<figure>
  <img
    src="harbor-route.png"
    alt="Map showing the harbor cycle route"
    width="900"
    height="600"
  >
  <figcaption>The harbor route avoids the busiest roads.</figcaption>
</figure>

In the browser you see the image with a caption line underneath. Screen readers treat the figure as one unit, so the caption stays connected to the image in the accessibility tree.

The caption and alt text have different jobs.

The caption is visible to everyone and can add context the image alone does not carry. The alt text replaces the visual information when the image cannot be seen. Avoid copying the exact same sentence into both.

figcaption must be the first or last child of figure. Put it after the image when the caption describes what you see.

Not every image needs a figure. A small icon inside a button or a logo in the header is usually not a figure. Use figure when the image and its caption form a meaningful unit that the page discusses as one piece.

A common mistake is putting the caption in a plain p tag below the image. Visually it looks fine, but assistive technology no longer knows the text belongs to that image. The figure element keeps them linked in the document structure.

On your my-page project, wrap a project screenshot in a figure. Write alt text that describes the screenshot and a caption that explains what the reader should notice. You can put more than one image inside a single figure when they belong together, such as before-and-after screenshots, with one figcaption at the end describing the whole set.