name: Chart (experimental)
description: The chart component presents a data chart and a tabular version of the same data
part_of_admin_layout: true
body: |
  This component takes a set of data and presents it as a line graph and a table with one or more rows and lines.
  The chart relies upon chartkick and renders using JavaScript, so the table is provided as a fallback for a lack of JavaScript,
  an accessible view on the data for screenreaders, and a simple view of the raw data for all users.

  The `chart_overview` option can be used to provide an explanation for screen reader users of what the chart shows.
accessibility_criteria: |
  Charts must:

    - use line colours with a contrast ratio higher than 4.5:1 against the background colour to meet WCAG AA
    - contain a `chart_heading` option if `minimal` is not set to true, so that skip links and visually hidden headings are accurate
shared_accessibility_criteria:
  - link
uses_component_wrapper_helper: true
examples:
  default:
    data:
      chart_heading: Chart showing page views on the website in January 2015
      h_axis_title: Day
      v_axis_title: Views
      chart_overview: This chart shows page views for January 2015.
      keys:
        - "2015-01-01"
        - "2015-01-02"
        - "2015-01-03"
        - "2015-01-04"
        - "2015-01-05"
        - "2015-01-06"
        - "2015-01-07"
        - "2015-01-08"
        - "2015-01-09"
        - "2015-01-10"
      rows:
        - label: January 2015
          values:
            - 500
            - 1190
            - 740
            - 820
            - 270
            - 450
            - 110
            - 210
            - 670
            - 430
  multiple rows of data:
    description: Where more than one series is shown on a chart, do not hide the legend.
    data:
      chart_heading: Page views chart
      h_axis_title: Day
      v_axis_title: Views
      chart_overview: This chart shows page views for January in different years.
      keys:
        - 1st
        - 2nd
        - 3rd
        - 4th
        - 5th
        - 6th
        - 7th
        - 8th
        - 9th
        - 10th
      rows:
        - label: January 2015
          values:
            - 5
            - 119
            - 74
            - 82
            - 27
            - 45
            - 11
            - 21
            - 67
            - 43
        - label: January 2016
          values:
            - 5
            - 8
            - 37
            - 50
            - 43
            - 29
            - 67
            - 61
            - 14
            - 91
        - label: January 2017
          values:
            - 31
            - 81
            - 12
            - 15
            - 52
            - 61
            - 143
            - 27
            - 18
            - 34
  hide_legend:
    data:
      chart_heading: Page views chart
      h_axis_title: Day
      v_axis_title: Views
      chart_overview: This chart shows page views for January 2015.
      hide_legend: true
      keys:
        - "2015-01-01"
        - "2015-01-02"
        - "2015-01-03"
        - "2015-01-04"
        - "2015-01-05"
        - "2015-01-06"
        - "2015-01-07"
        - "2015-01-08"
        - "2015-01-09"
        - "2015-01-10"
      rows:
        - label: January 2015
          values:
            - 500
            - 1190
            - 740
            - 820
            - 270
            - 450
            - 110
            - 210
            - 670
            - 430
  with_line_colours_and_styles:
    description: Note that line styles and colours currently only work on line charts.
    data:
      chart_heading: Page views chart
      h_axis_title: Day
      v_axis_title: Views
      chart_overview: This chart shows page views for January in different years.
      line_colours:
        - orange
        - blue
        - "#88AA11"
      line_styles:
        - solid
        - dotted
        - solid
      keys:
        - 1st
        - 2nd
        - 3rd
      rows:
        - label: January 2015
          values:
            - 110
            - 119
            - 105
        - label: January 2016
          values:
            - 71
            - 68
            - 75
        - label: January 2017
          values:
            - 21
            - 42
            - 18
  bar_chart:
    data:
      chart_heading: Hats owned
      h_axis_title: Day
      v_axis_title: Views
      chart_overview: This chart shows page views for January 2015.
      chart_type: "bar"
      hide_legend: true
      keys:
        - Jon
        - Ash
        - James
        - Phil
      rows:
        - label: Hats owned
          values:
            - 3
            - 1
            - 1
            - 2
  column_chart:
    data:
      chart_heading: Hats owned
      h_axis_title: Day
      v_axis_title: Views
      chart_overview: This chart shows page views for January 2015.
      chart_type: "column"
      hide_legend: true
      keys:
        - Jon
        - Ash
        - James
        - Phil
      rows:
        - label: Hats owned
          values:
            - 3
            - 1
            - 1
            - 2
  format_axis_labels:
    description: |
      Axis labels can be forced into date or currency format as shown.

      'currency' will add a currency symbol (£) at the start of the labels.

      'percent' will add a percent (%) to the end of the labels.

      'date' will force a standard date format of `YYYY-MM-DD` to the labels, where they are in an undesirable date format. This can be useful if there are a lot of labels on the axes because the chart can do strange truncation sometimes.
    data:
      chart_heading: Cost per day
      h_axis_title: Day
      v_axis_title: Cost
      chart_overview: This chart shows cost per day.
      v_axis_format: currency
      h_axis_format: date
      keys:
        - 2024 Jan 1
        - 2024 Jan 2
        - 2024 Jan 3
        - 2024 Jan 4
        - 2024 Jan 5
        - 2024 Jan 6
      rows:
        - label: Cost
          values:
            - 14
            - 29
            - 45
            - 63
            - 54
            - 22
  vertical table:
    description: Reorient the table to better suit the output of some data sets.
    data:
      chart_heading: Page views chart
      table_direction: vertical
      h_axis_title: Day
      v_axis_title: Views
      chart_overview: This chart shows page views for January in different years.
      keys:
        - 1st
        - 2nd
        - 3rd
        - 4th
        - 5th
        - 6th
        - 7th
      rows:
        - label: January 2015
          values:
            - 5
            - 119
            - 74
            - 117
            - 33
            - 89
            - 79
        - label: January 2016
          values:
            - 3
            - 8
            - 37
            - 82
            - 118
            - 85
            - 80
  with_a_different_point_size:
    description: For some charts it may be better to reduce the point size so that the line is clearer. However it is recommended that the point size is larger to make it easier for users to move the mouse over them.
    data:
      chart_heading: Page views chart
      h_axis_title: Day
      v_axis_title: Views
      chart_overview: This chart shows page views for January 2015.
      point_size: 0
      keys:
        - "2015-01-01"
        - "2015-01-02"
        - "2015-01-03"
        - "2015-01-04"
        - "2015-01-05"
        - "2015-01-06"
        - "2015-01-07"
        - "2015-01-08"
        - "2015-01-09"
        - "2015-01-10"
      rows:
        - label: January 2015
          values:
            - 600
            - 690
            - 740
            - 820
            - 570
            - 950
            - 810
            - 610
            - 770
            - 530
  scale_y_axis_based_on_data:
    description: |
      By default the Y-axis will always start at zero, but this may not always be required.

      If there are empty items in the data the chart line will either discontinue or leave a gap, as shown.
    data:
      chart_heading: Page views chart
      h_axis_title: Day
      v_axis_title: Views
      chart_overview: This chart shows page views for January 2015.
      hide_legend: true
      y_axis_auto_adjust: true
      keys:
        - "2015-01-01"
        - "2015-01-02"
        - "2015-01-03"
        - "2015-01-04"
        - "2015-01-05"
        - "2015-01-06"
        - "2015-01-07"
        - "2015-01-08"
        - "2015-01-09"
        - "2015-01-10"
        - "2015-01-11"
        - "2015-01-12"
        - "2015-01-13"
      rows:
        - label: January 2015
          values:
            - 1500
            - 1190
            - 1740
            - 1820
            - 1270
            -
            -
            - 1450
            - 1110
            - 1210
            - 1670
            - 1430
            - 1352
  with_a_different_heading_level:
    description: Use a different heading level for the chart heading. It defaults to a H2.
    data:
      chart_heading: Page views chart
      chart_heading_level: 4
      h_axis_title: Day
      v_axis_title: Views
      chart_overview: This chart shows page views for January in different years.
      keys:
        - 1st
        - 2nd
        - 3rd
        - 4th
        - 5th
        - 6th
        - 7th
      rows:
        - label: January 2015
          values:
            - 5
            - 119
            - 74
            - 117
            - 33
            - 89
            - 79
        - label: January 2016
          values:
            - 3
            - 8
            - 37
            - 82
            - 118
            - 85
            - 80
  with_a_download_link:
    description: Add a download link to the original data. Doesn't do anything clever, just creates a link to the URL passed.
    data:
      chart_heading: Page views chart
      h_axis_title: Day
      v_axis_title: Views
      link: 'https://www.gov.uk'
      chart_overview: This chart shows page views for January in different years.
      keys:
        - 1st
        - 2nd
        - 3rd
        - 4th
        - 5th
        - 6th
        - 7th
      rows:
        - label: January 2015
          values:
            - 5
            - 119
            - 74
            - 117
            - 33
            - 89
            - 79
        - label: January 2016
          values:
            - 3
            - 8
            - 37
            - 82
            - 118
            - 85
            - 80
  with_margin_bottom:
    description: The component accepts a number for margin bottom from `0` to `9` (`0px` to `60px`) using the [GOV.UK Frontend spacing scale](https://design-system.service.gov.uk/styles/spacing/#the-responsive-spacing-scale). It defaults to having a bottom margin of 15px.
    data:
      chart_heading: Page views chart
      h_axis_title: Day
      v_axis_title: Views
      margin_bottom: 9
      chart_overview: This chart shows page views for January in different years.
      keys:
        - 1st
        - 2nd
        - 3rd
        - 4th
        - 5th
        - 6th
        - 7th
      rows:
        - label: January 2015
          values:
            - 5
            - 119
            - 74
            - 117
            - 33
            - 89
            - 79
        - label: January 2016
          values:
            - 3
            - 8
            - 37
            - 82
            - 118
            - 85
            - 80
  minimal_version:
    description: |
      The minimal version presents a simplified version of the chart. This should only be used where there is not enough space to display a full chart, and the user is then given an option to see more information about the chart, for example by including a link next to the chart component. This must be part of the page, as this is not provided by the component itself.

      Specifically, minimal mode:

      - hides the chart heading
      - removes the legend and X and Y axis values
      - removes the data table and link to the data (if supplied) beneath the chart
      - removes the part of the visually hidden accessibility message that links to the table
      - removes the ability to interact with the chart (no hover popups or clicks)
      - sets the size of the points on the chart to zero
    data:
      chart_heading: Page views
      h_axis_title: Day
      v_axis_title: Views
      minimal: true
      chart_overview: This is a graph of views per day
      keys:
        - 1st
        - 2nd
        - 3rd
        - 4th
        - 5th
        - 6th
        - 7th
      rows:
        - label: January 2015
          values:
            - 5
            - 119
            - 74
            - 117
            - 33
            - 89
            - 79
        - label: January 2016
          values:
            - 3
            - 8
            - 37
            - 82
            - 118
            - 85
            - 80
  with_a_different_height:
    description: |
      Sets a height in pixels for the chart, defaulting to `400`. This is useful where the chart might appear in a narrow column and the default height would be too tall.

      The component is not currently responsive.
    data:
      chart_heading: Page views
      h_axis_title: Day
      v_axis_title: Views
      minimal: true
      chart_overview: This is a graph of views per day
      height: 200
      keys:
        - 1st
        - 2nd
        - 3rd
        - 4th
        - 5th
        - 6th
        - 7th
      rows:
        - label: January 2015
          values:
            - 5
            - 119
            - 74
            - 117
            - 33
            - 89
            - 79
        - label: January 2016
          values:
            - 3
            - 8
            - 37
            - 82
            - 118
            - 85
            - 80
  with_hidden_heading:
    description: |
      The heading element is optional, allowing a heading to be set outside the component. Hiding the heading doesn't remove the need to populate `chart_heading` with text, as `chart_heading` is needed for accessibility.
    data:
      chart_heading: Page views
      hide_heading: true
      h_axis_title: Day
      v_axis_title: Views
      chart_overview: This is a graph of views per day
      keys:
        - 1st
        - 2nd
        - 3rd
        - 4th
        - 5th
        - 6th
        - 7th
      rows:
        - label: January 2015
          values:
            - 5
            - 119
            - 74
            - 117
            - 33
            - 89
            - 79
        - label: January 2016
          values:
            - 3
            - 8
            - 37
            - 82
            - 118
            - 85
            - 80