Content presentation - Table

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

2 column table

Open this default table example in new window
Copy default table code 
<table class="hse-table">
  <caption class="hse-table__caption">Skin symptoms and possible causes</caption>
  <thead role="rowgroup" class="hse-table__head">
    <tr role="row">
      <th role="columnheader" class="" scope="col">
        Skin symptoms
      </th>
      <th role="columnheader" class="" scope="col">
        Possible cause
      </th>
    </tr>
  </thead>
  <tbody class="hse-table__body">
    <tr role="row" class="hse-table__row">
      <td class="hse-table__cell">Blisters on lips or around the mouth</td>
      <td class="hse-table__cell ">cold sores</td>
    </tr>
    <tr role="row" class="hse-table__row">
      <td class="hse-table__cell">Itchy, dry, cracked, sore</td>
      <td class="hse-table__cell ">eczema</td>
    </tr>
    <tr role="row" class="hse-table__row">
      <td class="hse-table__cell">Itchy blisters</td>
      <td class="hse-table__cell ">shingles, chickenpox</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: "Skin symptoms and possible causes",
  firstCellIsHeader: false,
  head: [
    {
      text: "Skin symptoms"
    },
    {
      text: "Possible cause"
    }
  ],
  rows: [
    [
      {
        text: "Blisters on lips or around the mouth"
      },
      {
        text: "cold sores"
      }
    ],
    [
      {
        text: "Itchy, dry, cracked, sore"
      },
      {
        text: "eczema"
      }
    ],
    [
      {
        text: "Itchy blisters"
      },
      {
        text: "shingles, chickenpox"
      }
    ]
  ]
}) }}
Close default table code

When to use a table

Use the table to let users compare information in rows and columns.

When not to use a table

Never use tables to layout content on a page. Use the grid system instead.

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

Creating accessible tables - webaim.org

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.

Updated: September 2023