Layout Figure

Overview

Important information:

The guidance content for the figure component is currently under review and will be updated shortly.

The figure component provides a structured and reusable way to display visual data in ONS content.

Example Figure contents

Nunjucksfor Example Figure
Nunjucks macro optionsfor Example Figure
HTMLfor Example Figure

Nunjucks

{% from "components/figure/_macro.njk" import onsFigure %}

{%
    call onsFigure({
        "headingLevel": 3,
        "figureNumber": "Figure 1",
        "title": "Image 1: Working from home",
        "subtitle": "A growing proportion of the workforce now works remotely",
        "id": "figure-with-image",
        "caption": "Image 1 - Woman in a purple dress shirt using a laptop",
        "download": {
            "title": "Download this image",
            "itemsList": [
                {
                    "text": "High resolution image (JPG format, 1.2MB)",
                    "url": "/img/small/woman-in-purple-dress-shirt.jpg",
                    "download": "file"
                },
                {
                    "text": "High resolution image (JPG format, 1.2MB)",
                    "url": "/img/small/woman-in-purple-dress-shirt.jpg",
                    "download": "file"
                }
            ]
        },
        "footnotes": {
            "title": "Footnotes",
            "content": "Image is for illustrative purposes only."
        }
    })
%}
    {# Note that for the sake if the example the image here is rendered directly in an image tag, because onsImage already renders using the figure component #}
    <img class="ons-image__img" src="/img/small/woman-in-purple-dress-shirt.jpg" alt="Woman in a purple dress shirt using a laptop" />
{% endcall %}

Nunjucks macro options

Name	Type	Required	Description
useDivForRootElement	boolean	false	If `true`, renders the root element as a `div` instead of a `figure`. When set, the caption renders in a `span` instead of a `figcaption`.
headingLevel	number	false	Number used to determine the heading level of the title. The subtitle is rendered one level below this, e.g. if you provide level 3, the subtitle will render as h4. The download and footnotes heading levels adjust based on which headings are present: two levels below when both title and subtitle are provided, one level below when only title is provided, or at the base heading level when neither is provided. Accepts a value between 1 and 4, defaulting to 2 if not provided. All headings render at a fixed visual size regardless of the level chosen.
title	string	false	The title displayed above the nested content.
subtitle	string	false	The subtitle displayed below the title. Only rendered when `title` is also provided.
audioDescription	string	false	A visually-hidden textual description of the nested content for screen readers, associated with the figure via `aria-describedby`. Should not be used when nesting an image as the alt-text on the image serves this purpose instead.
caption	string	false	A short visible caption providing additional context, displayed in a `figcaption`.
footnotes	`Object<Footnotes>`	false	Footnotes to appear below the nested content in a 'details' element.
download	`Object<Download>`	false	Object for download options, displayed in a details element below the nested content.
id	string	true if audio description, footnotes or downloads provided	An `id` applied to the wrapping element. Also used to generate the audio description, footnotes and downloads `ids`.
classes	string	false	Classes to add to the wrapping element.

The nested content (for example a chart or image) is provided through the macro's caller block rather than as a parameter, so no HTML needs to be passed in. See the example for usage.

Download
Name	Type	Required	Description
title	string	false	The title displayed above the download options.
itemsList	`Array<ListItem>` (ref)	false	An list of items available for download

Footnotes
Name	Type	Required	Description
title	string	true	The title text for the footnotes heading.
content	string	true	HTML content for the footnotes.

HTML

<figure class="ons-figure" id="figure-with-image">
  <span class="ons-figure__number">Figure 1</span>
  <h3 class="ons-figure__title">Image 1: Working from home</h3>
  <h4 class="ons-figure__subtitle">A growing proportion of the workforce now works remotely</h4>
  <div class="
                ons-figure__content
                ons-u-mt-l
                ons-u-mb-l
            ">
    <img class="ons-image__img" src="/img/small/woman-in-purple-dress-shirt.jpg"
      alt="Woman in a purple dress shirt using a laptop" />
  </div>
  <figcaption class="ons-figure__caption">Image 1 - Woman in a purple dress shirt using a laptop</figcaption>
</figure>
<div id="figure-footnotes--figure-with-image" class="ons-details ons-js-details ons-u-mb-l">
  <div class="ons-details__heading ons-js-details-heading" role="button">
    <h5 class="ons-details__title ons-u-fs-r--b">Footnotes</h5>
    <span class="ons-details__icon">
      <svg class="ons-icon" viewBox="0 0 8 13" xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor"
        role="img" aria-hidden="true">
        <path
          d="M5.74,14.28l-.57-.56a.5.5,0,0,1,0-.71h0l5-5-5-5a.5.5,0,0,1,0-.71h0l.57-.56a.5.5,0,0,1,.71,0h0l5.93,5.93a.5.5,0,0,1,0,.7L6.45,14.28a.5.5,0,0,1-.71,0Z"
          transform="translate(-5.02 -1.59)" />
      </svg></span>
  </div>
  <div id="figure-footnotes--figure-with-image-content" class="ons-details__content ons-js-details-content"> Image is
    for illustrative purposes only. </div>
</div>
<div id="figure-downloads--figure-with-image" class="ons-details ons-js-details">
  <div class="ons-details__heading ons-js-details-heading" role="button">
    <h5 class="ons-details__title ons-u-fs-r--b">Download this image</h5>
    <span class="ons-details__icon">
      <svg class="ons-icon" viewBox="0 0 8 13" xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor"
        role="img" aria-hidden="true">
        <path
          d="M5.74,14.28l-.57-.56a.5.5,0,0,1,0-.71h0l5-5-5-5a.5.5,0,0,1,0-.71h0l.57-.56a.5.5,0,0,1,.71,0h0l5.93,5.93a.5.5,0,0,1,0,.7L6.45,14.28a.5.5,0,0,1-.71,0Z"
          transform="translate(-5.02 -1.59)" />
      </svg></span>
  </div>
  <div id="figure-downloads--figure-with-image-content" class="ons-details__content ons-js-details-content">
    <ul class="ons-list ons-list--bare">
      <li class="ons-list__item">
        <a href="/img/small/woman-in-purple-dress-shirt.jpg" class="ons-list__link" download="file">High resolution
          image (JPG format, 1.2MB)</a>
      </li>
      <li class="ons-list__item">
        <a href="/img/small/woman-in-purple-dress-shirt.jpg" class="ons-list__link" download="file">High resolution
          image (JPG format, 1.2MB)</a>
      </li>
    </ul>
  </div>
</div>

When to use this component

Figures support narrative content by providing clear reference points, such as “Figure 2”. They help to visualise the data and should be used to support the surrounding commentary.

The image, table and chart components are all rendered using the figure component.

When not to use this component

Do not use this component for decorative images or simple standalone statistics. Use a more appropriate component such as Headline Facts and Figures (opens in a new tab) instead.

How to use this component

A figure is made up of the following elements:

Figure number (optional)

The figure number allows the content to be referenced within the surrounding narrative, for example “Figure 3”.

If a figure number is not needed, this element can be omitted entirely.

Figure title (optional)

Guidance on figure titles (opens in a new tab) can be found in the Data visualisation section of the ONS Service Manual.

Figure subtitle (optional)

Guidance on figure subtitles (opens in a new tab) can be found in the Data visualisation section of the ONS Service Manual.

Visualisation

The figure component supports a wide range of visual content.

It does not define how a visualisation should be designed internally. Instead, it provides the surrounding structure, including spacing, styling and metadata, so that different types of visualisation can be presented consistently across the website.

Data source (optional)

The data source identifies where the data originates from, including the organisation name. View source guidance (opens in a new tab) in the Data visualisation section of the ONS Service Manual.

Footnotes (optional)

Footnotes can be used to provide additional clarification or context.

Footnotes are presented using the details component to allow users to expand them when needed.

Footnotes are only shown when available and are presented in a numbered list.
A figure may include one or multiple footnotes within the expandable section.
Footnotes may sometimes include hyperlinks to related content.

Guidance on footnotes (opens in a new tab) can be found in the Data visualisation section of the ONS Service Manual.

Download links (optional)

Download links allow users to access the underlying data or related assets.

Download links are presented within an expandable details component to allow users to expand them when needed.

Expected behaviour

Download links are only shown when available.
A figure may include one or multiple formats.
Download links should not be numbered or bulleted.
Do not show unavailable or placeholder options.

Help improve this component

If you find any issues with this component or page content, raise a bug or suggest a new feature for the Service Manual.

Cookies on ons.gov.uk