Charts Column charts

Overview

A column chart uses vertical rectangular bars to display data. Includes stacked, clustered and column with line..

Important information:

The code to build the chart examples are provided in this page. For further guidance on how to use and implement the column charts, please see the Column chart page in the Data visualisation section.

Column chart

Example Column Chart contents

Nunjucksfor Example Column Chart
Nunjucks macro optionsfor Example Column Chart
HTMLfor Example Column Chart

Nunjucks

{% from "components/chart/_macro.njk" import onsChart %}

{{
    onsChart({
        "chartType": "column",
        "description": "Public sector net debt excluding public sector banks, percentage of gross domestic product (GDP), UK, financial year ending (FYE) 1901 to October 2024",
        "theme": "primary",
        "title": "Figure 6: Net debt as a percentage of GDP remains at levels last seen in the early 1960s",
        "subtitle": "Public sector net debt excluding public sector banks, percentage of gross domestic product (GDP), UK, financial year ending (FYE) 1901 to October 2024",
        "id": "uuid",
        "caption": "Source: Public sector finances from the Office for Budget Responsibility (OBR) and the Office for National Statistics",
        "download": {
            'title': 'Download Figure 1 data',
            'itemsList': [
                {
                    "text": "Excel spreadsheet (XLSX format, 18KB)",
                    "url": "#"
                },
                {
                    "text": "Simple text file (CSV format, 25KB)",
                    "url": "#"
                },
                {
                    "text": "Image (PNG format, 25KB)",
                    "url": "#"
                }
            ]
        },
        "legend": false,
        "series": [
            {
                "data": [
                    37.8, 41.0, 43.0, 42.9, 41.8, 39.8, 37.9, 38.2, 37.6, 36.7,
                    33.9, 31.8
                ],
                "dataLabels": false,
                "name": "Public sector net debt as a % of GDP (PSND)"
            }
        ],
        "xAxis": {
            "categories": [
                "Mar 1901", "Mar 1902", "Mar 1903", "Mar 1904", "Mar 1905", "Mar 1906", "Mar 1907", "Mar 1908", "Mar 1909", "Mar 1910",
                "Mar 1911", "Mar 1912"
            ],
            "title":  "Years",
            "type": "linear",
            "tickIntervalMobile": 5
        },
        "yAxis": {
            "title": "Percentage of GDP"
        },
        "percentageHeightDesktop": 35,
        "percentageHeightMobile": 90
    })
}}

Nunjucks macro options

Name	Type	Required	Description
chartType	string	true if iframe not set	The type of chart to render. Supported types include: 'line', 'bar', 'column', 'scatter', 'columnrange', 'boxplot' and 'area'. Will be ignored if an iframe url is set.
unsupportedChartText	string	false	Optional text override to display after the chart type when it's not supported. Defaults to "chart type - chart type is not supported"
instructions	string	false	Instructions for keyboard users on how to interact with the chart. This text will be read aloud by screen readers to guide navigation and interaction.
theme	string	false	The theme to apply to the chart. Either `primary` or `alternate`. Defaults to `primary`. Will be ignored if an iframe url is set.
headingLevel	number	false	Number used to determine the heading level of the title. Use to ensure the title has a correct semantic order on the page. Accepts a value between 1 and 4, defaulting to 2 if not provided.
title	string	true	The main title of the chart.
subtitle	string	false	A subtitle that appears under the main title.
id	string	true	A unique identifier for the chart instance or iframe.
caption	string	false	A caption providing additional context for the chart.
description	string	true	A textual description of the chart for screen readers.
download	object	false	Object for (download)[#download] options.
legend	boolean	false	Whether the legend is displayed. Defaults to `true`. Note that legends are automatically hidden for single series charts. Will be ignored if an iframe url is set.
yAxis	object	true if iframe not set	Defines the vertical axis y-axis configuration parameters. Will be ignored if an iframe url is set.
xAxis	object	true if iframe not set	Defines the horizontal axis x-axis configuration parameters. Will be ignored if an iframe url is set.
series	array	true if iframe not set	The data series to be plotted, including labels and values. Will be ignored if an iframe url is set. Note: The number of series is limited by the selected theme - up to 6 series for the primary theme and 5 series for the alternate theme. Any additional series beyond these limits will be ignored and not displayed.
useStackedLayout	boolean	false	Determines whether the chart should use a stacked layout. It is useful only for bar and column charts. Will be ignored if an iframe url is set.
percentageHeightDesktop	integer	false	Sets the percentage plot height at desktop, relative to the width. If undefined the chart will fall back to the default height of 400px at desktop. Does not apply to bar charts. Will be ignored if an iframe url is set.
percentageHeightMobile	integer	false	Sets the percentage plot height at mobile, relative to the width. If undefined the chart will fall back to the default height of 400px at mobile. Does not apply to bar charts. Will be ignored if an iframe url is set.

annotations	array	false	An array of point annotations. Will be ignored if an iframe url is set.
rangeAnnotations	array	false	An array of range annotations. Will be ignored if an iframe url is set.
referenceLineAnnotations	array	false	An array of reference line annotations. Will be ignored if an iframe url is set.
estimateLineLabel	string	false	Label for the estimate line in the legend. Used in column charts with confidence intervals. Will be ignored if an iframe url is set.
uncertaintyRangeLabel	string	false	Label for the confidence interval in the legend. Used in column charts showing uncertainty ranges. Will be ignored if an iframe url is set.
iframeUrl	string	false	A url for a visualisation to display in an iframe instead of displaying a Highcharts chart.
footnotes	`Object<Footnotes>`	false	Footnotes to appear below the chart in a 'details' element
fallbackImageUrl	string	false	A url for a fallback image to display instead of the chart or iframe visualisation if JavaScript is disabled. If a fallback image is passed with an iframeUrl parameter, the iframe will be hidden for non-JavaScript users. If it is not passed, it is assumed the iframe content will provide a fallback image to be displayed inside the iframe.
fallbackImageAlt	string	false	Alt text for the fallback image - a short description only, as the description field describes the chart for screen readers. Defaults to "Fallback image for the chart as JavaScript is disabled"
iframeAspectRatio	string	false	Sets the aspect ratio for iframe charts. Only applicable when using an iframe chart. Acceptable values are 16-9, 4-3, 21-9, 1-1, 3-2, and 9-16. The value must be provided in the x-y format (e.g. 16-9). If an unsupported value is provided or a value is not provided, the aspect ratio will default to 16-9.

Download
Property	Type	Required	Description
title	string	false	The title displayed above the download options.
itemsList	array	false	An array of items available for download, each described by a (DownloadItem)[#DownloadItem].

DownloadItem
Property	Type	Required	Description
text	string	true	The label or description of the downloadable item.
url	string	true	The URL to the downloadable resource.

Y_Axis
Name	Type	Required	Description
title	string	true	The title text displayed on the y-axis. Note that for any chart type apart from bar charts, a maximum character limit of 50 characters is recommended to avoid the axis title being cut off at mobile.
labelFormat	string	false	A format string for the axis label. Examples of string formats can be found in these docs (opens in a new tab) .
tickIntervalMobile	number	false	The interval of the tick marks in axis units at mobile. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
tickIntervalDesktop	number	false	The interval of the tick marks in axis units at desktop. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
customReferenceLineValue	float or int	false	A custom value to display a darker reference line. If not supplied, the darker will appear at zero. The custom value is only used for column charts and line charts - for other chart types it will be ignored, and the darker line will appear at zero.
min	number	false	Sets the minimum value for the Y-axis. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.
max	number	false	Sets the maximum value for the Y-axis. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.
startOnTick	boolean	false	Align the axis to start on a tick. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.
endOnTick	boolean	false	Align the axis to end on a tick. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.

X_Axis
Name	Type	Required	Description
title	string	false	The title text displayed on the x-axis. Note: x-axis titles are not supported for bar chart types.
labelFormat	string	false	A format string for the x-axis label. Examples of string formats can be found in these docs (opens in a new tab) .
categories	array	false	Labels for each tick mark along the x-axis.
type	string	false	The type of axis. Can be one of `linear`, `logarithmic`, `datetime` or `category`. Defaults to linear.
tickIntervalMobile	number	false	The interval of the tick marks in axis units at mobile. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
tickIntervalDesktop	number	false	The interval of the tick marks in axis units at desktop. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
min	number	false	Sets the minimum value for the X-axis. Relevant only for scatter charts.
max	number	false	Sets the maximum value for the X-axis. Relevant only for scatter charts.
startOnTick	boolean	false	Align the axis to start on a tick. Relevant only for scatter charts.
endOnTick	boolean	false	Align the axis to end on a tick. Relevant only for scatter charts.

Series
Name	Type	Required	Description
name	string	true	The name of the series.
data	array	true	The data values for the series. Each value corresponds to a category on the x-axis.
dataLabels	boolean	false	Options for whether the DataLabel is displayed. Defaults to `false`. This option is only available for bar chart and clustered bar charts with two or fewer series, and 20 or fewer data points in any series.
marker	boolean	false	Options for whether the Marker is displayed on the data points. Defaults to `false`. This option is only available for line charts.
type	string	false	Specifies the configuration type to apply to the series. Supported types include 'line' and 'scatter'. By default, it aligns with the chart type. This is used when combining multiple chart types within a single chart. Note: Only the following chart type combinations are supported: "column with line" and "columnrange with scatter". For column with line, only one line series is supported. Additional line series will be ignored.
connectNulls	boolean	false	Whether to connect lines that have a data point missing. Only relevant for line charts.

Point annotations
Name	Type	Required	Description
text	string	true	The annotation text.
point	object	false	The x and y coordinates for the annotation
labelOffsetX (px)	int	true	The x offset in px of the label from the annotation point
labelOffsetY (px)	int	true	The y offset in px of the label from the annotation point

Point
Name	Type	Required	Description
xValue	float or int	true	The x axis value of the annotation. For category axes this is the zero based index of the x axis categories array. It must be an integer in this scenario.
yValue	float	true	The y axis value of the annotation

Range annotations
Name	Type	Required	Description
text	string	true	The annotation text.
range	Object	true	The xValue or yValue coordinates for the annotation
axis	string	true	The axis the range annotation should be applied to. Should be one of 'x' or 'y'. Note that for bar charts 'x' will be the vertical axis, and 'y' will be the horizontal axis.
labelInside	boolean	true	Whether the label for the range sits inside or outside the shaded area
labelOffsetX (px)	int	false	The horizontal offset in px of the label from it's default position. Ignored if labelInside is true.
labelOffsetY (px)	int	false	The vertical offset in px of the label from it's default position. Ignored if labelInside is true.
labelWidth (px)	int	false	The width of the label in pixels - the label text will wrap if it is wider than this value. If undefined, the label will be set to 150px wide.

Range
Name	Type	Required	Description
axisValue1	float or int	true	The starting point on the axis for the annotation. For category axes this is the zero based index of the categories array. It must be an integer in this scenario.
axisValue2	float or int	true	The ending pont on the axis for the annotation. For category axes this is the zero based index of the axis categories array. It must be an integer in this scenario.

Reference line annotations
Name	Type	Required	Description
text	string	true	The annotation text.
value	float or int	true	The x axis or y axis value for the annotation. For category axes this is the zero based index of the categories array. It must be an integer in this scenario.
axis	string	true	The axis the range annotation should be applied to. Should be one of 'x' or 'y'. Note that for bar charts 'x' will be the vertical axis, and 'y' will be the horizontal axis.
labelWidth (px)	int	false	The width of the label in pixels - the label text will wrap if it is wider than this value. If undefined, the label will be set to 150px wide.
labelOffsetX (px)	int	false	The horizontal offset in px of the label from it's default position.
labelOffsetY (px)	int	false	The vertical offset in px of the label from it's default position.

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

HTML

<div data-highcharts-base-chart data-highcharts-type="column" data-highcharts-theme="primary"
  data-highcharts-title="Figure 6: Net debt as a percentage of GDP remains at levels last seen in the early 1960s"
  data-highcharts-id="uuid" data-highcharts-percentage-height-desktop="35" data-highcharts-percentage-height-mobile="90"
  data-highcharts-x-axis-tick-interval-mobile="5">
  <figure class="ons-chart" aria-describedby="chart-audio-description-uuid">
    <h2 class="ons-chart__title">Figure 6: Net debt as a percentage of GDP remains at levels last seen in the early
      1960s</h2>
    <h3 class="ons-chart__subtitle">Public sector net debt excluding public sector banks, percentage of gross domestic
      product (GDP), UK, financial year ending (FYE) 1901 to October 2024</h3>
    <p class="ons-u-vh" id="chart-audio-description-uuid">Public sector net debt excluding public sector banks,
      percentage of gross domestic product (GDP), UK, financial year ending (FYE) 1901 to October 2024</p>
    <div data-highcharts-chart-container class="ons-chart__container" tabindex="0" role="region"
      aria-label="chart container" aria-describedby="chart-instructions-uuid">
      <div id="chart-instructions-uuid" class="ons-u-vh">Use the Tab key to move focus into the chart. Once inside, use
        the arrow keys to navigate between data points. As you move, tooltips will be announced to describe each point.
        Touch device users, explore by touch or with swipe gestures.</div>
      <div data-highcharts-chart class="ons-chart__chart"></div>
    </div>
    <figcaption class="ons-chart__caption">Source: Public sector finances from the Office for Budget Responsibility
      (OBR) and the Office for National Statistics</figcaption>
  </figure>
  <h4 class="ons-chart__download-title">Download Figure 1 data</h4>
  <ol class="ons-list">
    <li class="ons-list__item">
      <a href="#" class="ons-list__link">Excel spreadsheet (XLSX format, 18KB)</a>
    </li>
    <li class="ons-list__item">
      <a href="#" class="ons-list__link">Simple text file (CSV format, 25KB)</a>
    </li>
    <li class="ons-list__item">
      <a href="#" class="ons-list__link">Image (PNG format, 25KB)</a>
    </li>
  </ol>
  <!-- Set scripts to pass the config values as json to the JavaScript -->
  <!-- prettier-ignore-start -->
  <script type="application/json" data-highcharts-config--uuid>
    {
      "chart": {
        "type": "column"
      },
      "legend": {
        "enabled": false
      },
      "yAxis": {
        "title": {
          "text": "Percentage of GDP"
        },
        "labels": {}
      },
      "xAxis": {
        "title": {
          "text": "Years"
        },
        "categories": ["Mar 1901", "Mar 1902", "Mar 1903", "Mar 1904", "Mar 1905", "Mar 1906", "Mar 1907", "Mar 1908",
          "Mar 1909", "Mar 1910", "Mar 1911", "Mar 1912"
        ],
        "type": "linear",
        "labels": {}
      },
      "series": [{
        "name": "Public sector net debt as a % of GDP (PSND)",
        "data": [37.8, 41, 43, 42.9, 41.8, 39.8, 37.9, 38.2, 37.6, 36.7, 33.9, 31.8],
        "marker": {
          "enabled": false
        },
        "dataLabels": {
          "enabled": false
        },
        "connectNulls": false,
        "type": "column"
      }]
    }
  </script>
  <!-- prettier-ignore-end -->
</div>

Variants

There are multiple variants of this component.

Clustered column chart
Column with line chart
Column chart with confidence levels
Stacked column chart

Clustered column chart

Avoid using clustered column charts where different categories are shown by different coloured bars within a cluster. This can be confusing, because it breaks up the pattern in time series data, especially if you have more than two series.

For further guidance on how to use and implement these charts, please see the Column chart page in the Data visualisation section.

Example Clustered Column Chart contents

Nunjucksfor Example Clustered Column Chart
Nunjucks macro optionsfor Example Clustered Column Chart
HTMLfor Example Clustered Column Chart

Nunjucks

{% from "components/chart/_macro.njk" import onsChart %}

{{
    onsChart({
        "chartType": "column",
        "description": "Volume sales, monthly percentage change, seasonally adjusted, Great Britain, October 2024",
        "theme": "primary",
        "title": "Clothing stores fell back, following three months of growth",
        "subtitle": "Volume sales, monthly percentage change, seasonally adjusted, Great Britain, October 2024",
        "id": "uuid",
        "caption": "Source: Monthly Business Survey, Retail Sales Inquiry from the Office for National Statistics",
        "download": {
            'title': 'Download Figure 1 data',
            'itemsList': [
                {
                    "text": "Excel spreadsheet (XLSX format, 18KB)",
                    "url": "#"
                },
                {
                    "text": "Simple text file (CSV format, 25KB)",
                    "url": "#"
                },
                {
                    "text": "Image (PNG format, 25KB)",
                    "url": "#"
                }
            ]
        },
        "legend": true,
        "series": [
            {
                "data": [6.2, 1.5, 15.9, 1.7],
                "dataLabels": false,
                "name": "2022"
            },
            {
                "data": [2.9, -2.7, 2.9, 3.5],
                "dataLabels": false,
                "name": "2023"
            },
            {
                "data": [-1.6, 1.2, 3.2, 3.8],
                "dataLabels": false,
                "name": "2024"
            },
            {
                "data": [3.0, 2, 5.6, 2.1],
                "dataLabels": false,
                "name": "2025"
            },
            {
                "data": [2.0, 2, 3, 4],
                "dataLabels": false,
                "name": "2026"
            }
        ],
        "xAxis": {
            "categories": [
                "Food stores",
                "Non-food stores",
                "Non-store retailing ",
                "Automotive fuel"
            ],
            "type": "linear",
            "tickIntervalMobile": 5
        },
        "yAxis": {
            "title": "2022"
        },
        "percentageHeightDesktop": 35,
        "percentageHeightMobile": 90
    })
}}

Nunjucks macro options

Name	Type	Required	Description
chartType	string	true if iframe not set	The type of chart to render. Supported types include: 'line', 'bar', 'column', 'scatter', 'columnrange', 'boxplot' and 'area'. Will be ignored if an iframe url is set.
unsupportedChartText	string	false	Optional text override to display after the chart type when it's not supported. Defaults to "chart type - chart type is not supported"
instructions	string	false	Instructions for keyboard users on how to interact with the chart. This text will be read aloud by screen readers to guide navigation and interaction.
theme	string	false	The theme to apply to the chart. Either `primary` or `alternate`. Defaults to `primary`. Will be ignored if an iframe url is set.
headingLevel	number	false	Number used to determine the heading level of the title. Use to ensure the title has a correct semantic order on the page. Accepts a value between 1 and 4, defaulting to 2 if not provided.
title	string	true	The main title of the chart.
subtitle	string	false	A subtitle that appears under the main title.
id	string	true	A unique identifier for the chart instance or iframe.
caption	string	false	A caption providing additional context for the chart.
description	string	true	A textual description of the chart for screen readers.
download	object	false	Object for (download)[#download] options.
legend	boolean	false	Whether the legend is displayed. Defaults to `true`. Note that legends are automatically hidden for single series charts. Will be ignored if an iframe url is set.
yAxis	object	true if iframe not set	Defines the vertical axis y-axis configuration parameters. Will be ignored if an iframe url is set.
xAxis	object	true if iframe not set	Defines the horizontal axis x-axis configuration parameters. Will be ignored if an iframe url is set.
series	array	true if iframe not set	The data series to be plotted, including labels and values. Will be ignored if an iframe url is set. Note: The number of series is limited by the selected theme - up to 6 series for the primary theme and 5 series for the alternate theme. Any additional series beyond these limits will be ignored and not displayed.
useStackedLayout	boolean	false	Determines whether the chart should use a stacked layout. It is useful only for bar and column charts. Will be ignored if an iframe url is set.
percentageHeightDesktop	integer	false	Sets the percentage plot height at desktop, relative to the width. If undefined the chart will fall back to the default height of 400px at desktop. Does not apply to bar charts. Will be ignored if an iframe url is set.
percentageHeightMobile	integer	false	Sets the percentage plot height at mobile, relative to the width. If undefined the chart will fall back to the default height of 400px at mobile. Does not apply to bar charts. Will be ignored if an iframe url is set.

annotations	array	false	An array of point annotations. Will be ignored if an iframe url is set.
rangeAnnotations	array	false	An array of range annotations. Will be ignored if an iframe url is set.
referenceLineAnnotations	array	false	An array of reference line annotations. Will be ignored if an iframe url is set.
estimateLineLabel	string	false	Label for the estimate line in the legend. Used in column charts with confidence intervals. Will be ignored if an iframe url is set.
uncertaintyRangeLabel	string	false	Label for the confidence interval in the legend. Used in column charts showing uncertainty ranges. Will be ignored if an iframe url is set.
iframeUrl	string	false	A url for a visualisation to display in an iframe instead of displaying a Highcharts chart.
footnotes	`Object<Footnotes>`	false	Footnotes to appear below the chart in a 'details' element
fallbackImageUrl	string	false	A url for a fallback image to display instead of the chart or iframe visualisation if JavaScript is disabled. If a fallback image is passed with an iframeUrl parameter, the iframe will be hidden for non-JavaScript users. If it is not passed, it is assumed the iframe content will provide a fallback image to be displayed inside the iframe.
fallbackImageAlt	string	false	Alt text for the fallback image - a short description only, as the description field describes the chart for screen readers. Defaults to "Fallback image for the chart as JavaScript is disabled"
iframeAspectRatio	string	false	Sets the aspect ratio for iframe charts. Only applicable when using an iframe chart. Acceptable values are 16-9, 4-3, 21-9, 1-1, 3-2, and 9-16. The value must be provided in the x-y format (e.g. 16-9). If an unsupported value is provided or a value is not provided, the aspect ratio will default to 16-9.

Download
Property	Type	Required	Description
title	string	false	The title displayed above the download options.
itemsList	array	false	An array of items available for download, each described by a (DownloadItem)[#DownloadItem].

DownloadItem
Property	Type	Required	Description
text	string	true	The label or description of the downloadable item.
url	string	true	The URL to the downloadable resource.

Y_Axis
Name	Type	Required	Description
title	string	true	The title text displayed on the y-axis. Note that for any chart type apart from bar charts, a maximum character limit of 50 characters is recommended to avoid the axis title being cut off at mobile.
labelFormat	string	false	A format string for the axis label. Examples of string formats can be found in these docs (opens in a new tab) .
tickIntervalMobile	number	false	The interval of the tick marks in axis units at mobile. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
tickIntervalDesktop	number	false	The interval of the tick marks in axis units at desktop. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
customReferenceLineValue	float or int	false	A custom value to display a darker reference line. If not supplied, the darker will appear at zero. The custom value is only used for column charts and line charts - for other chart types it will be ignored, and the darker line will appear at zero.
min	number	false	Sets the minimum value for the Y-axis. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.
max	number	false	Sets the maximum value for the Y-axis. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.
startOnTick	boolean	false	Align the axis to start on a tick. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.
endOnTick	boolean	false	Align the axis to end on a tick. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.

X_Axis
Name	Type	Required	Description
title	string	false	The title text displayed on the x-axis. Note: x-axis titles are not supported for bar chart types.
labelFormat	string	false	A format string for the x-axis label. Examples of string formats can be found in these docs (opens in a new tab) .
categories	array	false	Labels for each tick mark along the x-axis.
type	string	false	The type of axis. Can be one of `linear`, `logarithmic`, `datetime` or `category`. Defaults to linear.
tickIntervalMobile	number	false	The interval of the tick marks in axis units at mobile. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
tickIntervalDesktop	number	false	The interval of the tick marks in axis units at desktop. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
min	number	false	Sets the minimum value for the X-axis. Relevant only for scatter charts.
max	number	false	Sets the maximum value for the X-axis. Relevant only for scatter charts.
startOnTick	boolean	false	Align the axis to start on a tick. Relevant only for scatter charts.
endOnTick	boolean	false	Align the axis to end on a tick. Relevant only for scatter charts.

Series
Name	Type	Required	Description
name	string	true	The name of the series.
data	array	true	The data values for the series. Each value corresponds to a category on the x-axis.
dataLabels	boolean	false	Options for whether the DataLabel is displayed. Defaults to `false`. This option is only available for bar chart and clustered bar charts with two or fewer series, and 20 or fewer data points in any series.
marker	boolean	false	Options for whether the Marker is displayed on the data points. Defaults to `false`. This option is only available for line charts.
type	string	false	Specifies the configuration type to apply to the series. Supported types include 'line' and 'scatter'. By default, it aligns with the chart type. This is used when combining multiple chart types within a single chart. Note: Only the following chart type combinations are supported: "column with line" and "columnrange with scatter". For column with line, only one line series is supported. Additional line series will be ignored.
connectNulls	boolean	false	Whether to connect lines that have a data point missing. Only relevant for line charts.

Point annotations
Name	Type	Required	Description
text	string	true	The annotation text.
point	object	false	The x and y coordinates for the annotation
labelOffsetX (px)	int	true	The x offset in px of the label from the annotation point
labelOffsetY (px)	int	true	The y offset in px of the label from the annotation point

Point
Name	Type	Required	Description
xValue	float or int	true	The x axis value of the annotation. For category axes this is the zero based index of the x axis categories array. It must be an integer in this scenario.
yValue	float	true	The y axis value of the annotation

Range annotations
Name	Type	Required	Description
text	string	true	The annotation text.
range	Object	true	The xValue or yValue coordinates for the annotation
axis	string	true	The axis the range annotation should be applied to. Should be one of 'x' or 'y'. Note that for bar charts 'x' will be the vertical axis, and 'y' will be the horizontal axis.
labelInside	boolean	true	Whether the label for the range sits inside or outside the shaded area
labelOffsetX (px)	int	false	The horizontal offset in px of the label from it's default position. Ignored if labelInside is true.
labelOffsetY (px)	int	false	The vertical offset in px of the label from it's default position. Ignored if labelInside is true.
labelWidth (px)	int	false	The width of the label in pixels - the label text will wrap if it is wider than this value. If undefined, the label will be set to 150px wide.

Range
Name	Type	Required	Description
axisValue1	float or int	true	The starting point on the axis for the annotation. For category axes this is the zero based index of the categories array. It must be an integer in this scenario.
axisValue2	float or int	true	The ending pont on the axis for the annotation. For category axes this is the zero based index of the axis categories array. It must be an integer in this scenario.

Reference line annotations
Name	Type	Required	Description
text	string	true	The annotation text.
value	float or int	true	The x axis or y axis value for the annotation. For category axes this is the zero based index of the categories array. It must be an integer in this scenario.
axis	string	true	The axis the range annotation should be applied to. Should be one of 'x' or 'y'. Note that for bar charts 'x' will be the vertical axis, and 'y' will be the horizontal axis.
labelWidth (px)	int	false	The width of the label in pixels - the label text will wrap if it is wider than this value. If undefined, the label will be set to 150px wide.
labelOffsetX (px)	int	false	The horizontal offset in px of the label from it's default position.
labelOffsetY (px)	int	false	The vertical offset in px of the label from it's default position.

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

HTML

<div data-highcharts-base-chart data-highcharts-type="column" data-highcharts-theme="primary"
  data-highcharts-title="Clothing stores fell back, following three months of growth" data-highcharts-id="uuid"
  data-highcharts-percentage-height-desktop="35" data-highcharts-percentage-height-mobile="90"
  data-highcharts-x-axis-tick-interval-mobile="5">
  <figure class="ons-chart" aria-describedby="chart-audio-description-uuid">
    <h2 class="ons-chart__title">Clothing stores fell back, following three months of growth</h2>
    <h3 class="ons-chart__subtitle">Volume sales, monthly percentage change, seasonally adjusted, Great Britain, October
      2024</h3>
    <p class="ons-u-vh" id="chart-audio-description-uuid">Volume sales, monthly percentage change, seasonally adjusted,
      Great Britain, October 2024</p>
    <div data-highcharts-chart-container class="ons-chart__container" tabindex="0" role="region"
      aria-label="chart container" aria-describedby="chart-instructions-uuid">
      <div id="chart-instructions-uuid" class="ons-u-vh">Use the Tab key to move focus into the chart. Once inside, use
        the arrow keys to navigate between data points. As you move, tooltips will be announced to describe each point.
        Touch device users, explore by touch or with swipe gestures.</div>
      <div data-highcharts-chart class="ons-chart__chart"></div>
    </div>
    <figcaption class="ons-chart__caption">Source: Monthly Business Survey, Retail Sales Inquiry from the Office for
      National Statistics</figcaption>
  </figure>
  <h4 class="ons-chart__download-title">Download Figure 1 data</h4>
  <ol class="ons-list">
    <li class="ons-list__item">
      <a href="#" class="ons-list__link">Excel spreadsheet (XLSX format, 18KB)</a>
    </li>
    <li class="ons-list__item">
      <a href="#" class="ons-list__link">Simple text file (CSV format, 25KB)</a>
    </li>
    <li class="ons-list__item">
      <a href="#" class="ons-list__link">Image (PNG format, 25KB)</a>
    </li>
  </ol>
  <!-- Set scripts to pass the config values as json to the JavaScript -->
  <!-- prettier-ignore-start -->
  <script type="application/json" data-highcharts-config--uuid>
    {
      "chart": {
        "type": "column"
      },
      "legend": {
        "enabled": true
      },
      "yAxis": {
        "title": {
          "text": "2022"
        },
        "labels": {}
      },
      "xAxis": {
        "title": {},
        "categories": ["Food stores", "Non-food stores", "Non-store retailing ", "Automotive fuel"],
        "type": "linear",
        "labels": {}
      },
      "series": [{
        "name": "2022",
        "data": [6.2, 1.5, 15.9, 1.7],
        "marker": {
          "enabled": false
        },
        "dataLabels": {
          "enabled": false
        },
        "connectNulls": false,
        "type": "column"
      }, {
        "name": "2023",
        "data": [2.9, -2.7, 2.9, 3.5],
        "marker": {
          "enabled": false
        },
        "dataLabels": {
          "enabled": false
        },
        "connectNulls": false,
        "type": "column"
      }, {
        "name": "2024",
        "data": [-1.6, 1.2, 3.2, 3.8],
        "marker": {
          "enabled": false
        },
        "dataLabels": {
          "enabled": false
        },
        "connectNulls": false,
        "type": "column"
      }, {
        "name": "2025",
        "data": [3, 2, 5.6, 2.1],
        "marker": {
          "enabled": false
        },
        "dataLabels": {
          "enabled": false
        },
        "connectNulls": false,
        "type": "column"
      }, {
        "name": "2026",
        "data": [2, 2, 3, 4],
        "marker": {
          "enabled": false
        },
        "dataLabels": {
          "enabled": false
        },
        "connectNulls": false,
        "type": "column"
      }]
    }
  </script>
  <!-- prettier-ignore-end -->
</div>

Column with line chart

Use this when you need to add a line on your column chart.

Example Column With Line Chart contents

Nunjucksfor Example Column With Line Chart
Nunjucks macro optionsfor Example Column With Line Chart
HTMLfor Example Column With Line Chart

Nunjucks

{% from "components/chart/_macro.njk" import onsChart %}

{{
    onsChart({
        "chartType": "column",
        "description": "Volume sales, seasonally adjusted, Great Britain, January 2022 to January 2025",
        "theme": "primary",
        "title": "Food stores showed a strong rise on the month, while non-food stores fell",
        "subtitle": "Figure 6: Upward contribution from housing and household services (including energy) saw the annual CPIH inflation rate rise",
        "id": "uuid",
        "caption": "Source: Monthly Business Survey, Retail Sales Inquiry from the Office for National Statistics",
        "download": {
            'title': 'Download Figure 1 data',
            'itemsList': [
                {
                    "text": "Excel spreadsheet (XLSX format, 18KB)",
                    "url": "#"
                },
                {
                    "text": "Simple text file (CSV format, 25KB)",
                    "url": "#"
                },
                {
                    "text": "Image (PNG format, 25KB)",
                    "url": "#"
                }
            ]
        },
        "legend": true,
        "xAxis": {
            "categories": ["One", "Two", "Three", "Four", "Five", "Six", "Seven", "Eight", "Nine", "Ten"],
            "type": "linear",
            "tickIntervalMobile": 5
        },
        "yAxis": {
            "title": "Percent (%)"
        },
        "series": [
            {
                "data": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
                "dataLabels": true,
                "name": "Values"
            },
            {
                "data": [
                    ["One", 6],
                    ["Two", 4],
                    ["Three", 5],
                    ["Four", 7],
                    ["Five", 2],
                    ["Six", 9],
                    ["Seven", 3],
                    ["Eight", 8],
                    ["Nine", 2],
                    ["Ten", 1]
                ],
                "dataLabels": false,
                "name": "Another test data source",
                "type": "line"
            }
        ],
        "percentageHeightDesktop": 35,
        "percentageHeightMobile": 90
    })
}}

Nunjucks macro options

Name	Type	Required	Description
chartType	string	true if iframe not set	The type of chart to render. Supported types include: 'line', 'bar', 'column', 'scatter', 'columnrange', 'boxplot' and 'area'. Will be ignored if an iframe url is set.
unsupportedChartText	string	false	Optional text override to display after the chart type when it's not supported. Defaults to "chart type - chart type is not supported"
instructions	string	false	Instructions for keyboard users on how to interact with the chart. This text will be read aloud by screen readers to guide navigation and interaction.
theme	string	false	The theme to apply to the chart. Either `primary` or `alternate`. Defaults to `primary`. Will be ignored if an iframe url is set.
headingLevel	number	false	Number used to determine the heading level of the title. Use to ensure the title has a correct semantic order on the page. Accepts a value between 1 and 4, defaulting to 2 if not provided.
title	string	true	The main title of the chart.
subtitle	string	false	A subtitle that appears under the main title.
id	string	true	A unique identifier for the chart instance or iframe.
caption	string	false	A caption providing additional context for the chart.
description	string	true	A textual description of the chart for screen readers.
download	object	false	Object for (download)[#download] options.
legend	boolean	false	Whether the legend is displayed. Defaults to `true`. Note that legends are automatically hidden for single series charts. Will be ignored if an iframe url is set.
yAxis	object	true if iframe not set	Defines the vertical axis y-axis configuration parameters. Will be ignored if an iframe url is set.
xAxis	object	true if iframe not set	Defines the horizontal axis x-axis configuration parameters. Will be ignored if an iframe url is set.
series	array	true if iframe not set	The data series to be plotted, including labels and values. Will be ignored if an iframe url is set. Note: The number of series is limited by the selected theme - up to 6 series for the primary theme and 5 series for the alternate theme. Any additional series beyond these limits will be ignored and not displayed.
useStackedLayout	boolean	false	Determines whether the chart should use a stacked layout. It is useful only for bar and column charts. Will be ignored if an iframe url is set.
percentageHeightDesktop	integer	false	Sets the percentage plot height at desktop, relative to the width. If undefined the chart will fall back to the default height of 400px at desktop. Does not apply to bar charts. Will be ignored if an iframe url is set.
percentageHeightMobile	integer	false	Sets the percentage plot height at mobile, relative to the width. If undefined the chart will fall back to the default height of 400px at mobile. Does not apply to bar charts. Will be ignored if an iframe url is set.

annotations	array	false	An array of point annotations. Will be ignored if an iframe url is set.
rangeAnnotations	array	false	An array of range annotations. Will be ignored if an iframe url is set.
referenceLineAnnotations	array	false	An array of reference line annotations. Will be ignored if an iframe url is set.
estimateLineLabel	string	false	Label for the estimate line in the legend. Used in column charts with confidence intervals. Will be ignored if an iframe url is set.
uncertaintyRangeLabel	string	false	Label for the confidence interval in the legend. Used in column charts showing uncertainty ranges. Will be ignored if an iframe url is set.
iframeUrl	string	false	A url for a visualisation to display in an iframe instead of displaying a Highcharts chart.
footnotes	`Object<Footnotes>`	false	Footnotes to appear below the chart in a 'details' element
fallbackImageUrl	string	false	A url for a fallback image to display instead of the chart or iframe visualisation if JavaScript is disabled. If a fallback image is passed with an iframeUrl parameter, the iframe will be hidden for non-JavaScript users. If it is not passed, it is assumed the iframe content will provide a fallback image to be displayed inside the iframe.
fallbackImageAlt	string	false	Alt text for the fallback image - a short description only, as the description field describes the chart for screen readers. Defaults to "Fallback image for the chart as JavaScript is disabled"
iframeAspectRatio	string	false	Sets the aspect ratio for iframe charts. Only applicable when using an iframe chart. Acceptable values are 16-9, 4-3, 21-9, 1-1, 3-2, and 9-16. The value must be provided in the x-y format (e.g. 16-9). If an unsupported value is provided or a value is not provided, the aspect ratio will default to 16-9.

Download
Property	Type	Required	Description
title	string	false	The title displayed above the download options.
itemsList	array	false	An array of items available for download, each described by a (DownloadItem)[#DownloadItem].

DownloadItem
Property	Type	Required	Description
text	string	true	The label or description of the downloadable item.
url	string	true	The URL to the downloadable resource.

Y_Axis
Name	Type	Required	Description
title	string	true	The title text displayed on the y-axis. Note that for any chart type apart from bar charts, a maximum character limit of 50 characters is recommended to avoid the axis title being cut off at mobile.
labelFormat	string	false	A format string for the axis label. Examples of string formats can be found in these docs (opens in a new tab) .
tickIntervalMobile	number	false	The interval of the tick marks in axis units at mobile. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
tickIntervalDesktop	number	false	The interval of the tick marks in axis units at desktop. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
customReferenceLineValue	float or int	false	A custom value to display a darker reference line. If not supplied, the darker will appear at zero. The custom value is only used for column charts and line charts - for other chart types it will be ignored, and the darker line will appear at zero.
min	number	false	Sets the minimum value for the Y-axis. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.
max	number	false	Sets the maximum value for the Y-axis. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.
startOnTick	boolean	false	Align the axis to start on a tick. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.
endOnTick	boolean	false	Align the axis to end on a tick. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.

X_Axis
Name	Type	Required	Description
title	string	false	The title text displayed on the x-axis. Note: x-axis titles are not supported for bar chart types.
labelFormat	string	false	A format string for the x-axis label. Examples of string formats can be found in these docs (opens in a new tab) .
categories	array	false	Labels for each tick mark along the x-axis.
type	string	false	The type of axis. Can be one of `linear`, `logarithmic`, `datetime` or `category`. Defaults to linear.
tickIntervalMobile	number	false	The interval of the tick marks in axis units at mobile. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
tickIntervalDesktop	number	false	The interval of the tick marks in axis units at desktop. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
min	number	false	Sets the minimum value for the X-axis. Relevant only for scatter charts.
max	number	false	Sets the maximum value for the X-axis. Relevant only for scatter charts.
startOnTick	boolean	false	Align the axis to start on a tick. Relevant only for scatter charts.
endOnTick	boolean	false	Align the axis to end on a tick. Relevant only for scatter charts.

Series
Name	Type	Required	Description
name	string	true	The name of the series.
data	array	true	The data values for the series. Each value corresponds to a category on the x-axis.
dataLabels	boolean	false	Options for whether the DataLabel is displayed. Defaults to `false`. This option is only available for bar chart and clustered bar charts with two or fewer series, and 20 or fewer data points in any series.
marker	boolean	false	Options for whether the Marker is displayed on the data points. Defaults to `false`. This option is only available for line charts.
type	string	false	Specifies the configuration type to apply to the series. Supported types include 'line' and 'scatter'. By default, it aligns with the chart type. This is used when combining multiple chart types within a single chart. Note: Only the following chart type combinations are supported: "column with line" and "columnrange with scatter". For column with line, only one line series is supported. Additional line series will be ignored.
connectNulls	boolean	false	Whether to connect lines that have a data point missing. Only relevant for line charts.

Point annotations
Name	Type	Required	Description
text	string	true	The annotation text.
point	object	false	The x and y coordinates for the annotation
labelOffsetX (px)	int	true	The x offset in px of the label from the annotation point
labelOffsetY (px)	int	true	The y offset in px of the label from the annotation point

Point
Name	Type	Required	Description
xValue	float or int	true	The x axis value of the annotation. For category axes this is the zero based index of the x axis categories array. It must be an integer in this scenario.
yValue	float	true	The y axis value of the annotation

Range annotations
Name	Type	Required	Description
text	string	true	The annotation text.
range	Object	true	The xValue or yValue coordinates for the annotation
axis	string	true	The axis the range annotation should be applied to. Should be one of 'x' or 'y'. Note that for bar charts 'x' will be the vertical axis, and 'y' will be the horizontal axis.
labelInside	boolean	true	Whether the label for the range sits inside or outside the shaded area
labelOffsetX (px)	int	false	The horizontal offset in px of the label from it's default position. Ignored if labelInside is true.
labelOffsetY (px)	int	false	The vertical offset in px of the label from it's default position. Ignored if labelInside is true.
labelWidth (px)	int	false	The width of the label in pixels - the label text will wrap if it is wider than this value. If undefined, the label will be set to 150px wide.

Range
Name	Type	Required	Description
axisValue1	float or int	true	The starting point on the axis for the annotation. For category axes this is the zero based index of the categories array. It must be an integer in this scenario.
axisValue2	float or int	true	The ending pont on the axis for the annotation. For category axes this is the zero based index of the axis categories array. It must be an integer in this scenario.

Reference line annotations
Name	Type	Required	Description
text	string	true	The annotation text.
value	float or int	true	The x axis or y axis value for the annotation. For category axes this is the zero based index of the categories array. It must be an integer in this scenario.
axis	string	true	The axis the range annotation should be applied to. Should be one of 'x' or 'y'. Note that for bar charts 'x' will be the vertical axis, and 'y' will be the horizontal axis.
labelWidth (px)	int	false	The width of the label in pixels - the label text will wrap if it is wider than this value. If undefined, the label will be set to 150px wide.
labelOffsetX (px)	int	false	The horizontal offset in px of the label from it's default position.
labelOffsetY (px)	int	false	The vertical offset in px of the label from it's default position.

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

HTML

<div data-highcharts-base-chart data-highcharts-type="column" data-highcharts-theme="primary"
  data-highcharts-title="Food stores showed a strong rise on the month, while non-food stores fell"
  data-highcharts-id="uuid" data-highcharts-percentage-height-desktop="35" data-highcharts-percentage-height-mobile="90"
  data-highcharts-x-axis-tick-interval-mobile="5">
  <figure class="ons-chart" aria-describedby="chart-audio-description-uuid">
    <h2 class="ons-chart__title">Food stores showed a strong rise on the month, while non-food stores fell</h2>
    <h3 class="ons-chart__subtitle">Figure 6: Upward contribution from housing and household services (including energy)
      saw the annual CPIH inflation rate rise</h3>
    <p class="ons-u-vh" id="chart-audio-description-uuid">Volume sales, seasonally adjusted, Great Britain, January 2022
      to January 2025</p>
    <div data-highcharts-chart-container class="ons-chart__container" tabindex="0" role="region"
      aria-label="chart container" aria-describedby="chart-instructions-uuid">
      <div id="chart-instructions-uuid" class="ons-u-vh">Use the Tab key to move focus into the chart. Once inside, use
        the arrow keys to navigate between data points. As you move, tooltips will be announced to describe each point.
        Touch device users, explore by touch or with swipe gestures.</div>
      <div data-highcharts-chart class="ons-chart__chart"></div>
    </div>
    <figcaption class="ons-chart__caption">Source: Monthly Business Survey, Retail Sales Inquiry from the Office for
      National Statistics</figcaption>
  </figure>
  <h4 class="ons-chart__download-title">Download Figure 1 data</h4>
  <ol class="ons-list">
    <li class="ons-list__item">
      <a href="#" class="ons-list__link">Excel spreadsheet (XLSX format, 18KB)</a>
    </li>
    <li class="ons-list__item">
      <a href="#" class="ons-list__link">Simple text file (CSV format, 25KB)</a>
    </li>
    <li class="ons-list__item">
      <a href="#" class="ons-list__link">Image (PNG format, 25KB)</a>
    </li>
  </ol>
  <!-- Set scripts to pass the config values as json to the JavaScript -->
  <!-- prettier-ignore-start -->
  <script type="application/json" data-highcharts-config--uuid>
    {
      "chart": {
        "type": "column"
      },
      "legend": {
        "enabled": true
      },
      "yAxis": {
        "title": {
          "text": "Percent (%)"
        },
        "labels": {}
      },
      "xAxis": {
        "title": {},
        "categories": ["One", "Two", "Three", "Four", "Five", "Six", "Seven", "Eight", "Nine", "Ten"],
        "type": "linear",
        "labels": {}
      },
      "series": [{
        "name": "Values",
        "data": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
        "marker": {
          "enabled": false
        },
        "dataLabels": {
          "enabled": true
        },
        "connectNulls": false,
        "type": "column"
      }, {
        "name": "Another test data source",
        "data": [
          ["One", 6],
          ["Two", 4],
          ["Three", 5],
          ["Four", 7],
          ["Five", 2],
          ["Six", 9],
          ["Seven", 3],
          ["Eight", 8],
          ["Nine", 2],
          ["Ten", 1]
        ],
        "marker": {
          "enabled": false
        },
        "dataLabels": {
          "enabled": false
        },
        "connectNulls": false,
        "type": "line"
      }]
    }
  </script>
  <!-- prettier-ignore-end -->
</div>

Column chart with confidence levels

Use this when you need to display confidence levels on your column charts.

Example Column With Confidence Levels contents

Nunjucksfor Example Column With Confidence Levels
Nunjucks macro optionsfor Example Column With Confidence Levels
HTMLfor Example Column With Confidence Levels

Nunjucks

{% from "components/chart/_macro.njk" import onsChart %}

{{
    onsChart({
        "chartType": "boxplot",
        "description": "Public sector net debt excluding public sector banks, percentage of gross domestic product (GDP), UK, financial year ending (FYE) 1901 to October 2024",
        "title": "Figure 6: Net debt as a percentage of GDP remains at levels last seen in the early 1960s",
        "subtitle": "Public sector net debt excluding public sector banks, percentage of gross domestic product (GDP), UK, financial year ending (FYE) 1901 to October 2024",
        "id": "uuid",
        "caption": "Source: Public sector finances from the Office for Budget Responsibility (OBR) and the Office for National Statistics",
        "download": {
            'title': 'Download Figure 1 data',
            'itemsList': [
                {
                    "text": "Excel spreadsheet (XLSX format, 18KB)",
                    "url": "#"
                },
                {
                    "text": "Simple text file (CSV format, 25KB)",
                    "url": "#"
                },
                {
                    "text": "Image (PNG format, 25KB)",
                    "url": "#"
                }
            ]
        },
        "legend": true,
        "series": [
            {
                "data": [
                    [760, 801, 848, 895, 965],
                    [733, 853, 939, 980, 1080],
                    [714, 762, 817, 870, 918],
                    [724, 802, 806, 871, 950],
                    [834, 836, 864, 882, 910],
                    [939, 939, 939, 939, 939],
                    [817, 817, 817, 817, 817],
                    [806, 806, 806, 806, 806],
                    [864, 864, 864, 864, 864]
                ]
            }
        ],
        'estimateLineLabel': 'Data line',
        'uncertaintyRangeLabel': 'Confidence interval',
        "xAxis": {
            "categories": ['1', '2', '3', '4', '5', '6', '7', '8', '9'],
            "title":  "Years",
            "type": "linear",
            "tickIntervalMobile": 5
        },
        "yAxis": {
            "title": "Percentage of GDP"
        },
        "percentageHeightDesktop": 35,
        "percentageHeightMobile": 90
    })
}}

Nunjucks macro options

Name	Type	Required	Description
chartType	string	true if iframe not set	The type of chart to render. Supported types include: 'line', 'bar', 'column', 'scatter', 'columnrange', 'boxplot' and 'area'. Will be ignored if an iframe url is set.
unsupportedChartText	string	false	Optional text override to display after the chart type when it's not supported. Defaults to "chart type - chart type is not supported"
instructions	string	false	Instructions for keyboard users on how to interact with the chart. This text will be read aloud by screen readers to guide navigation and interaction.
theme	string	false	The theme to apply to the chart. Either `primary` or `alternate`. Defaults to `primary`. Will be ignored if an iframe url is set.
headingLevel	number	false	Number used to determine the heading level of the title. Use to ensure the title has a correct semantic order on the page. Accepts a value between 1 and 4, defaulting to 2 if not provided.
title	string	true	The main title of the chart.
subtitle	string	false	A subtitle that appears under the main title.
id	string	true	A unique identifier for the chart instance or iframe.
caption	string	false	A caption providing additional context for the chart.
description	string	true	A textual description of the chart for screen readers.
download	object	false	Object for (download)[#download] options.
legend	boolean	false	Whether the legend is displayed. Defaults to `true`. Note that legends are automatically hidden for single series charts. Will be ignored if an iframe url is set.
yAxis	object	true if iframe not set	Defines the vertical axis y-axis configuration parameters. Will be ignored if an iframe url is set.
xAxis	object	true if iframe not set	Defines the horizontal axis x-axis configuration parameters. Will be ignored if an iframe url is set.
series	array	true if iframe not set	The data series to be plotted, including labels and values. Will be ignored if an iframe url is set. Note: The number of series is limited by the selected theme - up to 6 series for the primary theme and 5 series for the alternate theme. Any additional series beyond these limits will be ignored and not displayed.
useStackedLayout	boolean	false	Determines whether the chart should use a stacked layout. It is useful only for bar and column charts. Will be ignored if an iframe url is set.
percentageHeightDesktop	integer	false	Sets the percentage plot height at desktop, relative to the width. If undefined the chart will fall back to the default height of 400px at desktop. Does not apply to bar charts. Will be ignored if an iframe url is set.
percentageHeightMobile	integer	false	Sets the percentage plot height at mobile, relative to the width. If undefined the chart will fall back to the default height of 400px at mobile. Does not apply to bar charts. Will be ignored if an iframe url is set.

annotations	array	false	An array of point annotations. Will be ignored if an iframe url is set.
rangeAnnotations	array	false	An array of range annotations. Will be ignored if an iframe url is set.
referenceLineAnnotations	array	false	An array of reference line annotations. Will be ignored if an iframe url is set.
estimateLineLabel	string	false	Label for the estimate line in the legend. Used in column charts with confidence intervals. Will be ignored if an iframe url is set.
uncertaintyRangeLabel	string	false	Label for the confidence interval in the legend. Used in column charts showing uncertainty ranges. Will be ignored if an iframe url is set.
iframeUrl	string	false	A url for a visualisation to display in an iframe instead of displaying a Highcharts chart.
footnotes	`Object<Footnotes>`	false	Footnotes to appear below the chart in a 'details' element
fallbackImageUrl	string	false	A url for a fallback image to display instead of the chart or iframe visualisation if JavaScript is disabled. If a fallback image is passed with an iframeUrl parameter, the iframe will be hidden for non-JavaScript users. If it is not passed, it is assumed the iframe content will provide a fallback image to be displayed inside the iframe.
fallbackImageAlt	string	false	Alt text for the fallback image - a short description only, as the description field describes the chart for screen readers. Defaults to "Fallback image for the chart as JavaScript is disabled"
iframeAspectRatio	string	false	Sets the aspect ratio for iframe charts. Only applicable when using an iframe chart. Acceptable values are 16-9, 4-3, 21-9, 1-1, 3-2, and 9-16. The value must be provided in the x-y format (e.g. 16-9). If an unsupported value is provided or a value is not provided, the aspect ratio will default to 16-9.

Download
Property	Type	Required	Description
title	string	false	The title displayed above the download options.
itemsList	array	false	An array of items available for download, each described by a (DownloadItem)[#DownloadItem].

DownloadItem
Property	Type	Required	Description
text	string	true	The label or description of the downloadable item.
url	string	true	The URL to the downloadable resource.

Y_Axis
Name	Type	Required	Description
title	string	true	The title text displayed on the y-axis. Note that for any chart type apart from bar charts, a maximum character limit of 50 characters is recommended to avoid the axis title being cut off at mobile.
labelFormat	string	false	A format string for the axis label. Examples of string formats can be found in these docs (opens in a new tab) .
tickIntervalMobile	number	false	The interval of the tick marks in axis units at mobile. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
tickIntervalDesktop	number	false	The interval of the tick marks in axis units at desktop. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
customReferenceLineValue	float or int	false	A custom value to display a darker reference line. If not supplied, the darker will appear at zero. The custom value is only used for column charts and line charts - for other chart types it will be ignored, and the darker line will appear at zero.
min	number	false	Sets the minimum value for the Y-axis. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.
max	number	false	Sets the maximum value for the Y-axis. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.
startOnTick	boolean	false	Align the axis to start on a tick. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.
endOnTick	boolean	false	Align the axis to end on a tick. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.

X_Axis
Name	Type	Required	Description
title	string	false	The title text displayed on the x-axis. Note: x-axis titles are not supported for bar chart types.
labelFormat	string	false	A format string for the x-axis label. Examples of string formats can be found in these docs (opens in a new tab) .
categories	array	false	Labels for each tick mark along the x-axis.
type	string	false	The type of axis. Can be one of `linear`, `logarithmic`, `datetime` or `category`. Defaults to linear.
tickIntervalMobile	number	false	The interval of the tick marks in axis units at mobile. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
tickIntervalDesktop	number	false	The interval of the tick marks in axis units at desktop. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
min	number	false	Sets the minimum value for the X-axis. Relevant only for scatter charts.
max	number	false	Sets the maximum value for the X-axis. Relevant only for scatter charts.
startOnTick	boolean	false	Align the axis to start on a tick. Relevant only for scatter charts.
endOnTick	boolean	false	Align the axis to end on a tick. Relevant only for scatter charts.

Series
Name	Type	Required	Description
name	string	true	The name of the series.
data	array	true	The data values for the series. Each value corresponds to a category on the x-axis.
dataLabels	boolean	false	Options for whether the DataLabel is displayed. Defaults to `false`. This option is only available for bar chart and clustered bar charts with two or fewer series, and 20 or fewer data points in any series.
marker	boolean	false	Options for whether the Marker is displayed on the data points. Defaults to `false`. This option is only available for line charts.
type	string	false	Specifies the configuration type to apply to the series. Supported types include 'line' and 'scatter'. By default, it aligns with the chart type. This is used when combining multiple chart types within a single chart. Note: Only the following chart type combinations are supported: "column with line" and "columnrange with scatter". For column with line, only one line series is supported. Additional line series will be ignored.
connectNulls	boolean	false	Whether to connect lines that have a data point missing. Only relevant for line charts.

Point annotations
Name	Type	Required	Description
text	string	true	The annotation text.
point	object	false	The x and y coordinates for the annotation
labelOffsetX (px)	int	true	The x offset in px of the label from the annotation point
labelOffsetY (px)	int	true	The y offset in px of the label from the annotation point

Point
Name	Type	Required	Description
xValue	float or int	true	The x axis value of the annotation. For category axes this is the zero based index of the x axis categories array. It must be an integer in this scenario.
yValue	float	true	The y axis value of the annotation

Range annotations
Name	Type	Required	Description
text	string	true	The annotation text.
range	Object	true	The xValue or yValue coordinates for the annotation
axis	string	true	The axis the range annotation should be applied to. Should be one of 'x' or 'y'. Note that for bar charts 'x' will be the vertical axis, and 'y' will be the horizontal axis.
labelInside	boolean	true	Whether the label for the range sits inside or outside the shaded area
labelOffsetX (px)	int	false	The horizontal offset in px of the label from it's default position. Ignored if labelInside is true.
labelOffsetY (px)	int	false	The vertical offset in px of the label from it's default position. Ignored if labelInside is true.
labelWidth (px)	int	false	The width of the label in pixels - the label text will wrap if it is wider than this value. If undefined, the label will be set to 150px wide.

Range
Name	Type	Required	Description
axisValue1	float or int	true	The starting point on the axis for the annotation. For category axes this is the zero based index of the categories array. It must be an integer in this scenario.
axisValue2	float or int	true	The ending pont on the axis for the annotation. For category axes this is the zero based index of the axis categories array. It must be an integer in this scenario.

Reference line annotations
Name	Type	Required	Description
text	string	true	The annotation text.
value	float or int	true	The x axis or y axis value for the annotation. For category axes this is the zero based index of the categories array. It must be an integer in this scenario.
axis	string	true	The axis the range annotation should be applied to. Should be one of 'x' or 'y'. Note that for bar charts 'x' will be the vertical axis, and 'y' will be the horizontal axis.
labelWidth (px)	int	false	The width of the label in pixels - the label text will wrap if it is wider than this value. If undefined, the label will be set to 150px wide.
labelOffsetX (px)	int	false	The horizontal offset in px of the label from it's default position.
labelOffsetY (px)	int	false	The vertical offset in px of the label from it's default position.

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

HTML

<div data-highcharts-base-chart data-highcharts-type="boxplot" data-highcharts-theme=""
  data-highcharts-title="Figure 6: Net debt as a percentage of GDP remains at levels last seen in the early 1960s"
  data-highcharts-id="uuid" data-highcharts-percentage-height-desktop="35" data-highcharts-percentage-height-mobile="90"
  data-highcharts-x-axis-tick-interval-mobile="5" data-highcharts-estimate-line-label="Data line"
  data-highcharts-uncertainty-range-label="Confidence interval">
  <figure class="ons-chart" aria-describedby="chart-audio-description-uuid">
    <h2 class="ons-chart__title">Figure 6: Net debt as a percentage of GDP remains at levels last seen in the early
      1960s</h2>
    <h3 class="ons-chart__subtitle">Public sector net debt excluding public sector banks, percentage of gross domestic
      product (GDP), UK, financial year ending (FYE) 1901 to October 2024</h3>
    <p class="ons-u-vh" id="chart-audio-description-uuid">Public sector net debt excluding public sector banks,
      percentage of gross domestic product (GDP), UK, financial year ending (FYE) 1901 to October 2024</p>
    <div class="ons-chart__boxplot-legend">
      <div class="ons-chart__boxplot-legend-item">
        <span class="ons-chart__boxplot-legend-item ons-chart__boxplot-legend-item--uncertainty"></span>
        <span class="ons-chart__boxplot-legend-label">Confidence interval</span>
      </div>
      <div class="ons-chart__boxplot-legend-item">
        <span class="ons-chart__boxplot-legend-item ons-chart__boxplot-legend-item--estimate"></span>
        <span class="ons-chart__boxplot-legend-label">Data line</span>
      </div>
    </div>
    <div data-highcharts-chart-container class="ons-chart__container" tabindex="0" role="region"
      aria-label="chart container" aria-describedby="chart-instructions-uuid">
      <div id="chart-instructions-uuid" class="ons-u-vh">Use the Tab key to move focus into the chart. Once inside, use
        the arrow keys to navigate between data points. As you move, tooltips will be announced to describe each point.
        Touch device users, explore by touch or with swipe gestures.</div>
      <div data-highcharts-chart class="ons-chart__chart"></div>
    </div>
    <figcaption class="ons-chart__caption">Source: Public sector finances from the Office for Budget Responsibility
      (OBR) and the Office for National Statistics</figcaption>
  </figure>
  <h4 class="ons-chart__download-title">Download Figure 1 data</h4>
  <ol class="ons-list">
    <li class="ons-list__item">
      <a href="#" class="ons-list__link">Excel spreadsheet (XLSX format, 18KB)</a>
    </li>
    <li class="ons-list__item">
      <a href="#" class="ons-list__link">Simple text file (CSV format, 25KB)</a>
    </li>
    <li class="ons-list__item">
      <a href="#" class="ons-list__link">Image (PNG format, 25KB)</a>
    </li>
  </ol>
  <!-- Set scripts to pass the config values as json to the JavaScript -->
  <!-- prettier-ignore-start -->
  <script type="application/json" data-highcharts-config--uuid>
    {
      "chart": {
        "type": "boxplot"
      },
      "legend": {
        "enabled": true
      },
      "yAxis": {
        "title": {
          "text": "Percentage of GDP"
        },
        "labels": {}
      },
      "xAxis": {
        "title": {
          "text": "Years"
        },
        "categories": ["1", "2", "3", "4", "5", "6", "7", "8", "9"],
        "type": "linear",
        "labels": {}
      },
      "series": [{
        "name": "",
        "data": [
          [760, 801, 848, 895, 965],
          [733, 853, 939, 980, 1080],
          [714, 762, 817, 870, 918],
          [724, 802, 806, 871, 950],
          [834, 836, 864, 882, 910],
          [939, 939, 939, 939, 939],
          [817, 817, 817, 817, 817],
          [806, 806, 806, 806, 806],
          [864, 864, 864, 864, 864]
        ],
        "marker": {
          "enabled": false
        },
        "dataLabels": {
          "enabled": false
        },
        "connectNulls": false,
        "type": "boxplot"
      }]
    }
  </script>
  <!-- prettier-ignore-end -->
</div>

Stacked Column chart

A stacked column chart uses different colour segments within each column to show a breakdown of categories.

For further guidance on how to use and implement the stacked column charts, please see Stacked bar charts page in the Data visualisation section.

Example Stacked Column Chart contents

Nunjucksfor Example Stacked Column Chart
Nunjucks macro optionsfor Example Stacked Column Chart
HTMLfor Example Stacked Column Chart

Nunjucks

{% from "components/chart/_macro.njk" import onsChart %}
{{
    onsChart({
        "chartType": "column",
        "description": "Monthly percentage change in retail sales volume by store type, Great Britain, January to June 2025",
        "theme": "primary",
        "title": "Food stores showed a strong rise on the month, while non-food stores fell",
        "subtitle": "Figure 6: Upward contribution to monthly percentage change in total retail sales",
        "id": "uuid",
        "useStackedLayout": true,
        "caption": "Source: Monthly Business Survey, Retail Sales Inquiry from the Office for National Statistics",
        "download": {
            "title": "Download Figure 6 data",
            "itemsList": [
                { "text": "Excel spreadsheet (XLSX format, 22KB)", "url": "#" },
                { "text": "Simple text file (CSV format, 28KB)", "url": "#" },
                { "text": "Image (PNG format, 32KB)", "url": "#" }
            ]
        },
        "legend": true,
        "series": [
            {
                "name": "Food stores",
                "data": [1.5, 0.8, 1.2, 0.9, 1.1, 1.4]
            },
            {
                "name": "Non-food stores",
                "data": [0.5, -0.2, 0.6, 0.8, 0.3, 0.4]
            },
            {
                "name": "Non-store retailing",
                "data": [0.2, 0.1, 0.3, 0.2, 0.4, 0.3]
            },
            {
                "name": "Automotive fuel",
                "data": [0.3, 0.2, -0.1, 0.4, 0.2, 0.5]
            }
        ],
        "xAxis": {
            "categories": [
                "Jan 2025",
                "Feb 2025",
                "Mar 2025",
                "Apr 2025",
                "May 2025",
                "Jun 2025"
            ],
            "title": "Month"
        },
        "yAxis": {
            "title": "Monthly percentage change (%)"
        },
        "percentageHeightDesktop": 40,
        "percentageHeightMobile": 90
    })
}}

Nunjucks macro options

Name	Type	Required	Description
chartType	string	true if iframe not set	The type of chart to render. Supported types include: 'line', 'bar', 'column', 'scatter', 'columnrange', 'boxplot' and 'area'. Will be ignored if an iframe url is set.
unsupportedChartText	string	false	Optional text override to display after the chart type when it's not supported. Defaults to "chart type - chart type is not supported"
instructions	string	false	Instructions for keyboard users on how to interact with the chart. This text will be read aloud by screen readers to guide navigation and interaction.
theme	string	false	The theme to apply to the chart. Either `primary` or `alternate`. Defaults to `primary`. Will be ignored if an iframe url is set.
headingLevel	number	false	Number used to determine the heading level of the title. Use to ensure the title has a correct semantic order on the page. Accepts a value between 1 and 4, defaulting to 2 if not provided.
title	string	true	The main title of the chart.
subtitle	string	false	A subtitle that appears under the main title.
id	string	true	A unique identifier for the chart instance or iframe.
caption	string	false	A caption providing additional context for the chart.
description	string	true	A textual description of the chart for screen readers.
download	object	false	Object for (download)[#download] options.
legend	boolean	false	Whether the legend is displayed. Defaults to `true`. Note that legends are automatically hidden for single series charts. Will be ignored if an iframe url is set.
yAxis	object	true if iframe not set	Defines the vertical axis y-axis configuration parameters. Will be ignored if an iframe url is set.
xAxis	object	true if iframe not set	Defines the horizontal axis x-axis configuration parameters. Will be ignored if an iframe url is set.
series	array	true if iframe not set	The data series to be plotted, including labels and values. Will be ignored if an iframe url is set. Note: The number of series is limited by the selected theme - up to 6 series for the primary theme and 5 series for the alternate theme. Any additional series beyond these limits will be ignored and not displayed.
useStackedLayout	boolean	false	Determines whether the chart should use a stacked layout. It is useful only for bar and column charts. Will be ignored if an iframe url is set.
percentageHeightDesktop	integer	false	Sets the percentage plot height at desktop, relative to the width. If undefined the chart will fall back to the default height of 400px at desktop. Does not apply to bar charts. Will be ignored if an iframe url is set.
percentageHeightMobile	integer	false	Sets the percentage plot height at mobile, relative to the width. If undefined the chart will fall back to the default height of 400px at mobile. Does not apply to bar charts. Will be ignored if an iframe url is set.

annotations	array	false	An array of point annotations. Will be ignored if an iframe url is set.
rangeAnnotations	array	false	An array of range annotations. Will be ignored if an iframe url is set.
referenceLineAnnotations	array	false	An array of reference line annotations. Will be ignored if an iframe url is set.
estimateLineLabel	string	false	Label for the estimate line in the legend. Used in column charts with confidence intervals. Will be ignored if an iframe url is set.
uncertaintyRangeLabel	string	false	Label for the confidence interval in the legend. Used in column charts showing uncertainty ranges. Will be ignored if an iframe url is set.
iframeUrl	string	false	A url for a visualisation to display in an iframe instead of displaying a Highcharts chart.
footnotes	`Object<Footnotes>`	false	Footnotes to appear below the chart in a 'details' element
fallbackImageUrl	string	false	A url for a fallback image to display instead of the chart or iframe visualisation if JavaScript is disabled. If a fallback image is passed with an iframeUrl parameter, the iframe will be hidden for non-JavaScript users. If it is not passed, it is assumed the iframe content will provide a fallback image to be displayed inside the iframe.
fallbackImageAlt	string	false	Alt text for the fallback image - a short description only, as the description field describes the chart for screen readers. Defaults to "Fallback image for the chart as JavaScript is disabled"
iframeAspectRatio	string	false	Sets the aspect ratio for iframe charts. Only applicable when using an iframe chart. Acceptable values are 16-9, 4-3, 21-9, 1-1, 3-2, and 9-16. The value must be provided in the x-y format (e.g. 16-9). If an unsupported value is provided or a value is not provided, the aspect ratio will default to 16-9.

Download
Property	Type	Required	Description
title	string	false	The title displayed above the download options.
itemsList	array	false	An array of items available for download, each described by a (DownloadItem)[#DownloadItem].

DownloadItem
Property	Type	Required	Description
text	string	true	The label or description of the downloadable item.
url	string	true	The URL to the downloadable resource.

Y_Axis
Name	Type	Required	Description
title	string	true	The title text displayed on the y-axis. Note that for any chart type apart from bar charts, a maximum character limit of 50 characters is recommended to avoid the axis title being cut off at mobile.
labelFormat	string	false	A format string for the axis label. Examples of string formats can be found in these docs (opens in a new tab) .
tickIntervalMobile	number	false	The interval of the tick marks in axis units at mobile. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
tickIntervalDesktop	number	false	The interval of the tick marks in axis units at desktop. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
customReferenceLineValue	float or int	false	A custom value to display a darker reference line. If not supplied, the darker will appear at zero. The custom value is only used for column charts and line charts - for other chart types it will be ignored, and the darker line will appear at zero.
min	number	false	Sets the minimum value for the Y-axis. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.
max	number	false	Sets the maximum value for the Y-axis. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.
startOnTick	boolean	false	Align the axis to start on a tick. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.
endOnTick	boolean	false	Align the axis to end on a tick. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.

X_Axis
Name	Type	Required	Description
title	string	false	The title text displayed on the x-axis. Note: x-axis titles are not supported for bar chart types.
labelFormat	string	false	A format string for the x-axis label. Examples of string formats can be found in these docs (opens in a new tab) .
categories	array	false	Labels for each tick mark along the x-axis.
type	string	false	The type of axis. Can be one of `linear`, `logarithmic`, `datetime` or `category`. Defaults to linear.
tickIntervalMobile	number	false	The interval of the tick marks in axis units at mobile. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
tickIntervalDesktop	number	false	The interval of the tick marks in axis units at desktop. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
min	number	false	Sets the minimum value for the X-axis. Relevant only for scatter charts.
max	number	false	Sets the maximum value for the X-axis. Relevant only for scatter charts.
startOnTick	boolean	false	Align the axis to start on a tick. Relevant only for scatter charts.
endOnTick	boolean	false	Align the axis to end on a tick. Relevant only for scatter charts.

Series
Name	Type	Required	Description
name	string	true	The name of the series.
data	array	true	The data values for the series. Each value corresponds to a category on the x-axis.
dataLabels	boolean	false	Options for whether the DataLabel is displayed. Defaults to `false`. This option is only available for bar chart and clustered bar charts with two or fewer series, and 20 or fewer data points in any series.
marker	boolean	false	Options for whether the Marker is displayed on the data points. Defaults to `false`. This option is only available for line charts.
type	string	false	Specifies the configuration type to apply to the series. Supported types include 'line' and 'scatter'. By default, it aligns with the chart type. This is used when combining multiple chart types within a single chart. Note: Only the following chart type combinations are supported: "column with line" and "columnrange with scatter". For column with line, only one line series is supported. Additional line series will be ignored.
connectNulls	boolean	false	Whether to connect lines that have a data point missing. Only relevant for line charts.

Point annotations
Name	Type	Required	Description
text	string	true	The annotation text.
point	object	false	The x and y coordinates for the annotation
labelOffsetX (px)	int	true	The x offset in px of the label from the annotation point
labelOffsetY (px)	int	true	The y offset in px of the label from the annotation point

Point
Name	Type	Required	Description
xValue	float or int	true	The x axis value of the annotation. For category axes this is the zero based index of the x axis categories array. It must be an integer in this scenario.
yValue	float	true	The y axis value of the annotation

Range annotations
Name	Type	Required	Description
text	string	true	The annotation text.
range	Object	true	The xValue or yValue coordinates for the annotation
axis	string	true	The axis the range annotation should be applied to. Should be one of 'x' or 'y'. Note that for bar charts 'x' will be the vertical axis, and 'y' will be the horizontal axis.
labelInside	boolean	true	Whether the label for the range sits inside or outside the shaded area
labelOffsetX (px)	int	false	The horizontal offset in px of the label from it's default position. Ignored if labelInside is true.
labelOffsetY (px)	int	false	The vertical offset in px of the label from it's default position. Ignored if labelInside is true.
labelWidth (px)	int	false	The width of the label in pixels - the label text will wrap if it is wider than this value. If undefined, the label will be set to 150px wide.

Range
Name	Type	Required	Description
axisValue1	float or int	true	The starting point on the axis for the annotation. For category axes this is the zero based index of the categories array. It must be an integer in this scenario.
axisValue2	float or int	true	The ending pont on the axis for the annotation. For category axes this is the zero based index of the axis categories array. It must be an integer in this scenario.

Reference line annotations
Name	Type	Required	Description
text	string	true	The annotation text.
value	float or int	true	The x axis or y axis value for the annotation. For category axes this is the zero based index of the categories array. It must be an integer in this scenario.
axis	string	true	The axis the range annotation should be applied to. Should be one of 'x' or 'y'. Note that for bar charts 'x' will be the vertical axis, and 'y' will be the horizontal axis.
labelWidth (px)	int	false	The width of the label in pixels - the label text will wrap if it is wider than this value. If undefined, the label will be set to 150px wide.
labelOffsetX (px)	int	false	The horizontal offset in px of the label from it's default position.
labelOffsetY (px)	int	false	The vertical offset in px of the label from it's default position.

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

HTML

<div data-highcharts-base-chart data-highcharts-type="column" data-highcharts-theme="primary"
  data-highcharts-title="Food stores showed a strong rise on the month, while non-food stores fell"
  data-highcharts-id="uuid" data-highcharts-use-stacked-layout="true" data-highcharts-percentage-height-desktop="40"
  data-highcharts-percentage-height-mobile="90">
  <figure class="ons-chart" aria-describedby="chart-audio-description-uuid">
    <h2 class="ons-chart__title">Food stores showed a strong rise on the month, while non-food stores fell</h2>
    <h3 class="ons-chart__subtitle">Figure 6: Upward contribution to monthly percentage change in total retail sales
    </h3>
    <p class="ons-u-vh" id="chart-audio-description-uuid">Monthly percentage change in retail sales volume by store
      type, Great Britain, January to June 2025</p>
    <div data-highcharts-chart-container class="ons-chart__container" tabindex="0" role="region"
      aria-label="chart container" aria-describedby="chart-instructions-uuid">
      <div id="chart-instructions-uuid" class="ons-u-vh">Use the Tab key to move focus into the chart. Once inside, use
        the arrow keys to navigate between data points. As you move, tooltips will be announced to describe each point.
        Touch device users, explore by touch or with swipe gestures.</div>
      <div data-highcharts-chart class="ons-chart__chart"></div>
    </div>
    <figcaption class="ons-chart__caption">Source: Monthly Business Survey, Retail Sales Inquiry from the Office for
      National Statistics</figcaption>
  </figure>
  <h4 class="ons-chart__download-title">Download Figure 6 data</h4>
  <ol class="ons-list">
    <li class="ons-list__item">
      <a href="#" class="ons-list__link">Excel spreadsheet (XLSX format, 22KB)</a>
    </li>
    <li class="ons-list__item">
      <a href="#" class="ons-list__link">Simple text file (CSV format, 28KB)</a>
    </li>
    <li class="ons-list__item">
      <a href="#" class="ons-list__link">Image (PNG format, 32KB)</a>
    </li>
  </ol>
  <!-- Set scripts to pass the config values as json to the JavaScript -->
  <!-- prettier-ignore-start -->
  <script type="application/json" data-highcharts-config--uuid>
    {
      "chart": {
        "type": "column"
      },
      "legend": {
        "enabled": true
      },
      "yAxis": {
        "title": {
          "text": "Monthly percentage change (%)"
        },
        "labels": {}
      },
      "xAxis": {
        "title": {
          "text": "Month"
        },
        "categories": ["Jan 2025", "Feb 2025", "Mar 2025", "Apr 2025", "May 2025", "Jun 2025"],
        "labels": {}
      },
      "series": [{
        "name": "Food stores",
        "data": [1.5, 0.8, 1.2, 0.9, 1.1, 1.4],
        "marker": {
          "enabled": false
        },
        "dataLabels": {
          "enabled": false
        },
        "connectNulls": false,
        "type": "column"
      }, {
        "name": "Non-food stores",
        "data": [0.5, -0.2, 0.6, 0.8, 0.3, 0.4],
        "marker": {
          "enabled": false
        },
        "dataLabels": {
          "enabled": false
        },
        "connectNulls": false,
        "type": "column"
      }, {
        "name": "Non-store retailing",
        "data": [0.2, 0.1, 0.3, 0.2, 0.4, 0.3],
        "marker": {
          "enabled": false
        },
        "dataLabels": {
          "enabled": false
        },
        "connectNulls": false,
        "type": "column"
      }, {
        "name": "Automotive fuel",
        "data": [0.3, 0.2, -0.1, 0.4, 0.2, 0.5],
        "marker": {
          "enabled": false
        },
        "dataLabels": {
          "enabled": false
        },
        "connectNulls": false,
        "type": "column"
      }]
    }
  </script>
  <!-- prettier-ignore-end -->
</div>

Annotations

If you need to add annotations to your column charts, there are various different annotations you can add. If you require guidance on using the annotations, please see Annotations in the Data Visualisation section.

Column chart with annotations
Column chart with range annotations
Column chart with reference line annotations

Column chart with annotations

Use this when you require annotations on your column charts.

Example Column Chart With Annotations contents

Nunjucksfor Example Column Chart With Annotations
Nunjucks macro optionsfor Example Column Chart With Annotations
HTMLfor Example Column Chart With Annotations

Nunjucks

{% from "components/chart/_macro.njk" import onsChart %}

{{
    onsChart({
        "chartType": "column",
        "description": "Public sector net debt excluding public sector banks, percentage of gross domestic product (GDP), UK, financial year ending (FYE) 1901 to October 2024",
        "theme": "primary",
        "title": "Figure 6: Net debt as a percentage of GDP remains at levels last seen in the early 1960s",
        "subtitle": "Public sector net debt excluding public sector banks, percentage of gross domestic product (GDP), UK, financial year ending (FYE) 1901 to October 2024",
        "id": "uuid",
        "caption": "Source: Public sector finances from the Office for Budget Responsibility (OBR) and the Office for National Statistics",
        "download": {
            'title': 'Download Figure 1 data',
            'itemsList': [
                {
                    "text": "Excel spreadsheet (XLSX format, 18KB)",
                    "url": "#"
                },
                {
                    "text": "Simple text file (CSV format, 25KB)",
                    "url": "#"
                },
                {
                    "text": "Image (PNG format, 25KB)",
                    "url": "#"
                }
            ]
        },
        "legend": false,
        "series": [
            {
                "data": [
                    37.8, 41.0, 43.0, 42.9, 41.8, 39.8, 37.9, 38.2, 37.6, 36.7,
                    33.9, 31.8
                ],
                "dataLabels": false,
                "name": "Public sector net debt as a % of GDP (PSND)"
            }
        ],
        "xAxis": {
            "categories": [
                "Mar 1901", "Mar 1902", "Mar 1903", "Mar 1904", "Mar 1905", "Mar 1906", "Mar 1907", "Mar 1908", "Mar 1909", "Mar 1910",
                "Mar 1911", "Mar 1912"
            ],
            "title":  "Years",
            "type": "linear",
            "tickIntervalMobile": 5
        },
        "yAxis": {
            "title": "Percentage of GDP"
        },
        "percentageHeightDesktop": 35,
        "percentageHeightMobile": 90,
        "annotations": [
            {
                "text": "A test point annotation",
                "point": {"x": 11, "y": 31.8},
                "labelOffsetX": 10,
                "labelOffsetY": -50
            }
        ]
    })
}}

Nunjucks macro options

Name	Type	Required	Description
chartType	string	true if iframe not set	The type of chart to render. Supported types include: 'line', 'bar', 'column', 'scatter', 'columnrange', 'boxplot' and 'area'. Will be ignored if an iframe url is set.
unsupportedChartText	string	false	Optional text override to display after the chart type when it's not supported. Defaults to "chart type - chart type is not supported"
instructions	string	false	Instructions for keyboard users on how to interact with the chart. This text will be read aloud by screen readers to guide navigation and interaction.
theme	string	false	The theme to apply to the chart. Either `primary` or `alternate`. Defaults to `primary`. Will be ignored if an iframe url is set.
headingLevel	number	false	Number used to determine the heading level of the title. Use to ensure the title has a correct semantic order on the page. Accepts a value between 1 and 4, defaulting to 2 if not provided.
title	string	true	The main title of the chart.
subtitle	string	false	A subtitle that appears under the main title.
id	string	true	A unique identifier for the chart instance or iframe.
caption	string	false	A caption providing additional context for the chart.
description	string	true	A textual description of the chart for screen readers.
download	object	false	Object for (download)[#download] options.
legend	boolean	false	Whether the legend is displayed. Defaults to `true`. Note that legends are automatically hidden for single series charts. Will be ignored if an iframe url is set.
yAxis	object	true if iframe not set	Defines the vertical axis y-axis configuration parameters. Will be ignored if an iframe url is set.
xAxis	object	true if iframe not set	Defines the horizontal axis x-axis configuration parameters. Will be ignored if an iframe url is set.
series	array	true if iframe not set	The data series to be plotted, including labels and values. Will be ignored if an iframe url is set. Note: The number of series is limited by the selected theme - up to 6 series for the primary theme and 5 series for the alternate theme. Any additional series beyond these limits will be ignored and not displayed.
useStackedLayout	boolean	false	Determines whether the chart should use a stacked layout. It is useful only for bar and column charts. Will be ignored if an iframe url is set.
percentageHeightDesktop	integer	false	Sets the percentage plot height at desktop, relative to the width. If undefined the chart will fall back to the default height of 400px at desktop. Does not apply to bar charts. Will be ignored if an iframe url is set.
percentageHeightMobile	integer	false	Sets the percentage plot height at mobile, relative to the width. If undefined the chart will fall back to the default height of 400px at mobile. Does not apply to bar charts. Will be ignored if an iframe url is set.

annotations	array	false	An array of point annotations. Will be ignored if an iframe url is set.
rangeAnnotations	array	false	An array of range annotations. Will be ignored if an iframe url is set.
referenceLineAnnotations	array	false	An array of reference line annotations. Will be ignored if an iframe url is set.
estimateLineLabel	string	false	Label for the estimate line in the legend. Used in column charts with confidence intervals. Will be ignored if an iframe url is set.
uncertaintyRangeLabel	string	false	Label for the confidence interval in the legend. Used in column charts showing uncertainty ranges. Will be ignored if an iframe url is set.
iframeUrl	string	false	A url for a visualisation to display in an iframe instead of displaying a Highcharts chart.
footnotes	`Object<Footnotes>`	false	Footnotes to appear below the chart in a 'details' element
fallbackImageUrl	string	false	A url for a fallback image to display instead of the chart or iframe visualisation if JavaScript is disabled. If a fallback image is passed with an iframeUrl parameter, the iframe will be hidden for non-JavaScript users. If it is not passed, it is assumed the iframe content will provide a fallback image to be displayed inside the iframe.
fallbackImageAlt	string	false	Alt text for the fallback image - a short description only, as the description field describes the chart for screen readers. Defaults to "Fallback image for the chart as JavaScript is disabled"
iframeAspectRatio	string	false	Sets the aspect ratio for iframe charts. Only applicable when using an iframe chart. Acceptable values are 16-9, 4-3, 21-9, 1-1, 3-2, and 9-16. The value must be provided in the x-y format (e.g. 16-9). If an unsupported value is provided or a value is not provided, the aspect ratio will default to 16-9.

Download
Property	Type	Required	Description
title	string	false	The title displayed above the download options.
itemsList	array	false	An array of items available for download, each described by a (DownloadItem)[#DownloadItem].

DownloadItem
Property	Type	Required	Description
text	string	true	The label or description of the downloadable item.
url	string	true	The URL to the downloadable resource.

Y_Axis
Name	Type	Required	Description
title	string	true	The title text displayed on the y-axis. Note that for any chart type apart from bar charts, a maximum character limit of 50 characters is recommended to avoid the axis title being cut off at mobile.
labelFormat	string	false	A format string for the axis label. Examples of string formats can be found in these docs (opens in a new tab) .
tickIntervalMobile	number	false	The interval of the tick marks in axis units at mobile. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
tickIntervalDesktop	number	false	The interval of the tick marks in axis units at desktop. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
customReferenceLineValue	float or int	false	A custom value to display a darker reference line. If not supplied, the darker will appear at zero. The custom value is only used for column charts and line charts - for other chart types it will be ignored, and the darker line will appear at zero.
min	number	false	Sets the minimum value for the Y-axis. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.
max	number	false	Sets the maximum value for the Y-axis. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.
startOnTick	boolean	false	Align the axis to start on a tick. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.
endOnTick	boolean	false	Align the axis to end on a tick. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.

X_Axis
Name	Type	Required	Description
title	string	false	The title text displayed on the x-axis. Note: x-axis titles are not supported for bar chart types.
labelFormat	string	false	A format string for the x-axis label. Examples of string formats can be found in these docs (opens in a new tab) .
categories	array	false	Labels for each tick mark along the x-axis.
type	string	false	The type of axis. Can be one of `linear`, `logarithmic`, `datetime` or `category`. Defaults to linear.
tickIntervalMobile	number	false	The interval of the tick marks in axis units at mobile. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
tickIntervalDesktop	number	false	The interval of the tick marks in axis units at desktop. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
min	number	false	Sets the minimum value for the X-axis. Relevant only for scatter charts.
max	number	false	Sets the maximum value for the X-axis. Relevant only for scatter charts.
startOnTick	boolean	false	Align the axis to start on a tick. Relevant only for scatter charts.
endOnTick	boolean	false	Align the axis to end on a tick. Relevant only for scatter charts.

Series
Name	Type	Required	Description
name	string	true	The name of the series.
data	array	true	The data values for the series. Each value corresponds to a category on the x-axis.
dataLabels	boolean	false	Options for whether the DataLabel is displayed. Defaults to `false`. This option is only available for bar chart and clustered bar charts with two or fewer series, and 20 or fewer data points in any series.
marker	boolean	false	Options for whether the Marker is displayed on the data points. Defaults to `false`. This option is only available for line charts.
type	string	false	Specifies the configuration type to apply to the series. Supported types include 'line' and 'scatter'. By default, it aligns with the chart type. This is used when combining multiple chart types within a single chart. Note: Only the following chart type combinations are supported: "column with line" and "columnrange with scatter". For column with line, only one line series is supported. Additional line series will be ignored.
connectNulls	boolean	false	Whether to connect lines that have a data point missing. Only relevant for line charts.

Point annotations
Name	Type	Required	Description
text	string	true	The annotation text.
point	object	false	The x and y coordinates for the annotation
labelOffsetX (px)	int	true	The x offset in px of the label from the annotation point
labelOffsetY (px)	int	true	The y offset in px of the label from the annotation point

Point
Name	Type	Required	Description
xValue	float or int	true	The x axis value of the annotation. For category axes this is the zero based index of the x axis categories array. It must be an integer in this scenario.
yValue	float	true	The y axis value of the annotation

Range annotations
Name	Type	Required	Description
text	string	true	The annotation text.
range	Object	true	The xValue or yValue coordinates for the annotation
axis	string	true	The axis the range annotation should be applied to. Should be one of 'x' or 'y'. Note that for bar charts 'x' will be the vertical axis, and 'y' will be the horizontal axis.
labelInside	boolean	true	Whether the label for the range sits inside or outside the shaded area
labelOffsetX (px)	int	false	The horizontal offset in px of the label from it's default position. Ignored if labelInside is true.
labelOffsetY (px)	int	false	The vertical offset in px of the label from it's default position. Ignored if labelInside is true.
labelWidth (px)	int	false	The width of the label in pixels - the label text will wrap if it is wider than this value. If undefined, the label will be set to 150px wide.

Range
Name	Type	Required	Description
axisValue1	float or int	true	The starting point on the axis for the annotation. For category axes this is the zero based index of the categories array. It must be an integer in this scenario.
axisValue2	float or int	true	The ending pont on the axis for the annotation. For category axes this is the zero based index of the axis categories array. It must be an integer in this scenario.

Reference line annotations
Name	Type	Required	Description
text	string	true	The annotation text.
value	float or int	true	The x axis or y axis value for the annotation. For category axes this is the zero based index of the categories array. It must be an integer in this scenario.
axis	string	true	The axis the range annotation should be applied to. Should be one of 'x' or 'y'. Note that for bar charts 'x' will be the vertical axis, and 'y' will be the horizontal axis.
labelWidth (px)	int	false	The width of the label in pixels - the label text will wrap if it is wider than this value. If undefined, the label will be set to 150px wide.
labelOffsetX (px)	int	false	The horizontal offset in px of the label from it's default position.
labelOffsetY (px)	int	false	The vertical offset in px of the label from it's default position.

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

HTML

<div data-highcharts-base-chart data-highcharts-type="column" data-highcharts-theme="primary"
  data-highcharts-title="Figure 6: Net debt as a percentage of GDP remains at levels last seen in the early 1960s"
  data-highcharts-id="uuid" data-highcharts-percentage-height-desktop="35" data-highcharts-percentage-height-mobile="90"
  data-highcharts-x-axis-tick-interval-mobile="5">
  <figure class="ons-chart" aria-describedby="chart-audio-description-uuid">
    <h2 class="ons-chart__title">Figure 6: Net debt as a percentage of GDP remains at levels last seen in the early
      1960s</h2>
    <h3 class="ons-chart__subtitle">Public sector net debt excluding public sector banks, percentage of gross domestic
      product (GDP), UK, financial year ending (FYE) 1901 to October 2024</h3>
    <p class="ons-u-vh" id="chart-audio-description-uuid">Public sector net debt excluding public sector banks,
      percentage of gross domestic product (GDP), UK, financial year ending (FYE) 1901 to October 2024</p>
    <div data-highcharts-chart-container class="ons-chart__container" tabindex="0" role="region"
      aria-label="chart container" aria-describedby="chart-instructions-uuid">
      <div id="chart-instructions-uuid" class="ons-u-vh">Use the Tab key to move focus into the chart. Once inside, use
        the arrow keys to navigate between data points. As you move, tooltips will be announced to describe each point.
        Touch device users, explore by touch or with swipe gestures.</div>
      <div data-highcharts-chart class="ons-chart__chart"></div>
    </div>
    <ul class="ons-chart__annotations-footnotes" aria-hidden="true" data-annotations-footnotes>
      <li class="ons-chart__annotations-footnotes_item">
        <span class="ons-chart__annotations-footnotes-number">1</span> A test point annotation
      </li>
    </ul>
    <figcaption class="ons-chart__caption">Source: Public sector finances from the Office for Budget Responsibility
      (OBR) and the Office for National Statistics</figcaption>
  </figure>
  <h4 class="ons-chart__download-title">Download Figure 1 data</h4>
  <ol class="ons-list">
    <li class="ons-list__item">
      <a href="#" class="ons-list__link">Excel spreadsheet (XLSX format, 18KB)</a>
    </li>
    <li class="ons-list__item">
      <a href="#" class="ons-list__link">Simple text file (CSV format, 25KB)</a>
    </li>
    <li class="ons-list__item">
      <a href="#" class="ons-list__link">Image (PNG format, 25KB)</a>
    </li>
  </ol>
  <!-- Set scripts to pass the config values as json to the JavaScript -->
  <!-- prettier-ignore-start -->
  <script type="application/json" data-highcharts-config--uuid>
    {
      "chart": {
        "type": "column"
      },
      "legend": {
        "enabled": false
      },
      "yAxis": {
        "title": {
          "text": "Percentage of GDP"
        },
        "labels": {}
      },
      "xAxis": {
        "title": {
          "text": "Years"
        },
        "categories": ["Mar 1901", "Mar 1902", "Mar 1903", "Mar 1904", "Mar 1905", "Mar 1906", "Mar 1907", "Mar 1908",
          "Mar 1909", "Mar 1910", "Mar 1911", "Mar 1912"
        ],
        "type": "linear",
        "labels": {}
      },
      "series": [{
        "name": "Public sector net debt as a % of GDP (PSND)",
        "data": [37.8, 41, 43, 42.9, 41.8, 39.8, 37.9, 38.2, 37.6, 36.7, 33.9, 31.8],
        "marker": {
          "enabled": false
        },
        "dataLabels": {
          "enabled": false
        },
        "connectNulls": false,
        "type": "column"
      }]
    }
  </script>
  <script type="application/json" data-highcharts-annotations--uuid>
    [{
      "text": "A test point annotation",
      "point": {
        "x": 11,
        "y": 31.8
      },
      "labelOffsetX": 10,
      "labelOffsetY": -50
    }]
  </script>
  <!-- prettier-ignore-end -->
</div>

Column chart with range annotations

Use this when you require range annotations on your column charts.

Open this example in a new tab(Example Column Chart With Range Annotations)

Example Column Chart With Range Annotations contents

Nunjucksfor Example Column Chart With Range Annotations
Nunjucks macro optionsfor Example Column Chart With Range Annotations
HTMLfor Example Column Chart With Range Annotations

Nunjucks

{% from "components/chart/_macro.njk" import onsChart %}

{{
    onsChart({
        "chartType": "column",
        "description": "Public sector net debt excluding public sector banks, percentage of gross domestic product (GDP), UK, financial year ending (FYE) 1901 to October 2024",
        "theme": "primary",
        "title": "Figure 6: Net debt as a percentage of GDP remains at levels last seen in the early 1960s",
        "subtitle": "Public sector net debt excluding public sector banks, percentage of gross domestic product (GDP), UK, financial year ending (FYE) 1901 to October 2024",
        "id": "uuid",
        "caption": "Source: Public sector finances from the Office for Budget Responsibility (OBR) and the Office for National Statistics",
        "download": {
            'title': 'Download Figure 1 data',
            'itemsList': [
                {
                    "text": "Excel spreadsheet (XLSX format, 18KB)",
                    "url": "#"
                },
                {
                    "text": "Simple text file (CSV format, 25KB)",
                    "url": "#"
                },
                {
                    "text": "Image (PNG format, 25KB)",
                    "url": "#"
                }
            ]
        },
        "legend": false,
        "series": [
            {
                "data": [
                    37.8, 41.0, 43.0, 42.9, 41.8, 39.8, 37.9, 38.2, 37.6, 36.7,
                    33.9, 31.8
                ],
                "dataLabels": false,
                "name": "Public sector net debt as a % of GDP (PSND)"
            }
        ],
        "xAxis": {
            "categories": [
                "Mar 1901", "Mar 1902", "Mar 1903", "Mar 1904", "Mar 1905", "Mar 1906", "Mar 1907", "Mar 1908", "Mar 1909", "Mar 1910",
                "Mar 1911", "Mar 1912"
            ],
            "title":  "Years",
            "type": "linear",
            "tickIntervalMobile": 5
        },
        "yAxis": {
            "title": "Percentage of GDP"
        },
        "percentageHeightDesktop": 35,
        "percentageHeightMobile": 90,
        "rangeAnnotations": [
            {
                "text": "A test x axis range annotation",
                "range": {"axisValue1": 4, "axisValue2": 7},
                "axis": "x",
                "labelOffsetX": 200,
                "labelOffsetY": 0
            }
        ]
    })
}}

Nunjucks macro options

Name	Type	Required	Description
chartType	string	true if iframe not set	The type of chart to render. Supported types include: 'line', 'bar', 'column', 'scatter', 'columnrange', 'boxplot' and 'area'. Will be ignored if an iframe url is set.
unsupportedChartText	string	false	Optional text override to display after the chart type when it's not supported. Defaults to "chart type - chart type is not supported"
instructions	string	false	Instructions for keyboard users on how to interact with the chart. This text will be read aloud by screen readers to guide navigation and interaction.
theme	string	false	The theme to apply to the chart. Either `primary` or `alternate`. Defaults to `primary`. Will be ignored if an iframe url is set.
headingLevel	number	false	Number used to determine the heading level of the title. Use to ensure the title has a correct semantic order on the page. Accepts a value between 1 and 4, defaulting to 2 if not provided.
title	string	true	The main title of the chart.
subtitle	string	false	A subtitle that appears under the main title.
id	string	true	A unique identifier for the chart instance or iframe.
caption	string	false	A caption providing additional context for the chart.
description	string	true	A textual description of the chart for screen readers.
download	object	false	Object for (download)[#download] options.
legend	boolean	false	Whether the legend is displayed. Defaults to `true`. Note that legends are automatically hidden for single series charts. Will be ignored if an iframe url is set.
yAxis	object	true if iframe not set	Defines the vertical axis y-axis configuration parameters. Will be ignored if an iframe url is set.
xAxis	object	true if iframe not set	Defines the horizontal axis x-axis configuration parameters. Will be ignored if an iframe url is set.
series	array	true if iframe not set	The data series to be plotted, including labels and values. Will be ignored if an iframe url is set. Note: The number of series is limited by the selected theme - up to 6 series for the primary theme and 5 series for the alternate theme. Any additional series beyond these limits will be ignored and not displayed.
useStackedLayout	boolean	false	Determines whether the chart should use a stacked layout. It is useful only for bar and column charts. Will be ignored if an iframe url is set.
percentageHeightDesktop	integer	false	Sets the percentage plot height at desktop, relative to the width. If undefined the chart will fall back to the default height of 400px at desktop. Does not apply to bar charts. Will be ignored if an iframe url is set.
percentageHeightMobile	integer	false	Sets the percentage plot height at mobile, relative to the width. If undefined the chart will fall back to the default height of 400px at mobile. Does not apply to bar charts. Will be ignored if an iframe url is set.

annotations	array	false	An array of point annotations. Will be ignored if an iframe url is set.
rangeAnnotations	array	false	An array of range annotations. Will be ignored if an iframe url is set.
referenceLineAnnotations	array	false	An array of reference line annotations. Will be ignored if an iframe url is set.
estimateLineLabel	string	false	Label for the estimate line in the legend. Used in column charts with confidence intervals. Will be ignored if an iframe url is set.
uncertaintyRangeLabel	string	false	Label for the confidence interval in the legend. Used in column charts showing uncertainty ranges. Will be ignored if an iframe url is set.
iframeUrl	string	false	A url for a visualisation to display in an iframe instead of displaying a Highcharts chart.
footnotes	`Object<Footnotes>`	false	Footnotes to appear below the chart in a 'details' element
fallbackImageUrl	string	false	A url for a fallback image to display instead of the chart or iframe visualisation if JavaScript is disabled. If a fallback image is passed with an iframeUrl parameter, the iframe will be hidden for non-JavaScript users. If it is not passed, it is assumed the iframe content will provide a fallback image to be displayed inside the iframe.
fallbackImageAlt	string	false	Alt text for the fallback image - a short description only, as the description field describes the chart for screen readers. Defaults to "Fallback image for the chart as JavaScript is disabled"
iframeAspectRatio	string	false	Sets the aspect ratio for iframe charts. Only applicable when using an iframe chart. Acceptable values are 16-9, 4-3, 21-9, 1-1, 3-2, and 9-16. The value must be provided in the x-y format (e.g. 16-9). If an unsupported value is provided or a value is not provided, the aspect ratio will default to 16-9.

Download
Property	Type	Required	Description
title	string	false	The title displayed above the download options.
itemsList	array	false	An array of items available for download, each described by a (DownloadItem)[#DownloadItem].

DownloadItem
Property	Type	Required	Description
text	string	true	The label or description of the downloadable item.
url	string	true	The URL to the downloadable resource.

Y_Axis
Name	Type	Required	Description
title	string	true	The title text displayed on the y-axis. Note that for any chart type apart from bar charts, a maximum character limit of 50 characters is recommended to avoid the axis title being cut off at mobile.
labelFormat	string	false	A format string for the axis label. Examples of string formats can be found in these docs (opens in a new tab) .
tickIntervalMobile	number	false	The interval of the tick marks in axis units at mobile. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
tickIntervalDesktop	number	false	The interval of the tick marks in axis units at desktop. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
customReferenceLineValue	float or int	false	A custom value to display a darker reference line. If not supplied, the darker will appear at zero. The custom value is only used for column charts and line charts - for other chart types it will be ignored, and the darker line will appear at zero.
min	number	false	Sets the minimum value for the Y-axis. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.
max	number	false	Sets the maximum value for the Y-axis. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.
startOnTick	boolean	false	Align the axis to start on a tick. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.
endOnTick	boolean	false	Align the axis to end on a tick. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.

X_Axis
Name	Type	Required	Description
title	string	false	The title text displayed on the x-axis. Note: x-axis titles are not supported for bar chart types.
labelFormat	string	false	A format string for the x-axis label. Examples of string formats can be found in these docs (opens in a new tab) .
categories	array	false	Labels for each tick mark along the x-axis.
type	string	false	The type of axis. Can be one of `linear`, `logarithmic`, `datetime` or `category`. Defaults to linear.
tickIntervalMobile	number	false	The interval of the tick marks in axis units at mobile. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
tickIntervalDesktop	number	false	The interval of the tick marks in axis units at desktop. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
min	number	false	Sets the minimum value for the X-axis. Relevant only for scatter charts.
max	number	false	Sets the maximum value for the X-axis. Relevant only for scatter charts.
startOnTick	boolean	false	Align the axis to start on a tick. Relevant only for scatter charts.
endOnTick	boolean	false	Align the axis to end on a tick. Relevant only for scatter charts.

Series
Name	Type	Required	Description
name	string	true	The name of the series.
data	array	true	The data values for the series. Each value corresponds to a category on the x-axis.
dataLabels	boolean	false	Options for whether the DataLabel is displayed. Defaults to `false`. This option is only available for bar chart and clustered bar charts with two or fewer series, and 20 or fewer data points in any series.
marker	boolean	false	Options for whether the Marker is displayed on the data points. Defaults to `false`. This option is only available for line charts.
type	string	false	Specifies the configuration type to apply to the series. Supported types include 'line' and 'scatter'. By default, it aligns with the chart type. This is used when combining multiple chart types within a single chart. Note: Only the following chart type combinations are supported: "column with line" and "columnrange with scatter". For column with line, only one line series is supported. Additional line series will be ignored.
connectNulls	boolean	false	Whether to connect lines that have a data point missing. Only relevant for line charts.

Point annotations
Name	Type	Required	Description
text	string	true	The annotation text.
point	object	false	The x and y coordinates for the annotation
labelOffsetX (px)	int	true	The x offset in px of the label from the annotation point
labelOffsetY (px)	int	true	The y offset in px of the label from the annotation point

Point
Name	Type	Required	Description
xValue	float or int	true	The x axis value of the annotation. For category axes this is the zero based index of the x axis categories array. It must be an integer in this scenario.
yValue	float	true	The y axis value of the annotation

Range annotations
Name	Type	Required	Description
text	string	true	The annotation text.
range	Object	true	The xValue or yValue coordinates for the annotation
axis	string	true	The axis the range annotation should be applied to. Should be one of 'x' or 'y'. Note that for bar charts 'x' will be the vertical axis, and 'y' will be the horizontal axis.
labelInside	boolean	true	Whether the label for the range sits inside or outside the shaded area
labelOffsetX (px)	int	false	The horizontal offset in px of the label from it's default position. Ignored if labelInside is true.
labelOffsetY (px)	int	false	The vertical offset in px of the label from it's default position. Ignored if labelInside is true.
labelWidth (px)	int	false	The width of the label in pixels - the label text will wrap if it is wider than this value. If undefined, the label will be set to 150px wide.

Range
Name	Type	Required	Description
axisValue1	float or int	true	The starting point on the axis for the annotation. For category axes this is the zero based index of the categories array. It must be an integer in this scenario.
axisValue2	float or int	true	The ending pont on the axis for the annotation. For category axes this is the zero based index of the axis categories array. It must be an integer in this scenario.

Reference line annotations
Name	Type	Required	Description
text	string	true	The annotation text.
value	float or int	true	The x axis or y axis value for the annotation. For category axes this is the zero based index of the categories array. It must be an integer in this scenario.
axis	string	true	The axis the range annotation should be applied to. Should be one of 'x' or 'y'. Note that for bar charts 'x' will be the vertical axis, and 'y' will be the horizontal axis.
labelWidth (px)	int	false	The width of the label in pixels - the label text will wrap if it is wider than this value. If undefined, the label will be set to 150px wide.
labelOffsetX (px)	int	false	The horizontal offset in px of the label from it's default position.
labelOffsetY (px)	int	false	The vertical offset in px of the label from it's default position.

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

HTML

<div data-highcharts-base-chart data-highcharts-type="column" data-highcharts-theme="primary"
  data-highcharts-title="Figure 6: Net debt as a percentage of GDP remains at levels last seen in the early 1960s"
  data-highcharts-id="uuid" data-highcharts-percentage-height-desktop="35" data-highcharts-percentage-height-mobile="90"
  data-highcharts-x-axis-tick-interval-mobile="5">
  <figure class="ons-chart" aria-describedby="chart-audio-description-uuid">
    <h2 class="ons-chart__title">Figure 6: Net debt as a percentage of GDP remains at levels last seen in the early
      1960s</h2>
    <h3 class="ons-chart__subtitle">Public sector net debt excluding public sector banks, percentage of gross domestic
      product (GDP), UK, financial year ending (FYE) 1901 to October 2024</h3>
    <p class="ons-u-vh" id="chart-audio-description-uuid">Public sector net debt excluding public sector banks,
      percentage of gross domestic product (GDP), UK, financial year ending (FYE) 1901 to October 2024</p>
    <div data-highcharts-chart-container class="ons-chart__container" tabindex="0" role="region"
      aria-label="chart container" aria-describedby="chart-instructions-uuid">
      <div id="chart-instructions-uuid" class="ons-u-vh">Use the Tab key to move focus into the chart. Once inside, use
        the arrow keys to navigate between data points. As you move, tooltips will be announced to describe each point.
        Touch device users, explore by touch or with swipe gestures.</div>
      <div data-highcharts-chart class="ons-chart__chart"></div>
    </div>
    <ul class="ons-chart__annotations-footnotes" aria-hidden="true" data-annotations-footnotes>
      <li class="ons-chart__annotations-footnotes_item">
        <span class="ons-chart__annotations-footnotes-number">1</span> A test x axis range annotation
      </li>
    </ul>
    <figcaption class="ons-chart__caption">Source: Public sector finances from the Office for Budget Responsibility
      (OBR) and the Office for National Statistics</figcaption>
  </figure>
  <h4 class="ons-chart__download-title">Download Figure 1 data</h4>
  <ol class="ons-list">
    <li class="ons-list__item">
      <a href="#" class="ons-list__link">Excel spreadsheet (XLSX format, 18KB)</a>
    </li>
    <li class="ons-list__item">
      <a href="#" class="ons-list__link">Simple text file (CSV format, 25KB)</a>
    </li>
    <li class="ons-list__item">
      <a href="#" class="ons-list__link">Image (PNG format, 25KB)</a>
    </li>
  </ol>
  <!-- Set scripts to pass the config values as json to the JavaScript -->
  <!-- prettier-ignore-start -->
  <script type="application/json" data-highcharts-config--uuid>
    {
      "chart": {
        "type": "column"
      },
      "legend": {
        "enabled": false
      },
      "yAxis": {
        "title": {
          "text": "Percentage of GDP"
        },
        "labels": {}
      },
      "xAxis": {
        "title": {
          "text": "Years"
        },
        "categories": ["Mar 1901", "Mar 1902", "Mar 1903", "Mar 1904", "Mar 1905", "Mar 1906", "Mar 1907", "Mar 1908",
          "Mar 1909", "Mar 1910", "Mar 1911", "Mar 1912"
        ],
        "type": "linear",
        "labels": {}
      },
      "series": [{
        "name": "Public sector net debt as a % of GDP (PSND)",
        "data": [37.8, 41, 43, 42.9, 41.8, 39.8, 37.9, 38.2, 37.6, 36.7, 33.9, 31.8],
        "marker": {
          "enabled": false
        },
        "dataLabels": {
          "enabled": false
        },
        "connectNulls": false,
        "type": "column"
      }]
    }
  </script>
  <script type="application/json" data-highcharts-range-annotations--uuid>
    [{
      "text": "A test x axis range annotation",
      "range": {
        "axisValue1": 4,
        "axisValue2": 7
      },
      "axis": "x",
      "labelOffsetX": 200,
      "labelOffsetY": 0
    }]
  </script>
  <!-- prettier-ignore-end -->
</div>

Column chart with reference line annotations

Use this when you require reference line annotations on your column charts.

Open this example in a new tab(Example Column Chart With Reference Line Annotations)

Example Column Chart With Reference Line Annotations contents

Nunjucksfor Example Column Chart With Reference Line Annotations
Nunjucks macro optionsfor Example Column Chart With Reference Line Annotations
HTMLfor Example Column Chart With Reference Line Annotations

Nunjucks

{% from "components/chart/_macro.njk" import onsChart %}

{{
    onsChart({
        "chartType": "column",
        "description": "Public sector net debt excluding public sector banks, percentage of gross domestic product (GDP), UK, financial year ending (FYE) 1901 to October 2024",
        "theme": "primary",
        "title": "Figure 6: Net debt as a percentage of GDP remains at levels last seen in the early 1960s",
        "subtitle": "Public sector net debt excluding public sector banks, percentage of gross domestic product (GDP), UK, financial year ending (FYE) 1901 to October 2024",
        "id": "uuid",
        "caption": "Source: Public sector finances from the Office for Budget Responsibility (OBR) and the Office for National Statistics",
        "download": {
            'title': 'Download Figure 1 data',
            'itemsList': [
                {
                    "text": "Excel spreadsheet (XLSX format, 18KB)",
                    "url": "#"
                },
                {
                    "text": "Simple text file (CSV format, 25KB)",
                    "url": "#"
                },
                {
                    "text": "Image (PNG format, 25KB)",
                    "url": "#"
                }
            ]
        },
        "legend": false,
        "series": [
            {
                "data": [
                    37.8, 41.0, 43.0, 42.9, 41.8, 39.8, 37.9, 38.2, 37.6, 36.7,
                    33.9, 31.8
                ],
                "dataLabels": false,
                "name": "Public sector net debt as a % of GDP (PSND)"
            }
        ],
        "xAxis": {
            "categories": [
                "Mar 1901", "Mar 1902", "Mar 1903", "Mar 1904", "Mar 1905", "Mar 1906", "Mar 1907", "Mar 1908", "Mar 1909", "Mar 1910",
                "Mar 1911", "Mar 1912"
            ],
            "title":  "Years",
            "type": "linear",
            "tickIntervalMobile": 5
        },
        "yAxis": {
            "title": "Percentage of GDP"
        },
        "percentageHeightDesktop": 35,
        "percentageHeightMobile": 90,
        "referenceLineAnnotations": [
            {
                "text": "A test y axis reference line annotation",
                "value": 20,
                "axis": "y",
                "labelOffsetY": -170,
                "labelOffsetX": 0
            }
        ]
    })
}}

Nunjucks macro options

Name	Type	Required	Description
chartType	string	true if iframe not set	The type of chart to render. Supported types include: 'line', 'bar', 'column', 'scatter', 'columnrange', 'boxplot' and 'area'. Will be ignored if an iframe url is set.
unsupportedChartText	string	false	Optional text override to display after the chart type when it's not supported. Defaults to "chart type - chart type is not supported"
instructions	string	false	Instructions for keyboard users on how to interact with the chart. This text will be read aloud by screen readers to guide navigation and interaction.
theme	string	false	The theme to apply to the chart. Either `primary` or `alternate`. Defaults to `primary`. Will be ignored if an iframe url is set.
headingLevel	number	false	Number used to determine the heading level of the title. Use to ensure the title has a correct semantic order on the page. Accepts a value between 1 and 4, defaulting to 2 if not provided.
title	string	true	The main title of the chart.
subtitle	string	false	A subtitle that appears under the main title.
id	string	true	A unique identifier for the chart instance or iframe.
caption	string	false	A caption providing additional context for the chart.
description	string	true	A textual description of the chart for screen readers.
download	object	false	Object for (download)[#download] options.
legend	boolean	false	Whether the legend is displayed. Defaults to `true`. Note that legends are automatically hidden for single series charts. Will be ignored if an iframe url is set.
yAxis	object	true if iframe not set	Defines the vertical axis y-axis configuration parameters. Will be ignored if an iframe url is set.
xAxis	object	true if iframe not set	Defines the horizontal axis x-axis configuration parameters. Will be ignored if an iframe url is set.
series	array	true if iframe not set	The data series to be plotted, including labels and values. Will be ignored if an iframe url is set. Note: The number of series is limited by the selected theme - up to 6 series for the primary theme and 5 series for the alternate theme. Any additional series beyond these limits will be ignored and not displayed.
useStackedLayout	boolean	false	Determines whether the chart should use a stacked layout. It is useful only for bar and column charts. Will be ignored if an iframe url is set.
percentageHeightDesktop	integer	false	Sets the percentage plot height at desktop, relative to the width. If undefined the chart will fall back to the default height of 400px at desktop. Does not apply to bar charts. Will be ignored if an iframe url is set.
percentageHeightMobile	integer	false	Sets the percentage plot height at mobile, relative to the width. If undefined the chart will fall back to the default height of 400px at mobile. Does not apply to bar charts. Will be ignored if an iframe url is set.

annotations	array	false	An array of point annotations. Will be ignored if an iframe url is set.
rangeAnnotations	array	false	An array of range annotations. Will be ignored if an iframe url is set.
referenceLineAnnotations	array	false	An array of reference line annotations. Will be ignored if an iframe url is set.
estimateLineLabel	string	false	Label for the estimate line in the legend. Used in column charts with confidence intervals. Will be ignored if an iframe url is set.
uncertaintyRangeLabel	string	false	Label for the confidence interval in the legend. Used in column charts showing uncertainty ranges. Will be ignored if an iframe url is set.
iframeUrl	string	false	A url for a visualisation to display in an iframe instead of displaying a Highcharts chart.
footnotes	`Object<Footnotes>`	false	Footnotes to appear below the chart in a 'details' element
fallbackImageUrl	string	false	A url for a fallback image to display instead of the chart or iframe visualisation if JavaScript is disabled. If a fallback image is passed with an iframeUrl parameter, the iframe will be hidden for non-JavaScript users. If it is not passed, it is assumed the iframe content will provide a fallback image to be displayed inside the iframe.
fallbackImageAlt	string	false	Alt text for the fallback image - a short description only, as the description field describes the chart for screen readers. Defaults to "Fallback image for the chart as JavaScript is disabled"
iframeAspectRatio	string	false	Sets the aspect ratio for iframe charts. Only applicable when using an iframe chart. Acceptable values are 16-9, 4-3, 21-9, 1-1, 3-2, and 9-16. The value must be provided in the x-y format (e.g. 16-9). If an unsupported value is provided or a value is not provided, the aspect ratio will default to 16-9.

Download
Property	Type	Required	Description
title	string	false	The title displayed above the download options.
itemsList	array	false	An array of items available for download, each described by a (DownloadItem)[#DownloadItem].

DownloadItem
Property	Type	Required	Description
text	string	true	The label or description of the downloadable item.
url	string	true	The URL to the downloadable resource.

Y_Axis
Name	Type	Required	Description
title	string	true	The title text displayed on the y-axis. Note that for any chart type apart from bar charts, a maximum character limit of 50 characters is recommended to avoid the axis title being cut off at mobile.
labelFormat	string	false	A format string for the axis label. Examples of string formats can be found in these docs (opens in a new tab) .
tickIntervalMobile	number	false	The interval of the tick marks in axis units at mobile. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
tickIntervalDesktop	number	false	The interval of the tick marks in axis units at desktop. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
customReferenceLineValue	float or int	false	A custom value to display a darker reference line. If not supplied, the darker will appear at zero. The custom value is only used for column charts and line charts - for other chart types it will be ignored, and the darker line will appear at zero.
min	number	false	Sets the minimum value for the Y-axis. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.
max	number	false	Sets the maximum value for the Y-axis. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.
startOnTick	boolean	false	Align the axis to start on a tick. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.
endOnTick	boolean	false	Align the axis to end on a tick. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.

X_Axis
Name	Type	Required	Description
title	string	false	The title text displayed on the x-axis. Note: x-axis titles are not supported for bar chart types.
labelFormat	string	false	A format string for the x-axis label. Examples of string formats can be found in these docs (opens in a new tab) .
categories	array	false	Labels for each tick mark along the x-axis.
type	string	false	The type of axis. Can be one of `linear`, `logarithmic`, `datetime` or `category`. Defaults to linear.
tickIntervalMobile	number	false	The interval of the tick marks in axis units at mobile. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
tickIntervalDesktop	number	false	The interval of the tick marks in axis units at desktop. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
min	number	false	Sets the minimum value for the X-axis. Relevant only for scatter charts.
max	number	false	Sets the maximum value for the X-axis. Relevant only for scatter charts.
startOnTick	boolean	false	Align the axis to start on a tick. Relevant only for scatter charts.
endOnTick	boolean	false	Align the axis to end on a tick. Relevant only for scatter charts.

Series
Name	Type	Required	Description
name	string	true	The name of the series.
data	array	true	The data values for the series. Each value corresponds to a category on the x-axis.
dataLabels	boolean	false	Options for whether the DataLabel is displayed. Defaults to `false`. This option is only available for bar chart and clustered bar charts with two or fewer series, and 20 or fewer data points in any series.
marker	boolean	false	Options for whether the Marker is displayed on the data points. Defaults to `false`. This option is only available for line charts.
type	string	false	Specifies the configuration type to apply to the series. Supported types include 'line' and 'scatter'. By default, it aligns with the chart type. This is used when combining multiple chart types within a single chart. Note: Only the following chart type combinations are supported: "column with line" and "columnrange with scatter". For column with line, only one line series is supported. Additional line series will be ignored.
connectNulls	boolean	false	Whether to connect lines that have a data point missing. Only relevant for line charts.

Point annotations
Name	Type	Required	Description
text	string	true	The annotation text.
point	object	false	The x and y coordinates for the annotation
labelOffsetX (px)	int	true	The x offset in px of the label from the annotation point
labelOffsetY (px)	int	true	The y offset in px of the label from the annotation point

Point
Name	Type	Required	Description
xValue	float or int	true	The x axis value of the annotation. For category axes this is the zero based index of the x axis categories array. It must be an integer in this scenario.
yValue	float	true	The y axis value of the annotation

Range annotations
Name	Type	Required	Description
text	string	true	The annotation text.
range	Object	true	The xValue or yValue coordinates for the annotation
axis	string	true	The axis the range annotation should be applied to. Should be one of 'x' or 'y'. Note that for bar charts 'x' will be the vertical axis, and 'y' will be the horizontal axis.
labelInside	boolean	true	Whether the label for the range sits inside or outside the shaded area
labelOffsetX (px)	int	false	The horizontal offset in px of the label from it's default position. Ignored if labelInside is true.
labelOffsetY (px)	int	false	The vertical offset in px of the label from it's default position. Ignored if labelInside is true.
labelWidth (px)	int	false	The width of the label in pixels - the label text will wrap if it is wider than this value. If undefined, the label will be set to 150px wide.

Range
Name	Type	Required	Description
axisValue1	float or int	true	The starting point on the axis for the annotation. For category axes this is the zero based index of the categories array. It must be an integer in this scenario.
axisValue2	float or int	true	The ending pont on the axis for the annotation. For category axes this is the zero based index of the axis categories array. It must be an integer in this scenario.

Reference line annotations
Name	Type	Required	Description
text	string	true	The annotation text.
value	float or int	true	The x axis or y axis value for the annotation. For category axes this is the zero based index of the categories array. It must be an integer in this scenario.
axis	string	true	The axis the range annotation should be applied to. Should be one of 'x' or 'y'. Note that for bar charts 'x' will be the vertical axis, and 'y' will be the horizontal axis.
labelWidth (px)	int	false	The width of the label in pixels - the label text will wrap if it is wider than this value. If undefined, the label will be set to 150px wide.
labelOffsetX (px)	int	false	The horizontal offset in px of the label from it's default position.
labelOffsetY (px)	int	false	The vertical offset in px of the label from it's default position.

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

HTML

<div data-highcharts-base-chart data-highcharts-type="column" data-highcharts-theme="primary"
  data-highcharts-title="Figure 6: Net debt as a percentage of GDP remains at levels last seen in the early 1960s"
  data-highcharts-id="uuid" data-highcharts-percentage-height-desktop="35" data-highcharts-percentage-height-mobile="90"
  data-highcharts-x-axis-tick-interval-mobile="5">
  <figure class="ons-chart" aria-describedby="chart-audio-description-uuid">
    <h2 class="ons-chart__title">Figure 6: Net debt as a percentage of GDP remains at levels last seen in the early
      1960s</h2>
    <h3 class="ons-chart__subtitle">Public sector net debt excluding public sector banks, percentage of gross domestic
      product (GDP), UK, financial year ending (FYE) 1901 to October 2024</h3>
    <p class="ons-u-vh" id="chart-audio-description-uuid">Public sector net debt excluding public sector banks,
      percentage of gross domestic product (GDP), UK, financial year ending (FYE) 1901 to October 2024</p>
    <div data-highcharts-chart-container class="ons-chart__container" tabindex="0" role="region"
      aria-label="chart container" aria-describedby="chart-instructions-uuid">
      <div id="chart-instructions-uuid" class="ons-u-vh">Use the Tab key to move focus into the chart. Once inside, use
        the arrow keys to navigate between data points. As you move, tooltips will be announced to describe each point.
        Touch device users, explore by touch or with swipe gestures.</div>
      <div data-highcharts-chart class="ons-chart__chart"></div>
    </div>
    <ul class="ons-chart__annotations-footnotes" aria-hidden="true" data-annotations-footnotes>
      <li class="ons-chart__annotations-footnotes_item">
        <span class="ons-chart__annotations-footnotes-number">1</span> A test y axis reference line annotation
      </li>
    </ul>
    <figcaption class="ons-chart__caption">Source: Public sector finances from the Office for Budget Responsibility
      (OBR) and the Office for National Statistics</figcaption>
  </figure>
  <h4 class="ons-chart__download-title">Download Figure 1 data</h4>
  <ol class="ons-list">
    <li class="ons-list__item">
      <a href="#" class="ons-list__link">Excel spreadsheet (XLSX format, 18KB)</a>
    </li>
    <li class="ons-list__item">
      <a href="#" class="ons-list__link">Simple text file (CSV format, 25KB)</a>
    </li>
    <li class="ons-list__item">
      <a href="#" class="ons-list__link">Image (PNG format, 25KB)</a>
    </li>
  </ol>
  <!-- Set scripts to pass the config values as json to the JavaScript -->
  <!-- prettier-ignore-start -->
  <script type="application/json" data-highcharts-config--uuid>
    {
      "chart": {
        "type": "column"
      },
      "legend": {
        "enabled": false
      },
      "yAxis": {
        "title": {
          "text": "Percentage of GDP"
        },
        "labels": {}
      },
      "xAxis": {
        "title": {
          "text": "Years"
        },
        "categories": ["Mar 1901", "Mar 1902", "Mar 1903", "Mar 1904", "Mar 1905", "Mar 1906", "Mar 1907", "Mar 1908",
          "Mar 1909", "Mar 1910", "Mar 1911", "Mar 1912"
        ],
        "type": "linear",
        "labels": {}
      },
      "series": [{
        "name": "Public sector net debt as a % of GDP (PSND)",
        "data": [37.8, 41, 43, 42.9, 41.8, 39.8, 37.9, 38.2, 37.6, 36.7, 33.9, 31.8],
        "marker": {
          "enabled": false
        },
        "dataLabels": {
          "enabled": false
        },
        "connectNulls": false,
        "type": "column"
      }]
    }
  </script>
  <script type="application/json" data-highcharts-reference-line-annotations--uuid>
    [{
      "text": "A test y axis reference line annotation",
      "value": 20,
      "axis": "y",
      "labelOffsetY": -170,
      "labelOffsetX": 0
    }]
  </script>
  <!-- prettier-ignore-end -->
</div>

Options

There are multiple additional options for this chart.

Column chart with axis min and max values
Column chart with custom reference line value

Column chart with axis min and max values

Use this when you require axis min and max values on your column charts.

Open this example in a new tab(Example Column Chart With Axis Min And Max Values)

Example Column Chart With Axis Min And Max Values contents

Nunjucksfor Example Column Chart With Axis Min And Max Values
Nunjucks macro optionsfor Example Column Chart With Axis Min And Max Values
HTMLfor Example Column Chart With Axis Min And Max Values

Nunjucks

{% from "components/chart/_macro.njk" import onsChart %}

{{
    onsChart({
        "chartType": "column",
        "description": "Public sector net debt excluding public sector banks, percentage of gross domestic product (GDP), UK, financial year ending (FYE) 1901 to October 2024",
        "theme": "primary",
        "title": "Figure 6: Net debt as a percentage of GDP remains at levels last seen in the early 1960s",
        "subtitle": "Public sector net debt excluding public sector banks, percentage of gross domestic product (GDP), UK, financial year ending (FYE) 1901 to October 2024",
        "id": "uuid",
        "caption": "Source: Public sector finances from the Office for Budget Responsibility (OBR) and the Office for National Statistics",
        "download": {
            'title': 'Download Figure 1 data',
            'itemsList': [
                {
                    "text": "Excel spreadsheet (XLSX format, 18KB)",
                    "url": "#"
                },
                {
                    "text": "Simple text file (CSV format, 25KB)",
                    "url": "#"
                },
                {
                    "text": "Image (PNG format, 25KB)",
                    "url": "#"
                }
            ]
        },
        "legend": false,
        "series": [
            {
                "data": [
                    37.8, 41.0, 43.0, 42.9, 41.8, 39.8, 37.9, 38.2, 37.6, 36.7,
                    33.9, 31.8
                ],
                "dataLabels": false,
                "name": "Public sector net debt as a % of GDP (PSND)"
            }
        ],
        "xAxis": {
            "categories": [
                "Mar 1901", "Mar 1902", "Mar 1903", "Mar 1904", "Mar 1905", "Mar 1906", "Mar 1907", "Mar 1908", "Mar 1909", "Mar 1910",
                "Mar 1911", "Mar 1912"
            ],
            "title":  "Years",
            "type": "linear",
            "tickIntervalMobile": 5
        },
        "yAxis": {
            "title": "Percentage of GDP",
            "min": -10,
            "max": 50,
            "startOnTick": true,
            "endOnTick": false
        },
        "percentageHeightDesktop": 35,
        "percentageHeightMobile": 90
    })
}}

Nunjucks macro options

Name	Type	Required	Description
chartType	string	true if iframe not set	The type of chart to render. Supported types include: 'line', 'bar', 'column', 'scatter', 'columnrange', 'boxplot' and 'area'. Will be ignored if an iframe url is set.
unsupportedChartText	string	false	Optional text override to display after the chart type when it's not supported. Defaults to "chart type - chart type is not supported"
instructions	string	false	Instructions for keyboard users on how to interact with the chart. This text will be read aloud by screen readers to guide navigation and interaction.
theme	string	false	The theme to apply to the chart. Either `primary` or `alternate`. Defaults to `primary`. Will be ignored if an iframe url is set.
headingLevel	number	false	Number used to determine the heading level of the title. Use to ensure the title has a correct semantic order on the page. Accepts a value between 1 and 4, defaulting to 2 if not provided.
title	string	true	The main title of the chart.
subtitle	string	false	A subtitle that appears under the main title.
id	string	true	A unique identifier for the chart instance or iframe.
caption	string	false	A caption providing additional context for the chart.
description	string	true	A textual description of the chart for screen readers.
download	object	false	Object for (download)[#download] options.
legend	boolean	false	Whether the legend is displayed. Defaults to `true`. Note that legends are automatically hidden for single series charts. Will be ignored if an iframe url is set.
yAxis	object	true if iframe not set	Defines the vertical axis y-axis configuration parameters. Will be ignored if an iframe url is set.
xAxis	object	true if iframe not set	Defines the horizontal axis x-axis configuration parameters. Will be ignored if an iframe url is set.
series	array	true if iframe not set	The data series to be plotted, including labels and values. Will be ignored if an iframe url is set. Note: The number of series is limited by the selected theme - up to 6 series for the primary theme and 5 series for the alternate theme. Any additional series beyond these limits will be ignored and not displayed.
useStackedLayout	boolean	false	Determines whether the chart should use a stacked layout. It is useful only for bar and column charts. Will be ignored if an iframe url is set.
percentageHeightDesktop	integer	false	Sets the percentage plot height at desktop, relative to the width. If undefined the chart will fall back to the default height of 400px at desktop. Does not apply to bar charts. Will be ignored if an iframe url is set.
percentageHeightMobile	integer	false	Sets the percentage plot height at mobile, relative to the width. If undefined the chart will fall back to the default height of 400px at mobile. Does not apply to bar charts. Will be ignored if an iframe url is set.

annotations	array	false	An array of point annotations. Will be ignored if an iframe url is set.
rangeAnnotations	array	false	An array of range annotations. Will be ignored if an iframe url is set.
referenceLineAnnotations	array	false	An array of reference line annotations. Will be ignored if an iframe url is set.
estimateLineLabel	string	false	Label for the estimate line in the legend. Used in column charts with confidence intervals. Will be ignored if an iframe url is set.
uncertaintyRangeLabel	string	false	Label for the confidence interval in the legend. Used in column charts showing uncertainty ranges. Will be ignored if an iframe url is set.
iframeUrl	string	false	A url for a visualisation to display in an iframe instead of displaying a Highcharts chart.
footnotes	`Object<Footnotes>`	false	Footnotes to appear below the chart in a 'details' element
fallbackImageUrl	string	false	A url for a fallback image to display instead of the chart or iframe visualisation if JavaScript is disabled. If a fallback image is passed with an iframeUrl parameter, the iframe will be hidden for non-JavaScript users. If it is not passed, it is assumed the iframe content will provide a fallback image to be displayed inside the iframe.
fallbackImageAlt	string	false	Alt text for the fallback image - a short description only, as the description field describes the chart for screen readers. Defaults to "Fallback image for the chart as JavaScript is disabled"
iframeAspectRatio	string	false	Sets the aspect ratio for iframe charts. Only applicable when using an iframe chart. Acceptable values are 16-9, 4-3, 21-9, 1-1, 3-2, and 9-16. The value must be provided in the x-y format (e.g. 16-9). If an unsupported value is provided or a value is not provided, the aspect ratio will default to 16-9.

Download
Property	Type	Required	Description
title	string	false	The title displayed above the download options.
itemsList	array	false	An array of items available for download, each described by a (DownloadItem)[#DownloadItem].

DownloadItem
Property	Type	Required	Description
text	string	true	The label or description of the downloadable item.
url	string	true	The URL to the downloadable resource.

Y_Axis
Name	Type	Required	Description
title	string	true	The title text displayed on the y-axis. Note that for any chart type apart from bar charts, a maximum character limit of 50 characters is recommended to avoid the axis title being cut off at mobile.
labelFormat	string	false	A format string for the axis label. Examples of string formats can be found in these docs (opens in a new tab) .
tickIntervalMobile	number	false	The interval of the tick marks in axis units at mobile. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
tickIntervalDesktop	number	false	The interval of the tick marks in axis units at desktop. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
customReferenceLineValue	float or int	false	A custom value to display a darker reference line. If not supplied, the darker will appear at zero. The custom value is only used for column charts and line charts - for other chart types it will be ignored, and the darker line will appear at zero.
min	number	false	Sets the minimum value for the Y-axis. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.
max	number	false	Sets the maximum value for the Y-axis. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.
startOnTick	boolean	false	Align the axis to start on a tick. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.
endOnTick	boolean	false	Align the axis to end on a tick. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.

X_Axis
Name	Type	Required	Description
title	string	false	The title text displayed on the x-axis. Note: x-axis titles are not supported for bar chart types.
labelFormat	string	false	A format string for the x-axis label. Examples of string formats can be found in these docs (opens in a new tab) .
categories	array	false	Labels for each tick mark along the x-axis.
type	string	false	The type of axis. Can be one of `linear`, `logarithmic`, `datetime` or `category`. Defaults to linear.
tickIntervalMobile	number	false	The interval of the tick marks in axis units at mobile. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
tickIntervalDesktop	number	false	The interval of the tick marks in axis units at desktop. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
min	number	false	Sets the minimum value for the X-axis. Relevant only for scatter charts.
max	number	false	Sets the maximum value for the X-axis. Relevant only for scatter charts.
startOnTick	boolean	false	Align the axis to start on a tick. Relevant only for scatter charts.
endOnTick	boolean	false	Align the axis to end on a tick. Relevant only for scatter charts.

Series
Name	Type	Required	Description
name	string	true	The name of the series.
data	array	true	The data values for the series. Each value corresponds to a category on the x-axis.
dataLabels	boolean	false	Options for whether the DataLabel is displayed. Defaults to `false`. This option is only available for bar chart and clustered bar charts with two or fewer series, and 20 or fewer data points in any series.
marker	boolean	false	Options for whether the Marker is displayed on the data points. Defaults to `false`. This option is only available for line charts.
type	string	false	Specifies the configuration type to apply to the series. Supported types include 'line' and 'scatter'. By default, it aligns with the chart type. This is used when combining multiple chart types within a single chart. Note: Only the following chart type combinations are supported: "column with line" and "columnrange with scatter". For column with line, only one line series is supported. Additional line series will be ignored.
connectNulls	boolean	false	Whether to connect lines that have a data point missing. Only relevant for line charts.

Point annotations
Name	Type	Required	Description
text	string	true	The annotation text.
point	object	false	The x and y coordinates for the annotation
labelOffsetX (px)	int	true	The x offset in px of the label from the annotation point
labelOffsetY (px)	int	true	The y offset in px of the label from the annotation point

Point
Name	Type	Required	Description
xValue	float or int	true	The x axis value of the annotation. For category axes this is the zero based index of the x axis categories array. It must be an integer in this scenario.
yValue	float	true	The y axis value of the annotation

Range annotations
Name	Type	Required	Description
text	string	true	The annotation text.
range	Object	true	The xValue or yValue coordinates for the annotation
axis	string	true	The axis the range annotation should be applied to. Should be one of 'x' or 'y'. Note that for bar charts 'x' will be the vertical axis, and 'y' will be the horizontal axis.
labelInside	boolean	true	Whether the label for the range sits inside or outside the shaded area
labelOffsetX (px)	int	false	The horizontal offset in px of the label from it's default position. Ignored if labelInside is true.
labelOffsetY (px)	int	false	The vertical offset in px of the label from it's default position. Ignored if labelInside is true.
labelWidth (px)	int	false	The width of the label in pixels - the label text will wrap if it is wider than this value. If undefined, the label will be set to 150px wide.

Range
Name	Type	Required	Description
axisValue1	float or int	true	The starting point on the axis for the annotation. For category axes this is the zero based index of the categories array. It must be an integer in this scenario.
axisValue2	float or int	true	The ending pont on the axis for the annotation. For category axes this is the zero based index of the axis categories array. It must be an integer in this scenario.

Reference line annotations
Name	Type	Required	Description
text	string	true	The annotation text.
value	float or int	true	The x axis or y axis value for the annotation. For category axes this is the zero based index of the categories array. It must be an integer in this scenario.
axis	string	true	The axis the range annotation should be applied to. Should be one of 'x' or 'y'. Note that for bar charts 'x' will be the vertical axis, and 'y' will be the horizontal axis.
labelWidth (px)	int	false	The width of the label in pixels - the label text will wrap if it is wider than this value. If undefined, the label will be set to 150px wide.
labelOffsetX (px)	int	false	The horizontal offset in px of the label from it's default position.
labelOffsetY (px)	int	false	The vertical offset in px of the label from it's default position.

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

HTML

<div data-highcharts-base-chart data-highcharts-type="column" data-highcharts-theme="primary"
  data-highcharts-title="Figure 6: Net debt as a percentage of GDP remains at levels last seen in the early 1960s"
  data-highcharts-id="uuid" data-highcharts-percentage-height-desktop="35" data-highcharts-percentage-height-mobile="90"
  data-highcharts-x-axis-tick-interval-mobile="5">
  <figure class="ons-chart" aria-describedby="chart-audio-description-uuid">
    <h2 class="ons-chart__title">Figure 6: Net debt as a percentage of GDP remains at levels last seen in the early
      1960s</h2>
    <h3 class="ons-chart__subtitle">Public sector net debt excluding public sector banks, percentage of gross domestic
      product (GDP), UK, financial year ending (FYE) 1901 to October 2024</h3>
    <p class="ons-u-vh" id="chart-audio-description-uuid">Public sector net debt excluding public sector banks,
      percentage of gross domestic product (GDP), UK, financial year ending (FYE) 1901 to October 2024</p>
    <div data-highcharts-chart-container class="ons-chart__container" tabindex="0" role="region"
      aria-label="chart container" aria-describedby="chart-instructions-uuid">
      <div id="chart-instructions-uuid" class="ons-u-vh">Use the Tab key to move focus into the chart. Once inside, use
        the arrow keys to navigate between data points. As you move, tooltips will be announced to describe each point.
        Touch device users, explore by touch or with swipe gestures.</div>
      <div data-highcharts-chart class="ons-chart__chart"></div>
    </div>
    <figcaption class="ons-chart__caption">Source: Public sector finances from the Office for Budget Responsibility
      (OBR) and the Office for National Statistics</figcaption>
  </figure>
  <h4 class="ons-chart__download-title">Download Figure 1 data</h4>
  <ol class="ons-list">
    <li class="ons-list__item">
      <a href="#" class="ons-list__link">Excel spreadsheet (XLSX format, 18KB)</a>
    </li>
    <li class="ons-list__item">
      <a href="#" class="ons-list__link">Simple text file (CSV format, 25KB)</a>
    </li>
    <li class="ons-list__item">
      <a href="#" class="ons-list__link">Image (PNG format, 25KB)</a>
    </li>
  </ol>
  <!-- Set scripts to pass the config values as json to the JavaScript -->
  <!-- prettier-ignore-start -->
  <script type="application/json" data-highcharts-config--uuid>
    {
      "chart": {
        "type": "column"
      },
      "legend": {
        "enabled": false
      },
      "yAxis": {
        "title": {
          "text": "Percentage of GDP"
        },
        "labels": {},
        "min": -10,
        "max": 50,
        "startOnTick": true,
        "endOnTick": false
      },
      "xAxis": {
        "title": {
          "text": "Years"
        },
        "categories": ["Mar 1901", "Mar 1902", "Mar 1903", "Mar 1904", "Mar 1905", "Mar 1906", "Mar 1907", "Mar 1908",
          "Mar 1909", "Mar 1910", "Mar 1911", "Mar 1912"
        ],
        "type": "linear",
        "labels": {}
      },
      "series": [{
        "name": "Public sector net debt as a % of GDP (PSND)",
        "data": [37.8, 41, 43, 42.9, 41.8, 39.8, 37.9, 38.2, 37.6, 36.7, 33.9, 31.8],
        "marker": {
          "enabled": false
        },
        "dataLabels": {
          "enabled": false
        },
        "connectNulls": false,
        "type": "column"
      }]
    }
  </script>
  <!-- prettier-ignore-end -->
</div>

Column chart with custom reference line value

Use this when you require a custom reference line value on your column charts.

Open this example in a new tab(Example Column Chart With Reference Line Annotations)

Example Column Chart With Reference Line Annotations contents

Nunjucksfor Example Column Chart With Reference Line Annotations
Nunjucks macro optionsfor Example Column Chart With Reference Line Annotations
HTMLfor Example Column Chart With Reference Line Annotations

Nunjucks

{% from "components/chart/_macro.njk" import onsChart %}

{{
    onsChart({
        "chartType": "column",
        "description": "Public sector net debt excluding public sector banks, percentage of gross domestic product (GDP), UK, financial year ending (FYE) 1901 to October 2024",
        "theme": "primary",
        "title": "Figure 6: Net debt as a percentage of GDP remains at levels last seen in the early 1960s",
        "subtitle": "Public sector net debt excluding public sector banks, percentage of gross domestic product (GDP), UK, financial year ending (FYE) 1901 to October 2024",
        "id": "uuid",
        "caption": "Source: Public sector finances from the Office for Budget Responsibility (OBR) and the Office for National Statistics",
        "download": {
            'title': 'Download Figure 1 data',
            'itemsList': [
                {
                    "text": "Excel spreadsheet (XLSX format, 18KB)",
                    "url": "#"
                },
                {
                    "text": "Simple text file (CSV format, 25KB)",
                    "url": "#"
                },
                {
                    "text": "Image (PNG format, 25KB)",
                    "url": "#"
                }
            ]
        },
        "legend": false,
        "series": [
            {
                "data": [
                    37.8, 41.0, 43.0, 42.9, 41.8, 39.8, 37.9, 38.2, 37.6, 36.7,
                    33.9, 31.8
                ],
                "dataLabels": false,
                "name": "Public sector net debt as a % of GDP (PSND)"
            }
        ],
        "xAxis": {
            "categories": [
                "Mar 1901", "Mar 1902", "Mar 1903", "Mar 1904", "Mar 1905", "Mar 1906", "Mar 1907", "Mar 1908", "Mar 1909", "Mar 1910",
                "Mar 1911", "Mar 1912"
            ],
            "title":  "Years",
            "type": "linear",
            "tickIntervalMobile": 5
        },
        "yAxis": {
            "title": "Percentage of GDP"
        },
        "percentageHeightDesktop": 35,
        "percentageHeightMobile": 90,
        "referenceLineAnnotations": [
            {
                "text": "A test y axis reference line annotation",
                "value": 20,
                "axis": "y",
                "labelOffsetY": -170,
                "labelOffsetX": 0
            }
        ]
    })
}}

Nunjucks macro options

Name	Type	Required	Description
chartType	string	true if iframe not set	The type of chart to render. Supported types include: 'line', 'bar', 'column', 'scatter', 'columnrange', 'boxplot' and 'area'. Will be ignored if an iframe url is set.
unsupportedChartText	string	false	Optional text override to display after the chart type when it's not supported. Defaults to "chart type - chart type is not supported"
instructions	string	false	Instructions for keyboard users on how to interact with the chart. This text will be read aloud by screen readers to guide navigation and interaction.
theme	string	false	The theme to apply to the chart. Either `primary` or `alternate`. Defaults to `primary`. Will be ignored if an iframe url is set.
headingLevel	number	false	Number used to determine the heading level of the title. Use to ensure the title has a correct semantic order on the page. Accepts a value between 1 and 4, defaulting to 2 if not provided.
title	string	true	The main title of the chart.
subtitle	string	false	A subtitle that appears under the main title.
id	string	true	A unique identifier for the chart instance or iframe.
caption	string	false	A caption providing additional context for the chart.
description	string	true	A textual description of the chart for screen readers.
download	object	false	Object for (download)[#download] options.
legend	boolean	false	Whether the legend is displayed. Defaults to `true`. Note that legends are automatically hidden for single series charts. Will be ignored if an iframe url is set.
yAxis	object	true if iframe not set	Defines the vertical axis y-axis configuration parameters. Will be ignored if an iframe url is set.
xAxis	object	true if iframe not set	Defines the horizontal axis x-axis configuration parameters. Will be ignored if an iframe url is set.
series	array	true if iframe not set	The data series to be plotted, including labels and values. Will be ignored if an iframe url is set. Note: The number of series is limited by the selected theme - up to 6 series for the primary theme and 5 series for the alternate theme. Any additional series beyond these limits will be ignored and not displayed.
useStackedLayout	boolean	false	Determines whether the chart should use a stacked layout. It is useful only for bar and column charts. Will be ignored if an iframe url is set.
percentageHeightDesktop	integer	false	Sets the percentage plot height at desktop, relative to the width. If undefined the chart will fall back to the default height of 400px at desktop. Does not apply to bar charts. Will be ignored if an iframe url is set.
percentageHeightMobile	integer	false	Sets the percentage plot height at mobile, relative to the width. If undefined the chart will fall back to the default height of 400px at mobile. Does not apply to bar charts. Will be ignored if an iframe url is set.

annotations	array	false	An array of point annotations. Will be ignored if an iframe url is set.
rangeAnnotations	array	false	An array of range annotations. Will be ignored if an iframe url is set.
referenceLineAnnotations	array	false	An array of reference line annotations. Will be ignored if an iframe url is set.
estimateLineLabel	string	false	Label for the estimate line in the legend. Used in column charts with confidence intervals. Will be ignored if an iframe url is set.
uncertaintyRangeLabel	string	false	Label for the confidence interval in the legend. Used in column charts showing uncertainty ranges. Will be ignored if an iframe url is set.
iframeUrl	string	false	A url for a visualisation to display in an iframe instead of displaying a Highcharts chart.
footnotes	`Object<Footnotes>`	false	Footnotes to appear below the chart in a 'details' element
fallbackImageUrl	string	false	A url for a fallback image to display instead of the chart or iframe visualisation if JavaScript is disabled. If a fallback image is passed with an iframeUrl parameter, the iframe will be hidden for non-JavaScript users. If it is not passed, it is assumed the iframe content will provide a fallback image to be displayed inside the iframe.
fallbackImageAlt	string	false	Alt text for the fallback image - a short description only, as the description field describes the chart for screen readers. Defaults to "Fallback image for the chart as JavaScript is disabled"
iframeAspectRatio	string	false	Sets the aspect ratio for iframe charts. Only applicable when using an iframe chart. Acceptable values are 16-9, 4-3, 21-9, 1-1, 3-2, and 9-16. The value must be provided in the x-y format (e.g. 16-9). If an unsupported value is provided or a value is not provided, the aspect ratio will default to 16-9.

Download
Property	Type	Required	Description
title	string	false	The title displayed above the download options.
itemsList	array	false	An array of items available for download, each described by a (DownloadItem)[#DownloadItem].

DownloadItem
Property	Type	Required	Description
text	string	true	The label or description of the downloadable item.
url	string	true	The URL to the downloadable resource.

Y_Axis
Name	Type	Required	Description
title	string	true	The title text displayed on the y-axis. Note that for any chart type apart from bar charts, a maximum character limit of 50 characters is recommended to avoid the axis title being cut off at mobile.
labelFormat	string	false	A format string for the axis label. Examples of string formats can be found in these docs (opens in a new tab) .
tickIntervalMobile	number	false	The interval of the tick marks in axis units at mobile. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
tickIntervalDesktop	number	false	The interval of the tick marks in axis units at desktop. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
customReferenceLineValue	float or int	false	A custom value to display a darker reference line. If not supplied, the darker will appear at zero. The custom value is only used for column charts and line charts - for other chart types it will be ignored, and the darker line will appear at zero.
min	number	false	Sets the minimum value for the Y-axis. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.
max	number	false	Sets the maximum value for the Y-axis. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.
startOnTick	boolean	false	Align the axis to start on a tick. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.
endOnTick	boolean	false	Align the axis to end on a tick. Relevant for Line, bar, area, column chart, column-range, boxplot and scatter charts.

X_Axis
Name	Type	Required	Description
title	string	false	The title text displayed on the x-axis. Note: x-axis titles are not supported for bar chart types.
labelFormat	string	false	A format string for the x-axis label. Examples of string formats can be found in these docs (opens in a new tab) .
categories	array	false	Labels for each tick mark along the x-axis.
type	string	false	The type of axis. Can be one of `linear`, `logarithmic`, `datetime` or `category`. Defaults to linear.
tickIntervalMobile	number	false	The interval of the tick marks in axis units at mobile. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
tickIntervalDesktop	number	false	The interval of the tick marks in axis units at desktop. Useful when you want to space out the labels (e.g. show every 2nd or 5th label).
min	number	false	Sets the minimum value for the X-axis. Relevant only for scatter charts.
max	number	false	Sets the maximum value for the X-axis. Relevant only for scatter charts.
startOnTick	boolean	false	Align the axis to start on a tick. Relevant only for scatter charts.
endOnTick	boolean	false	Align the axis to end on a tick. Relevant only for scatter charts.

Series
Name	Type	Required	Description
name	string	true	The name of the series.
data	array	true	The data values for the series. Each value corresponds to a category on the x-axis.
dataLabels	boolean	false	Options for whether the DataLabel is displayed. Defaults to `false`. This option is only available for bar chart and clustered bar charts with two or fewer series, and 20 or fewer data points in any series.
marker	boolean	false	Options for whether the Marker is displayed on the data points. Defaults to `false`. This option is only available for line charts.
type	string	false	Specifies the configuration type to apply to the series. Supported types include 'line' and 'scatter'. By default, it aligns with the chart type. This is used when combining multiple chart types within a single chart. Note: Only the following chart type combinations are supported: "column with line" and "columnrange with scatter". For column with line, only one line series is supported. Additional line series will be ignored.
connectNulls	boolean	false	Whether to connect lines that have a data point missing. Only relevant for line charts.

Point annotations
Name	Type	Required	Description
text	string	true	The annotation text.
point	object	false	The x and y coordinates for the annotation
labelOffsetX (px)	int	true	The x offset in px of the label from the annotation point
labelOffsetY (px)	int	true	The y offset in px of the label from the annotation point

Point
Name	Type	Required	Description
xValue	float or int	true	The x axis value of the annotation. For category axes this is the zero based index of the x axis categories array. It must be an integer in this scenario.
yValue	float	true	The y axis value of the annotation

Range annotations
Name	Type	Required	Description
text	string	true	The annotation text.
range	Object	true	The xValue or yValue coordinates for the annotation
axis	string	true	The axis the range annotation should be applied to. Should be one of 'x' or 'y'. Note that for bar charts 'x' will be the vertical axis, and 'y' will be the horizontal axis.
labelInside	boolean	true	Whether the label for the range sits inside or outside the shaded area
labelOffsetX (px)	int	false	The horizontal offset in px of the label from it's default position. Ignored if labelInside is true.
labelOffsetY (px)	int	false	The vertical offset in px of the label from it's default position. Ignored if labelInside is true.
labelWidth (px)	int	false	The width of the label in pixels - the label text will wrap if it is wider than this value. If undefined, the label will be set to 150px wide.

Range
Name	Type	Required	Description
axisValue1	float or int	true	The starting point on the axis for the annotation. For category axes this is the zero based index of the categories array. It must be an integer in this scenario.
axisValue2	float or int	true	The ending pont on the axis for the annotation. For category axes this is the zero based index of the axis categories array. It must be an integer in this scenario.

Reference line annotations
Name	Type	Required	Description
text	string	true	The annotation text.
value	float or int	true	The x axis or y axis value for the annotation. For category axes this is the zero based index of the categories array. It must be an integer in this scenario.
axis	string	true	The axis the range annotation should be applied to. Should be one of 'x' or 'y'. Note that for bar charts 'x' will be the vertical axis, and 'y' will be the horizontal axis.
labelWidth (px)	int	false	The width of the label in pixels - the label text will wrap if it is wider than this value. If undefined, the label will be set to 150px wide.
labelOffsetX (px)	int	false	The horizontal offset in px of the label from it's default position.
labelOffsetY (px)	int	false	The vertical offset in px of the label from it's default position.

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

HTML

<div data-highcharts-base-chart data-highcharts-type="column" data-highcharts-theme="primary"
  data-highcharts-title="Figure 6: Net debt as a percentage of GDP remains at levels last seen in the early 1960s"
  data-highcharts-id="uuid" data-highcharts-percentage-height-desktop="35" data-highcharts-percentage-height-mobile="90"
  data-highcharts-x-axis-tick-interval-mobile="5">
  <figure class="ons-chart" aria-describedby="chart-audio-description-uuid">
    <h2 class="ons-chart__title">Figure 6: Net debt as a percentage of GDP remains at levels last seen in the early
      1960s</h2>
    <h3 class="ons-chart__subtitle">Public sector net debt excluding public sector banks, percentage of gross domestic
      product (GDP), UK, financial year ending (FYE) 1901 to October 2024</h3>
    <p class="ons-u-vh" id="chart-audio-description-uuid">Public sector net debt excluding public sector banks,
      percentage of gross domestic product (GDP), UK, financial year ending (FYE) 1901 to October 2024</p>
    <div data-highcharts-chart-container class="ons-chart__container" tabindex="0" role="region"
      aria-label="chart container" aria-describedby="chart-instructions-uuid">
      <div id="chart-instructions-uuid" class="ons-u-vh">Use the Tab key to move focus into the chart. Once inside, use
        the arrow keys to navigate between data points. As you move, tooltips will be announced to describe each point.
        Touch device users, explore by touch or with swipe gestures.</div>
      <div data-highcharts-chart class="ons-chart__chart"></div>
    </div>
    <ul class="ons-chart__annotations-footnotes" aria-hidden="true" data-annotations-footnotes>
      <li class="ons-chart__annotations-footnotes_item">
        <span class="ons-chart__annotations-footnotes-number">1</span> A test y axis reference line annotation
      </li>
    </ul>
    <figcaption class="ons-chart__caption">Source: Public sector finances from the Office for Budget Responsibility
      (OBR) and the Office for National Statistics</figcaption>
  </figure>
  <h4 class="ons-chart__download-title">Download Figure 1 data</h4>
  <ol class="ons-list">
    <li class="ons-list__item">
      <a href="#" class="ons-list__link">Excel spreadsheet (XLSX format, 18KB)</a>
    </li>
    <li class="ons-list__item">
      <a href="#" class="ons-list__link">Simple text file (CSV format, 25KB)</a>
    </li>
    <li class="ons-list__item">
      <a href="#" class="ons-list__link">Image (PNG format, 25KB)</a>
    </li>
  </ol>
  <!-- Set scripts to pass the config values as json to the JavaScript -->
  <!-- prettier-ignore-start -->
  <script type="application/json" data-highcharts-config--uuid>
    {
      "chart": {
        "type": "column"
      },
      "legend": {
        "enabled": false
      },
      "yAxis": {
        "title": {
          "text": "Percentage of GDP"
        },
        "labels": {}
      },
      "xAxis": {
        "title": {
          "text": "Years"
        },
        "categories": ["Mar 1901", "Mar 1902", "Mar 1903", "Mar 1904", "Mar 1905", "Mar 1906", "Mar 1907", "Mar 1908",
          "Mar 1909", "Mar 1910", "Mar 1911", "Mar 1912"
        ],
        "type": "linear",
        "labels": {}
      },
      "series": [{
        "name": "Public sector net debt as a % of GDP (PSND)",
        "data": [37.8, 41, 43, 42.9, 41.8, 39.8, 37.9, 38.2, 37.6, 36.7, 33.9, 31.8],
        "marker": {
          "enabled": false
        },
        "dataLabels": {
          "enabled": false
        },
        "connectNulls": false,
        "type": "column"
      }]
    }
  </script>
  <script type="application/json" data-highcharts-reference-line-annotations--uuid>
    [{
      "text": "A test y axis reference line annotation",
      "value": 20,
      "axis": "y",
      "labelOffsetY": -170,
      "labelOffsetX": 0
    }]
  </script>
  <!-- prettier-ignore-end -->
</div>

Help improve this page

Let us know how we could improve this page, or share your user research findings. Discuss this page on GitHub (opens in a new tab)

Cookies on ons.gov.uk

Charts Column charts

Overview

Column chart

Example Column Chart contents

Nunjucks

Nunjucks macro options

HTML

Variants

Clustered column chart

Example Clustered Column Chart contents

Nunjucks

Nunjucks macro options

HTML

Column with line chart

Example Column With Line Chart contents

Nunjucks

Nunjucks macro options

HTML

Column chart with confidence levels

Example Column With Confidence Levels contents

Nunjucks

Nunjucks macro options

HTML

Stacked Column chart

Example Stacked Column Chart contents

Nunjucks

Nunjucks macro options

HTML

Annotations

Column chart with annotations

Example Column Chart With Annotations contents

Nunjucks

Nunjucks macro options

HTML

Column chart with range annotations

Example Column Chart With Range Annotations contents

Nunjucks

Nunjucks macro options

HTML

Column chart with reference line annotations

Example Column Chart With Reference Line Annotations contents

Nunjucks

Nunjucks macro options

HTML

Options

Column chart with axis min and max values

Example Column Chart With Axis Min And Max Values contents

Nunjucks

Nunjucks macro options

HTML

Column chart with custom reference line value

Example Column Chart With Reference Line Annotations contents

Nunjucks

Nunjucks macro options

HTML

Help improve this page