Content presentation - Table

Use a table to make it easier for users to compare and scan information.

2 column table

Open this default table example in new window
Copy default table code 
<table class="hs2-table">
  <caption class="hs2-table__caption">2 Column Table Caption Heading</caption>
  <thead role="rowgroup" class="hs2-table__head">
    <tr role="row">
      <th role="columnheader" class="" scope="col">
        Column one
      </th>
      <th role="columnheader" class="" scope="col">
        Column two
      </th>
    </tr>
  </thead>
  <tbody class="hs2-table__body">
    <tr role="row" class="hs2-table__row">
      <td class="hs2-table__cell">column one item</td>
      <td class="hs2-table__cell ">column two item</td>
    </tr>
    <tr role="row" class="hs2-table__row">
      <td class="hs2-table__cell">column one item</td>
      <td class="hs2-table__cell ">column two item</td>
    </tr>
    <tr role="row" class="hs2-table__row">
      <td class="hs2-table__cell">column one item</td>
      <td class="hs2-table__cell ">column two item</td>
    </tr>
  </tbody>
</table>
Close default table code
Nunjucks macro options

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

Some options are required for the macro to work; these are marked as "Required" in the option description.

If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against cross-site scripting exploits.

Nunjucks arguments for default table
Name Type Required Description
Name rows Type array Required true Description Array of table rows and cells.
Name rows[].text Type string Required true Description If `html` is set, this is not required. Text for cells in table rows. If `html` is provided, the `text` argument will be ignored.
Name rows[].html Type string Required true Description If `text` is set, this is not required. HTML for cells in table rows. If `html` is provided, the `text` argument will be ignored.
Name rows[].format Type string Required false Description Specify format of a cell. Currently we only use "numeric".
Name rows[].colspan Type integer Required false Description Specify how many columns a cell extends.
Name rows[].rowspan Type integer Required false Description Specify how many rows a cell extends.
Name head Type array Required false Description Array of table head cells.
Name head[].text Type string Required false Description If `html` is set, this is not required. Text for table head cells. If `html` is provided, the `text` argument will be ignored.
Name head[].html Type string Required false Description If `text` is set, this is not required. HTML for table head cells. If `html` is provided, the `text` argument will be ignored.
Name head[].format Type string Required false Description Specify format of a cell. Currently we only use "numeric".
Name head[].colspan Type integer Required false Description Specify how many columns a cell extends.
Name head[].rowspan Type integer Required false Description Specify how many rows a cell extends.
Name heading Type string Required false Description Heading/label of the panel if the panel argument is set to true.
Name headingLevel Type integer Required false Description Optional heading level for the heading. Default: 3.
Name caption Type string Required false Description Caption text.
Name captionClasses Type string Required false Description Classes for caption text size. Classes should correspond to the available typography heading classes.
Name firstCellIsHeader Type boolean Required false Description If set to true, first cell in table row will be a TH instead of a TD.
Name responsive Type boolean Required false Description If set to true, responsive table classes will be applied.
Name tableClasses Type string Required false Description Classes to add to the table container.
Name attributes Type object Required false Description HTML attributes (for example data attributes) to add to the table container.
Copy default table code 
{% from 'tables/macro.njk' import table %}

{{ table({
  panel: false,
  caption: "2 Column Table Caption Heading",
  firstCellIsHeader: false,
  head: [
    {
      text: "Column one"
    },
    {
      text: "Column two"
    }
  ],
  rows: [
    [
      {
        text: "column one item"
      },
      {
        text: "column two item"
      }
    ],
    [
      {
        text: "column one item"
      },
      {
        text: "column two item"
      }
    ],
    [
      {
        text: "column one item"
      },
      {
        text: "column two item"
      }
    ]
  ]
}) }}
Close default table code

When not to use a 2 column table

Do not use a 2 column table:

3 or more column table

On large screens this table looks like a 2 column table. However, on smaller screens it collapses.

Open this responsive table example in new window
Copy responsive table code 
<table role="table" class="hs2-table-responsive">
  <caption class="hs2-table__caption">3 Column Table Caption Heading</caption>
  <thead role="rowgroup" class="hs2-table__head">
    <tr role="row">
      <th role="columnheader" class="" scope="col">
        Column one heading
      </th>
      <th role="columnheader" class="" scope="col">
        Column two heading
      </th>
      <th role="columnheader" class="" scope="col">
        Column three heading
      </th>
    </tr>
  </thead>
  <tbody class="hs2-table__body">
    <tr role="row" class="hs2-table__row">
      <td role="cell" class="hs2-table__cell">
        <span class="hs2-table-responsive__heading">Column one heading </span>column one item
      </td>
      <td role="cell" class="hs2-table__cell">
        <span class="hs2-table-responsive__heading">Column two heading </span>column two item
      </td>
      <td role="cell" class="hs2-table__cell">
        <span class="hs2-table-responsive__heading">Column three heading </span>column three item
      </td>
    </tr>
    <tr role="row" class="hs2-table__row">
      <td role="cell" class="hs2-table__cell">
        <span class="hs2-table-responsive__heading">Column one heading </span>column one item
      </td>
      <td role="cell" class="hs2-table__cell">
        <span class="hs2-table-responsive__heading">Column two heading </span>column two item
      </td>
      <td role="cell" class="hs2-table__cell">
        <span class="hs2-table-responsive__heading">Column three heading </span>column three item
      </td>
    </tr>
    <tr role="row" class="hs2-table__row">
      <td role="cell" class="hs2-table__cell">
        <span class="hs2-table-responsive__heading">Column one heading </span>column one item
      </td>
      <td role="cell" class="hs2-table__cell">
        <span class="hs2-table-responsive__heading">Column two heading </span>column two item
      </td>
      <td role="cell" class="hs2-table__cell">
        <span class="hs2-table-responsive__heading">Column three heading </span>column three item
      </td>
    </tr>
  </tbody>
</table>
Close responsive table code
Nunjucks macro options

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

Some options are required for the macro to work; these are marked as "Required" in the option description.

If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against cross-site scripting exploits.

Nunjucks arguments for responsive table
Name Type Required Description
Name rows Type array Required true Description Array of table rows and cells.
Name rows[].text Type string Required true Description If `html` is set, this is not required. Text for cells in table rows. If `html` is provided, the `text` argument will be ignored.
Name rows[].html Type string Required true Description If `text` is set, this is not required. HTML for cells in table rows. If `html` is provided, the `text` argument will be ignored.
Name rows[].format Type string Required false Description Specify format of a cell. Currently we only use "numeric".
Name rows[].colspan Type integer Required false Description Specify how many columns a cell extends.
Name rows[].rowspan Type integer Required false Description Specify how many rows a cell extends.
Name head Type array Required false Description Array of table head cells.
Name head[].text Type string Required false Description If `html` is set, this is not required. Text for table head cells. If `html` is provided, the `text` argument will be ignored.
Name head[].html Type string Required false Description If `text` is set, this is not required. HTML for table head cells. If `html` is provided, the `text` argument will be ignored.
Name head[].format Type string Required false Description Specify format of a cell. Currently we only use "numeric".
Name head[].colspan Type integer Required false Description Specify how many columns a cell extends.
Name head[].rowspan Type integer Required false Description Specify how many rows a cell extends.
Name heading Type string Required false Description Heading/label of the panel if the panel argument is set to true.
Name headingLevel Type integer Required false Description Optional heading level for the heading. Default: 3.
Name caption Type string Required false Description Caption text.
Name captionClasses Type string Required false Description Classes for caption text size. Classes should correspond to the available typography heading classes.
Name firstCellIsHeader Type boolean Required false Description If set to true, first cell in table row will be a TH instead of a TD.
Name responsive Type boolean Required false Description If set to true, responsive table classes will be applied.
Name tableClasses Type string Required false Description Classes to add to the table container.
Name attributes Type object Required false Description HTML attributes (for example data attributes) to add to the table container.
Copy responsive table code 
{% from 'tables/macro.njk' import table %}

{{ table({
  responsive: true,
  panel: false,
  caption: "3 Column Table Caption Heading",
  firstCellIsHeader: false,
  head: [
    {
      text: "Column one heading"
    },
    {
      text: "Column two heading"
    },
    {
      text: "Column three heading"
    }
  ],
  rows: [
    [
      {
        header: "Column one heading",
        text: "column one item"
      },
      {
        header: "Column two heading",
        text: "column two item"
      },
      {
        header: "Column three heading",
        text: "column three item"
      }
    ],
    [
      {
        header: "Column one heading",
        text: "column one item"
      },
      {
        header: "Column two heading",
        text: "column two item"
      },
      {
        header: "Column three heading",
        text: "column three item"
      }
    ],
    [
      {
        header: "Column one heading",
        text: "column one item"
      },
      {
        header: "Column two heading",
        text: "column two item"
      },
      {
        header: "Column three heading",
        text: "column three item"
      }
    ]
  ]
}) }}
Close responsive table code

When not to use a 3 or more column table

Do not use a 3 or more column table:

How tables work

Accessibility

Follow WebAIM's guidance for tables and

  • give tables captions
  • use the scope attribute to associate the data cells with the appropriate headers
  • let the browser window determine the width of the table whenever possible, to reduce horizontal scrolling

Table captions

Use the <caption> element to describe a table in the same way you would use a heading. A caption helps users find, navigate and understand tables.

Table headers

Use table headers to tell users what the rows and columns represent.