Charts Bar charts
Overview
A bar chart uses horizontal rectangular bars to display data. Includes clustered and stacked bar charts.
The code to build the chart examples are provided in this page. For further guidance on how to use and implement the bar charts, please see the Bar chart page in the Data visualisation section.
Bar chart
Example Bar Chart contents
Nunjucks
{% from "components/chart/_macro.njk" import onsChart %}
{{
onsChart({
"chartType": "bar",
"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": "#"
}
]
},
"footnotes": {
"title": "Footnotes",
"content": "<ol><li>Non-store retailing refers to retailers that do not have a store presence. While the majority is made up of online retailers, it also includes other retailers, such as stalls and markets.</li><li>More data are available in our Retail Sales Index datasets.</li></ol>"
},
"xAxis": {
"categories": [
"All retailing",
"All retailing excluding Automotive fuel",
"Food stores",
"Department stores",
"Other non-food stores",
"Textile clothing \u0026 footwear stores",
"Household goods stores",
"Non-store retailing",
"Automotive fuel"
],
"type": "linear"
},
"yAxis": {
"title": "Percent (%)"
},
"series": [
{
"data": [1.7, 2.1, 5.6, 0, -0.6, -2.7, -1.7, 2.4, -1.2],
"dataLabels": true,
"name": "Jan-25"
}
]
})
}}
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. |
| 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]. |
| Property | Type | Required | Description |
|---|---|---|---|
| text | string | true | The label or description of the downloadable item. |
| url | string | true | The URL to the downloadable resource. |
| 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. |
| 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. |
| 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. |
| 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 |
| 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 |
| 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. |
| 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. |
| 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. |
| 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="bar" 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">
<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>
<div id="footnotes--uuid" class="ons-details ons-js-details ons-u-mt-xl">
<div class="ons-details__heading ons-js-details-heading" role="button">
<h4 class="ons-details__title ons-u-fs-r--b">Footnotes</h4>
<span class="ons-details__icon">
<svg class="ons-icon" viewBox="0 0 8 13" xmlns="http://www.w3.org/2000/svg" focusable="false"
fill="currentColor" role="img" aria-hidden="true">
<path
d="M5.74,14.28l-.57-.56a.5.5,0,0,1,0-.71h0l5-5-5-5a.5.5,0,0,1,0-.71h0l.57-.56a.5.5,0,0,1,.71,0h0l5.93,5.93a.5.5,0,0,1,0,.7L6.45,14.28a.5.5,0,0,1-.71,0Z"
transform="translate(-5.02 -1.59)" />
</svg></span>
</div>
<div id="footnotes--uuid-content" class="ons-details__content ons-js-details-content">
<ol>
<li>Non-store retailing refers to retailers that do not have a store presence. While the majority is made up of
online retailers, it also includes other retailers, such as stalls and markets.</li>
<li>More data are available in our Retail Sales Index datasets.</li>
</ol>
</div>
</div>
<!-- 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": "bar"
},
"legend": {
"enabled": true
},
"yAxis": {
"title": {
"text": "Percent (%)"
},
"labels": {}
},
"xAxis": {
"title": {},
"categories": ["All retailing", "All retailing excluding Automotive fuel", "Food stores", "Department stores",
"Other non-food stores", "Textile clothing u0026 footwear stores", "Household goods stores",
"Non-store retailing", "Automotive fuel"
],
"type": "linear",
"labels": {}
},
"series": [{
"name": "Jan-25",
"data": [1.7, 2.1, 5.6, 0, -0.6, -2.7, -1.7, 2.4, -1.2],
"marker": {
"enabled": false
},
"dataLabels": {
"enabled": true
},
"connectNulls": false,
"type": "bar"
}]
}
</script>
<!-- prettier-ignore-end -->
</div>Variants
There are multiple variants of this component.
Bar chart with confidence levels
Use this when you need to display confidence levels on your bar charts.
Example Bar With Confidence Levels contents
Nunjucks
{% from "components/chart/_macro.njk" import onsChart %}
{{
onsChart({
"chartType": "columnrange",
"description": "Volume sales, seasonally adjusted, Great Britain, January 2022 to January 2025",
"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": [
'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
],
"type": "linear",
"title": "Categories"
},
"yAxis": {
"title": "Temperature ( °C )"
},
"series": [
{
"data": [
[-9.5, 8.0],
[-7.8, 8.3],
[-13.1, 9.2],
[-4.4, 15.7],
[-1.0, 20.8],
[3.1, 28.4],
[5.9, 27.0],
[4.6, 23.0],
[4.9, 19.3],
[-5.2, 11.6],
[],
[-10.5, 12.0],
[-12.1, 18.5]
],
"name": "Values"
},
{
"data": [1,2,3,4,5,6,7,8,9,10,3,11,12],
"name": "Another test data source",
"type": "scatter"
}
]
})
}}
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. |
| 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]. |
| Property | Type | Required | Description |
|---|---|---|---|
| text | string | true | The label or description of the downloadable item. |
| url | string | true | The URL to the downloadable resource. |
| 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. |
| 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. |
| 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. |
| 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 |
| 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 |
| 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. |
| 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. |
| 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. |
| 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="columnrange" data-highcharts-theme=""
data-highcharts-title="Food stores showed a strong rise on the month, while non-food stores fell"
data-highcharts-id="uuid">
<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": "columnrange"
},
"legend": {
"enabled": true
},
"yAxis": {
"title": {
"text": "Temperature ( °C )"
},
"labels": {}
},
"xAxis": {
"title": {
"text": "Categories"
},
"categories": ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"],
"type": "linear",
"labels": {}
},
"series": [{
"name": "Values",
"data": [
[-9.5, 8],
[-7.8, 8.3],
[-13.1, 9.2],
[-4.4, 15.7],
[-1, 20.8],
[3.1, 28.4],
[5.9, 27],
[4.6, 23],
[4.9, 19.3],
[-5.2, 11.6],
[],
[-10.5, 12],
[-12.1, 18.5]
],
"marker": {
"enabled": false
},
"dataLabels": {
"enabled": false
},
"connectNulls": false,
"type": "columnrange"
}, {
"name": "Another test data source",
"data": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 3, 11, 12],
"marker": {
"enabled": true
},
"dataLabels": {
"enabled": false
},
"connectNulls": false,
"type": "scatter"
}]
}
</script>
<!-- prettier-ignore-end -->
</div>Clustered bar chart
You can use this type of chart for comparing a small number of series across several categories.
A clustered bar chart uses side-by-side bars of different colours to show values for different series within categories.
For further guidance on how to use and implement these charts, please see the Clustered bar chart in the Data visualisation section.
Example Clustered Bar Chart contents
Nunjucks
{% from "components/chart/_macro.njk" import onsChart %}
{{
onsChart({
"chartType": "bar",
"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,
"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"
}
],
"xAxis": {
"categories": [
"Food stores",
"Non-food stores",
"Non-store retailing ",
"Automotive fuel"
],
"type": "linear"
},
"yAxis": {
"title": "Percent (%)"
}
})
}}
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. |
| 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]. |
| Property | Type | Required | Description |
|---|---|---|---|
| text | string | true | The label or description of the downloadable item. |
| url | string | true | The URL to the downloadable resource. |
| 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. |
| 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. |
| 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. |
| 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 |
| 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 |
| 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. |
| 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. |
| 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. |
| 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="bar" 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">
<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": "bar"
},
"legend": {
"enabled": true
},
"yAxis": {
"title": {
"text": "Percent (%)"
},
"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": "bar"
}, {
"name": "2023",
"data": [-2.9, -2.7, -2.9, -3.5],
"marker": {
"enabled": false
},
"dataLabels": {
"enabled": false
},
"connectNulls": false,
"type": "bar"
}, {
"name": "2024",
"data": [-1.6, 1.2, 3.2, 3.8],
"marker": {
"enabled": false
},
"dataLabels": {
"enabled": false
},
"connectNulls": false,
"type": "bar"
}]
}
</script>
<!-- prettier-ignore-end -->
</div>Stacked bar chart
A stacked bar chart uses different colour segments within each bar to show a breakdown of categories.
For further guidance on how to use and implement these charts, please see the Stacked bar charts page in the Data visualisation section.
Example Stacked Bar Chart contents
Nunjucks
{% from "components/chart/_macro.njk" import onsChart %}
{{
onsChart({
"chartType": "bar",
"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",
"useStackedLayout": true,
"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": [5, 3, 4, 6],
"dataLabels": false,
"name": "2022"
},
{
"data": [2, 2, 3, 7],
"dataLabels": false,
"name": "2023"
},
{
"data": [3, 4, 4, 1],
"dataLabels": false,
"name": "2024"
}
],
"xAxis": {
"categories": [
"Food stores",
"Non-food stores",
"Non-store retailing ",
"Automotive fuel"
],
"type": "linear"
},
"yAxis": {
"title": "Percent (%)"
}
})
}}
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. |
| 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]. |
| Property | Type | Required | Description |
|---|---|---|---|
| text | string | true | The label or description of the downloadable item. |
| url | string | true | The URL to the downloadable resource. |
| 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. |
| 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. |
| 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. |
| 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 |
| 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 |
| 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. |
| 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. |
| 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. |
| 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="bar" 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">
<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": "bar"
},
"legend": {
"enabled": true
},
"yAxis": {
"title": {
"text": "Percent (%)"
},
"labels": {}
},
"xAxis": {
"title": {},
"categories": ["Food stores", "Non-food stores", "Non-store retailing ", "Automotive fuel"],
"type": "linear",
"labels": {}
},
"series": [{
"name": "2022",
"data": [5, 3, 4, 6],
"marker": {
"enabled": false
},
"dataLabels": {
"enabled": false
},
"connectNulls": false,
"type": "bar"
}, {
"name": "2023",
"data": [2, 2, 3, 7],
"marker": {
"enabled": false
},
"dataLabels": {
"enabled": false
},
"connectNulls": false,
"type": "bar"
}, {
"name": "2024",
"data": [3, 4, 4, 1],
"marker": {
"enabled": false
},
"dataLabels": {
"enabled": false
},
"connectNulls": false,
"type": "bar"
}]
}
</script>
<!-- prettier-ignore-end -->
</div>Annotations
If you need to add annotations to your bar 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.
Bar chart with annotations
Use this when you require annotations on your bar charts.
Example Bar Chart With Annotations contents
Nunjucks
{% from "components/chart/_macro.njk" import onsChart %}
{{
onsChart({
"chartType": "bar",
"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": "#"
}
]
},
"xAxis": {
"categories": [
"All retailing",
"All retailing excluding Automotive fuel",
"Food stores",
"Department stores",
"Other non-food stores",
"Textile clothing \u0026 footwear stores",
"Household goods stores",
"Non-store retailing",
"Automotive fuel"
],
"type": "linear"
},
"yAxis": {
"title": "Percent (%)"
},
"series": [
{
"data": [1.7, 2.1, 5.6, 0, -0.6, -2.7, -1.7, 2.4, -1.2],
"dataLabels": true,
"name": "Jan-25"
}
],
"annotations": [
{
"text": "A test point annotation",
"point": {"x": 2, "y": 3},
"labelOffsetX": 40,
"labelOffsetY": -30
}
]
})
}}
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. |
| 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]. |
| Property | Type | Required | Description |
|---|---|---|---|
| text | string | true | The label or description of the downloadable item. |
| url | string | true | The URL to the downloadable resource. |
| 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. |
| 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. |
| 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. |
| 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 |
| 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 |
| 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. |
| 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. |
| 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. |
| 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="bar" 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">
<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>
<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: 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": "bar"
},
"legend": {
"enabled": true
},
"yAxis": {
"title": {
"text": "Percent (%)"
},
"labels": {}
},
"xAxis": {
"title": {},
"categories": ["All retailing", "All retailing excluding Automotive fuel", "Food stores", "Department stores",
"Other non-food stores", "Textile clothing u0026 footwear stores", "Household goods stores",
"Non-store retailing", "Automotive fuel"
],
"type": "linear",
"labels": {}
},
"series": [{
"name": "Jan-25",
"data": [1.7, 2.1, 5.6, 0, -0.6, -2.7, -1.7, 2.4, -1.2],
"marker": {
"enabled": false
},
"dataLabels": {
"enabled": true
},
"connectNulls": false,
"type": "bar"
}]
}
</script>
<script type="application/json" data-highcharts-annotations--uuid>
[{
"text": "A test point annotation",
"point": {
"x": 2,
"y": 3
},
"labelOffsetX": 40,
"labelOffsetY": -30
}]
</script>
<!-- prettier-ignore-end -->
</div>Bar chart with point range and reference line annotations
Use this when you require point range and reference line annotations on your bar charts.
Example Bar Chart With Point Range And Reference Line Annotations contents
Nunjucks
{% from "components/chart/_macro.njk" import onsChart %}
{{
onsChart({
"chartType": "bar",
"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": "#"
}
]
},
"xAxis": {
"categories": [
"All retailing",
"All retailing excluding Automotive fuel",
"Food stores",
"Department stores",
"Other non-food stores",
"Textile clothing \u0026 footwear stores",
"Household goods stores",
"Non-store retailing",
"Automotive fuel"
],
"type": "linear"
},
"yAxis": {
"title": "Percent (%)"
},
"series": [
{
"data": [1.7, 2.1, 5.6, 0, -0.6, -2.7, -1.7, 2.4, -1.2],
"dataLabels": false,
"name": "Jan-25"
}
],
"annotations": [
{
"text": "A test point annotation",
"point": {"x": 2, "y": 3},
"labelOffsetX": 50,
"labelOffsetY": 60
}
],
"rangeAnnotations": [
{
"text": "A test x axis range annotation",
"range": {"axisValue1": 1, "axisValue2": 2},
"axis": "x",
"labelOffsetX": 10,
"labelOffsetY": -60
},
{
"text": "A test y axis range annotation with a width of 80px",
"range": {"axisValue1": 5, "axisValue2": 6},
"axis": "y",
"labelOffsetX": -80,
"labelOffsetY": 230,
"labelWidth": 80
}
],
"referenceLineAnnotations": [
{
"text": "A test x axis reference line annotation",
"value": 8,
"axis": "x",
"labelOffsetY": -30
},
{
"text": "A test y axis reference line annotation",
"value": 1.5,
"axis": "y",
"labelWidth": 100,
"labelOffsetX": 10,
"labelOffsetY": 170
}
]
})
}}
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. |
| 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]. |
| Property | Type | Required | Description |
|---|---|---|---|
| text | string | true | The label or description of the downloadable item. |
| url | string | true | The URL to the downloadable resource. |
| 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. |
| 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. |
| 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. |
| 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 |
| 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 |
| 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. |
| 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. |
| 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. |
| 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="bar" 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">
<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>
<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>
<li class="ons-chart__annotations-footnotes_item">
<span class="ons-chart__annotations-footnotes-number">2</span> A test x axis range annotation
</li>
<li class="ons-chart__annotations-footnotes_item">
<span class="ons-chart__annotations-footnotes-number">3</span> A test y axis range annotation with a width of
80px
</li>
<li class="ons-chart__annotations-footnotes_item">
<span class="ons-chart__annotations-footnotes-number">4</span> A test x axis reference line annotation
</li>
<li class="ons-chart__annotations-footnotes_item">
<span class="ons-chart__annotations-footnotes-number">5</span> A test y axis reference line annotation
</li>
</ul>
<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": "bar"
},
"legend": {
"enabled": true
},
"yAxis": {
"title": {
"text": "Percent (%)"
},
"labels": {}
},
"xAxis": {
"title": {},
"categories": ["All retailing", "All retailing excluding Automotive fuel", "Food stores", "Department stores",
"Other non-food stores", "Textile clothing u0026 footwear stores", "Household goods stores",
"Non-store retailing", "Automotive fuel"
],
"type": "linear",
"labels": {}
},
"series": [{
"name": "Jan-25",
"data": [1.7, 2.1, 5.6, 0, -0.6, -2.7, -1.7, 2.4, -1.2],
"marker": {
"enabled": false
},
"dataLabels": {
"enabled": false
},
"connectNulls": false,
"type": "bar"
}]
}
</script>
<script type="application/json" data-highcharts-annotations--uuid>
[{
"text": "A test point annotation",
"point": {
"x": 2,
"y": 3
},
"labelOffsetX": 50,
"labelOffsetY": 60
}]
</script>
<script type="application/json" data-highcharts-range-annotations--uuid>
[{
"text": "A test x axis range annotation",
"range": {
"axisValue1": 1,
"axisValue2": 2
},
"axis": "x",
"labelOffsetX": 10,
"labelOffsetY": -60
}, {
"text": "A test y axis range annotation with a width of 80px",
"range": {
"axisValue1": 5,
"axisValue2": 6
},
"axis": "y",
"labelOffsetX": -80,
"labelOffsetY": 230,
"labelWidth": 80
}]
</script>
<script type="application/json" data-highcharts-reference-line-annotations--uuid>
[{
"text": "A test x axis reference line annotation",
"value": 8,
"axis": "x",
"labelOffsetY": -30
}, {
"text": "A test y axis reference line annotation",
"value": 1.5,
"axis": "y",
"labelWidth": 100,
"labelOffsetX": 10,
"labelOffsetY": 170
}]
</script>
<!-- prettier-ignore-end -->
</div>Options
There are additional options that you can add to your charts.
Bar chart with axis min and max values
Use this when you require axis minimum and maximum values on your bar charts.
Example Bar Chart With Axis Min And Max Values contents
Nunjucks
{% from "components/chart/_macro.njk" import onsChart %}
{{
onsChart({
"chartType": "bar",
"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": "#"
}
]
},
"xAxis": {
"categories": [
"All retailing",
"All retailing excluding Automotive fuel",
"Food stores",
"Department stores",
"Other non-food stores",
"Textile clothing \u0026 footwear stores",
"Household goods stores",
"Non-store retailing",
"Automotive fuel"
],
"type": "linear"
},
"yAxis": {
"title": "Percent (%)",
"min": -5,
"max": 10,
"startOnTick": true,
"endOnTick": false
},
"series": [
{
"data": [1.7, 2.1, 5.6, 0, -0.6, -2.7, -1.7, 2.4, -1.2],
"dataLabels": true,
"name": "Jan-25"
}
]
})
}}
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. |
| 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]. |
| Property | Type | Required | Description |
|---|---|---|---|
| text | string | true | The label or description of the downloadable item. |
| url | string | true | The URL to the downloadable resource. |
| 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. |
| 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. |
| 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. |
| 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 |
| 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 |
| 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. |
| 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. |
| 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. |
| 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="bar" 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">
<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": "bar"
},
"legend": {
"enabled": true
},
"yAxis": {
"title": {
"text": "Percent (%)"
},
"labels": {},
"min": -5,
"max": 10,
"startOnTick": true,
"endOnTick": false
},
"xAxis": {
"title": {},
"categories": ["All retailing", "All retailing excluding Automotive fuel", "Food stores", "Department stores",
"Other non-food stores", "Textile clothing u0026 footwear stores", "Household goods stores",
"Non-store retailing", "Automotive fuel"
],
"type": "linear",
"labels": {}
},
"series": [{
"name": "Jan-25",
"data": [1.7, 2.1, 5.6, 0, -0.6, -2.7, -1.7, 2.4, -1.2],
"marker": {
"enabled": false
},
"dataLabels": {
"enabled": true
},
"connectNulls": false,
"type": "bar"
}]
}
</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)