Table

Overview

Use a table to present tabular data in two dimensions.

Basic table

Example Table Basic contents

Nunjucksfor Example Table Basic
Nunjucks macro optionsfor Example Table Basic
HTMLfor Example Table Basic

Nunjucks

{% from "components/table/_macro.njk" import onsTable %}
{{
    onsTable({
        "caption": "A basic table with a caption",
        "id": "basic-table",
        "ths": [
            {
                "value": "Column A"
            },
            {
                "value": "Column B"
            },
            {
                "value": "Column C"
            }
        ],
        "trs": [
            {
                "tds": [
                    {
                        "value": "Cell A1"
                    },
                    {
                        "value": "Cell B1"
                    },
                    {
                        "value": "Cell C1"
                    }
                ]
            },
            {
                "tds": [
                    {
                        "value": "Cell A2"
                    },
                    {
                        "value": "Cell B2"
                    },
                    {
                        "value": "Cell C2"
                    }
                ]
            }
        ]
    })
}}

Nunjucks macro options

Name	Type	Required	Description
variants	array or string	false	An array of values or single value (string) to adjust the component using available variants: “compact”, “responsive”,“scrollable”, “sortable”, and “row-hover”
tableClasses	string	false	Classes to add to the `<table>` element of the component
id	string	false	The HTML `id` of the table component
caption	string	false	The caption for the table component
hideCaption	boolean	false	Set to “true” to visually hide the caption
ariaLabel	string	false	The ARIA label to be added if ”scrollable” variant set, to inform screen reader users that the table can be scrolled. Defaults to “Scrollable table“.
ths	Array`<th>`	true	An array of `th` header cell elements for table
trs	Array`<tr>`	true	An array of `tr` row elements for table
sortBy	string	false (unless “sortable” variant set)	Sets the `data-aria-sort` attribute for the table. Used as a prefix for the `aria-label` to announce to screen readers when the table is sorted by a column. For example, “Sort by Date, ascending”.
ariaAsc	string	false (unless “sortable” variant set)	Sets the `data-aria-asc` attribute for the table. Used to update `aria-sort` attribute to announce to screen readers how a table is sorted by a column, for example, "Sort by Date, ascending".
ariaDesc	string	false (unless “sortable” variant set)	Sets the `data-aria-desc` attribute for the table. Used to update `aria-sort` attribute to announce to screen readers how a table is sorted by a column, for example, "Sort by Date, descending".
tfoot	Array`<tfoot>`	false	An array of `td` elements for a `tfoot` footer element

th
Name	Type	Required	Description
thClasses	string	false	Classes to add to the `th` element
ariaSort	string	false	Set to “ascending” or “descending” to set the default order of a table column when the page loads when setting `variants` to “sortable”. Defaults to “none”.
value	string	true	The content for the `th` cell
numeric	boolean	false	Set to “true” if all the cells in the column contain numbers. This aligns the content to the right so numbers can easily be compared.
widthPercentage	integer	false	Sets the `width` attribute for the `th` element

tr
Name	Type	Required	Description
tds	Array`<td>`	true	An array of `td` cell elements for each `tr`
id	string	false	The HTML `id` of the `tr` element
highlight	boolean	false	Set to “true” to highlight the row

td
Name	Type	Required	Description
tdClasses	string	false	Classes to add to the `td` element
id	string	false	The HTML `id` of the `td` element
data	string	false (unless “responsive” variant is set)	Set to the corresponding `th` header cell when using the “responsive” variant
dataSort	integer	false	Set the numerical order of a table cell in a column when using the “sortable” variant
value	string	false	The content for the `td` cell
numeric	boolean	false	Set to “true” if all the cells in the column contain numbers. This aligns the content to the right so numbers can easily be compared.
form	object`<form>`	false	Settings for a form within the `td` cell

form
Name	Type	Required	Description
method	string	false	The HTML `method` attribute for the form. Defaults to `post`.
action	string	true	The HTML `action` attribute for the form
button	object`<button>`	false	Settings for the form’s button
hiddenFormField	object	false	Settings for a hidden form field

hiddenFormField
Name	Type	Required	Description
name	string	false	The HTML `name` attribute for the hidden field `input`
value	string	false	The HTML `value` attribute for the hidden field `input`

button
Name	Type	Required	Description
text	string	true	Text label for the button
id	string	false	Sets the HTML `id` attribute for the button
name	string	false	Sets the HTML `name` attribute for the `<button>`. Not valid if `url` is set.
value	string	false	Sets the HTML `value` attribute for the `<button>`. Not valid if `url` is set.
url	string	false	If set, will create an HTML anchor link with the required classes and attributes
classes	string	false	Classes to add to the button component

tfoot
Name	Type	Required	Description
value	string	true	The content for the `td` cell in the `tfoot`

HTML

<table id="basic-table" class="ons-table ons-table--">
  <caption class="ons-table__caption"> A basic table with a caption </caption>
  <thead class="ons-table__head">
    <tr class="ons-table__row">
      <th scope="col" class="ons-table__header">
        <span class="ons-table__header-text">Column A</span>
      </th>
      <th scope="col" class="ons-table__header">
        <span class="ons-table__header-text">Column B</span>
      </th>
      <th scope="col" class="ons-table__header">
        <span class="ons-table__header-text">Column C</span>
      </th>
    </tr>
  </thead>
  <tbody class="ons-table__body">
    <tr class="ons-table__row">
      <td class="ons-table__cell"> Cell A1 </td>
      <td class="ons-table__cell"> Cell B1 </td>
      <td class="ons-table__cell"> Cell C1 </td>
    </tr>
    <tr class="ons-table__row">
      <td class="ons-table__cell"> Cell A2 </td>
      <td class="ons-table__cell"> Cell B2 </td>
      <td class="ons-table__cell"> Cell C2 </td>
    </tr>
  </tbody>
</table>

When to use this component

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

When not to use this component

Do not use this component for layout purposes.

If a table has no data, replace with a simple line of text saying "No [what the table is supposed to be showing]". For example, "No details about this user".

If a table is supposed to show search results but there are no results, replace with a simple line of text saying "No results for [what the table is supposed to be showing]". For example, "No results for births".

Variants

The “basic table” is the default style for a table. The following variants can be set using the variants parameter.

Use this where you need to display totals.

Example Table Footer contents

Nunjucksfor Example Table Footer
Nunjucks macro optionsfor Example Table Footer
HTMLfor Example Table Footer

Nunjucks

{% from "components/table/_macro.njk" import onsTable %}
{{
    onsTable({
        "caption": "A basic table with a footer",
        "ths": [
            {
                "value": "Column A"
            },
            {
                "value": "Column B"
            },
            {
                "value": "Column C"
            }
        ],
        "trs": [
            {
                "tds": [
                    {
                        "value": "Cell A1"
                    },
                    {
                        "value": "Cell B1"
                    },
                    {
                        "value": "Cell C1"
                    }
                ]
            },
            {
                "tds": [
                    {
                    "value": "Cell A2"
                    },
                    {
                    "value": "Cell B2"
                    },
                    {
                    "value": "Cell C2"
                    }
                ]
            }
        ],
        "tfoot": [
            {
                "value": "Column summary"
            },
            {
                "value": "Column summary"
            },
            {
                "value": "Column summary"
            }
        ]
    })
}}

Nunjucks macro options

Name	Type	Required	Description
variants	array or string	false	An array of values or single value (string) to adjust the component using available variants: “compact”, “responsive”,“scrollable”, “sortable”, and “row-hover”
tableClasses	string	false	Classes to add to the `<table>` element of the component
id	string	false	The HTML `id` of the table component
caption	string	false	The caption for the table component
hideCaption	boolean	false	Set to “true” to visually hide the caption
ariaLabel	string	false	The ARIA label to be added if ”scrollable” variant set, to inform screen reader users that the table can be scrolled. Defaults to “Scrollable table“.
ths	Array`<th>`	true	An array of `th` header cell elements for table
trs	Array`<tr>`	true	An array of `tr` row elements for table
sortBy	string	false (unless “sortable” variant set)	Sets the `data-aria-sort` attribute for the table. Used as a prefix for the `aria-label` to announce to screen readers when the table is sorted by a column. For example, “Sort by Date, ascending”.
ariaAsc	string	false (unless “sortable” variant set)	Sets the `data-aria-asc` attribute for the table. Used to update `aria-sort` attribute to announce to screen readers how a table is sorted by a column, for example, "Sort by Date, ascending".
ariaDesc	string	false (unless “sortable” variant set)	Sets the `data-aria-desc` attribute for the table. Used to update `aria-sort` attribute to announce to screen readers how a table is sorted by a column, for example, "Sort by Date, descending".
tfoot	Array`<tfoot>`	false	An array of `td` elements for a `tfoot` footer element

th
Name	Type	Required	Description
thClasses	string	false	Classes to add to the `th` element
ariaSort	string	false	Set to “ascending” or “descending” to set the default order of a table column when the page loads when setting `variants` to “sortable”. Defaults to “none”.
value	string	true	The content for the `th` cell
numeric	boolean	false	Set to “true” if all the cells in the column contain numbers. This aligns the content to the right so numbers can easily be compared.
widthPercentage	integer	false	Sets the `width` attribute for the `th` element

tr
Name	Type	Required	Description
tds	Array`<td>`	true	An array of `td` cell elements for each `tr`
id	string	false	The HTML `id` of the `tr` element
highlight	boolean	false	Set to “true” to highlight the row

td
Name	Type	Required	Description
tdClasses	string	false	Classes to add to the `td` element
id	string	false	The HTML `id` of the `td` element
data	string	false (unless “responsive” variant is set)	Set to the corresponding `th` header cell when using the “responsive” variant
dataSort	integer	false	Set the numerical order of a table cell in a column when using the “sortable” variant
value	string	false	The content for the `td` cell
numeric	boolean	false	Set to “true” if all the cells in the column contain numbers. This aligns the content to the right so numbers can easily be compared.
form	object`<form>`	false	Settings for a form within the `td` cell

form
Name	Type	Required	Description
method	string	false	The HTML `method` attribute for the form. Defaults to `post`.
action	string	true	The HTML `action` attribute for the form
button	object`<button>`	false	Settings for the form’s button
hiddenFormField	object	false	Settings for a hidden form field

hiddenFormField
Name	Type	Required	Description
name	string	false	The HTML `name` attribute for the hidden field `input`
value	string	false	The HTML `value` attribute for the hidden field `input`

button
Name	Type	Required	Description
text	string	true	Text label for the button
id	string	false	Sets the HTML `id` attribute for the button
name	string	false	Sets the HTML `name` attribute for the `<button>`. Not valid if `url` is set.
value	string	false	Sets the HTML `value` attribute for the `<button>`. Not valid if `url` is set.
url	string	false	If set, will create an HTML anchor link with the required classes and attributes
classes	string	false	Classes to add to the button component

tfoot
Name	Type	Required	Description
value	string	true	The content for the `td` cell in the `tfoot`

HTML

<table class="ons-table ons-table--">
  <caption class="ons-table__caption"> A basic table with a footer </caption>
  <thead class="ons-table__head">
    <tr class="ons-table__row">
      <th scope="col" class="ons-table__header">
        <span class="ons-table__header-text">Column A</span>
      </th>
      <th scope="col" class="ons-table__header">
        <span class="ons-table__header-text">Column B</span>
      </th>
      <th scope="col" class="ons-table__header">
        <span class="ons-table__header-text">Column C</span>
      </th>
    </tr>
  </thead>
  <tbody class="ons-table__body">
    <tr class="ons-table__row">
      <td class="ons-table__cell"> Cell A1 </td>
      <td class="ons-table__cell"> Cell B1 </td>
      <td class="ons-table__cell"> Cell C1 </td>
    </tr>
    <tr class="ons-table__row">
      <td class="ons-table__cell"> Cell A2 </td>
      <td class="ons-table__cell"> Cell B2 </td>
      <td class="ons-table__cell"> Cell C2 </td>
    </tr>
  </tbody>
  <tfoot class="ons-table__foot">
    <tr class="ons-table__row">
      <td class="ons-table__cell ons-u-fs-s">Column summary</td>
      <td class="ons-table__cell ons-u-fs-s">Column summary</td>
      <td class="ons-table__cell ons-u-fs-s">Column summary</td>
    </tr>
  </tfoot>
</table>

Compact table

Use this to display tables with too many columns to fit the viewport.

Setting "variants": 'compact' will reduce the font size of the table content.

Setting an additional row-hover to the array will highlight a row when hovered over by a user.

Example Table Compact contents

Nunjucksfor Example Table Compact
Nunjucks macro optionsfor Example Table Compact
HTMLfor Example Table Compact

Nunjucks

{% from "components/table/_macro.njk" import onsTable %}
{{
    onsTable({
        "variants": ['compact', 'row-hover'],
        "caption": "A compacted table with a large number of columns",
        "ths": [
            {
                "value": "Column A"
            },
            {
                "value": "Column B"
            },
            {
                "value": "Column C"
            },
            {
                "value": "Column D"
            },
            {
                "value": "Column E"
            },
            {
                "value": "Column F"
            }
        ],
        "trs": [
            {
                "tds": [
                    {
                        "value": "Cell A1"
                    },
                    {
                        "value": "Cell B1"
                    },
                    {
                        "value": "Cell C1"
                    },
                    {
                        "value": "Cell D1"
                    },
                    {
                        "value": "Cell E1"
                    },
                    {
                        "value": "Cell F1"
                    }
                ]
            },
            {
                "tds": [
                    {
                    "value": "Cell A2"
                    },
                    {
                    "value": "Cell B2"
                    },
                    {
                    "value": "Cell C2"
                    },
                    {
                    "value": "Cell D2"
                    },
                    {
                        "value": "Cell E1"
                    },
                    {
                        "value": "Cell F1"
                    }
                ]
            }
        ]
    })
}}

Nunjucks macro options

Name	Type	Required	Description
variants	array or string	false	An array of values or single value (string) to adjust the component using available variants: “compact”, “responsive”,“scrollable”, “sortable”, and “row-hover”
tableClasses	string	false	Classes to add to the `<table>` element of the component
id	string	false	The HTML `id` of the table component
caption	string	false	The caption for the table component
hideCaption	boolean	false	Set to “true” to visually hide the caption
ariaLabel	string	false	The ARIA label to be added if ”scrollable” variant set, to inform screen reader users that the table can be scrolled. Defaults to “Scrollable table“.
ths	Array`<th>`	true	An array of `th` header cell elements for table
trs	Array`<tr>`	true	An array of `tr` row elements for table
sortBy	string	false (unless “sortable” variant set)	Sets the `data-aria-sort` attribute for the table. Used as a prefix for the `aria-label` to announce to screen readers when the table is sorted by a column. For example, “Sort by Date, ascending”.
ariaAsc	string	false (unless “sortable” variant set)	Sets the `data-aria-asc` attribute for the table. Used to update `aria-sort` attribute to announce to screen readers how a table is sorted by a column, for example, "Sort by Date, ascending".
ariaDesc	string	false (unless “sortable” variant set)	Sets the `data-aria-desc` attribute for the table. Used to update `aria-sort` attribute to announce to screen readers how a table is sorted by a column, for example, "Sort by Date, descending".
tfoot	Array`<tfoot>`	false	An array of `td` elements for a `tfoot` footer element

th
Name	Type	Required	Description
thClasses	string	false	Classes to add to the `th` element
ariaSort	string	false	Set to “ascending” or “descending” to set the default order of a table column when the page loads when setting `variants` to “sortable”. Defaults to “none”.
value	string	true	The content for the `th` cell
numeric	boolean	false	Set to “true” if all the cells in the column contain numbers. This aligns the content to the right so numbers can easily be compared.
widthPercentage	integer	false	Sets the `width` attribute for the `th` element

tr
Name	Type	Required	Description
tds	Array`<td>`	true	An array of `td` cell elements for each `tr`
id	string	false	The HTML `id` of the `tr` element
highlight	boolean	false	Set to “true” to highlight the row

td
Name	Type	Required	Description
tdClasses	string	false	Classes to add to the `td` element
id	string	false	The HTML `id` of the `td` element
data	string	false (unless “responsive” variant is set)	Set to the corresponding `th` header cell when using the “responsive” variant
dataSort	integer	false	Set the numerical order of a table cell in a column when using the “sortable” variant
value	string	false	The content for the `td` cell
numeric	boolean	false	Set to “true” if all the cells in the column contain numbers. This aligns the content to the right so numbers can easily be compared.
form	object`<form>`	false	Settings for a form within the `td` cell

form
Name	Type	Required	Description
method	string	false	The HTML `method` attribute for the form. Defaults to `post`.
action	string	true	The HTML `action` attribute for the form
button	object`<button>`	false	Settings for the form’s button
hiddenFormField	object	false	Settings for a hidden form field

hiddenFormField
Name	Type	Required	Description
name	string	false	The HTML `name` attribute for the hidden field `input`
value	string	false	The HTML `value` attribute for the hidden field `input`

button
Name	Type	Required	Description
text	string	true	Text label for the button
id	string	false	Sets the HTML `id` attribute for the button
name	string	false	Sets the HTML `name` attribute for the `<button>`. Not valid if `url` is set.
value	string	false	Sets the HTML `value` attribute for the `<button>`. Not valid if `url` is set.
url	string	false	If set, will create an HTML anchor link with the required classes and attributes
classes	string	false	Classes to add to the button component

tfoot
Name	Type	Required	Description
value	string	true	The content for the `td` cell in the `tfoot`

HTML

<table class="ons-table ons-table--compact ons-table--row-hover">
  <caption class="ons-table__caption"> A compacted table with a large number of columns </caption>
  <thead class="ons-table__head">
    <tr class="ons-table__row">
      <th scope="col" class="ons-table__header">
        <span class="ons-table__header-text">Column A</span>
      </th>
      <th scope="col" class="ons-table__header">
        <span class="ons-table__header-text">Column B</span>
      </th>
      <th scope="col" class="ons-table__header">
        <span class="ons-table__header-text">Column C</span>
      </th>
      <th scope="col" class="ons-table__header">
        <span class="ons-table__header-text">Column D</span>
      </th>
      <th scope="col" class="ons-table__header">
        <span class="ons-table__header-text">Column E</span>
      </th>
      <th scope="col" class="ons-table__header">
        <span class="ons-table__header-text">Column F</span>
      </th>
    </tr>
  </thead>
  <tbody class="ons-table__body">
    <tr class="ons-table__row">
      <td class="ons-table__cell"> Cell A1 </td>
      <td class="ons-table__cell"> Cell B1 </td>
      <td class="ons-table__cell"> Cell C1 </td>
      <td class="ons-table__cell"> Cell D1 </td>
      <td class="ons-table__cell"> Cell E1 </td>
      <td class="ons-table__cell"> Cell F1 </td>
    </tr>
    <tr class="ons-table__row">
      <td class="ons-table__cell"> Cell A2 </td>
      <td class="ons-table__cell"> Cell B2 </td>
      <td class="ons-table__cell"> Cell C2 </td>
      <td class="ons-table__cell"> Cell D2 </td>
      <td class="ons-table__cell"> Cell E1 </td>
      <td class="ons-table__cell"> Cell F1 </td>
    </tr>
  </tbody>
</table>

Numeric table

Setting "numeric": true to any table cell will right-align its figures to make them easier to compare with other rows.

Example Table Numeric contents

Nunjucksfor Example Table Numeric
Nunjucks macro optionsfor Example Table Numeric
HTMLfor Example Table Numeric

Nunjucks

{% from "components/table/_macro.njk" import onsTable %}
{{
    onsTable({
        "caption": "A basic table with numeric values",
        "ths": [
            {
                "value": "Country",
                "widthPercentage": 50
            },
            {
                "value": "Population mid-2020",
                "numeric": true,
                "widthPercentage": 25
            },
            {
                "value": "% change 2019 to 2020",
                "numeric": true,
                "widthPercentage": 25
            }
        ],
        "trs": [
            {
                "tds": [
                    {
                        "value": "England"
                    },
                    {
                        "value": "67,081,000",
                        "numeric": true
                    },
                    {
                        "value": "0.43",
                        "numeric": true
                    }
                ]
            },
            {
                "tds": [
                    {
                        "value": "Northern Ireland"
                    },
                    {
                        "value": "1,896,000",
                        "numeric": true
                    },
                    {
                        "value": "0.10",
                        "numeric": true
                    }
                ]
            },
            {
                "tds": [
                    {
                        "value": "Scotland"
                    },
                    {
                        "value": "5,466,000",
                        "numeric": true
                    },
                    {
                        "value": "0.05",
                        "numeric": true
                    }
                ]
            },
            {
                "tds": [
                    {
                        "value": "Wales"
                    },
                    {
                        "value": "3,170,000",
                        "numeric": true
                    },
                    {
                        "value": "0.53",
                        "numeric": true
                    }
                ]
            }
        ]
    })
}}

Nunjucks macro options

Name	Type	Required	Description
variants	array or string	false	An array of values or single value (string) to adjust the component using available variants: “compact”, “responsive”,“scrollable”, “sortable”, and “row-hover”
tableClasses	string	false	Classes to add to the `<table>` element of the component
id	string	false	The HTML `id` of the table component
caption	string	false	The caption for the table component
hideCaption	boolean	false	Set to “true” to visually hide the caption
ariaLabel	string	false	The ARIA label to be added if ”scrollable” variant set, to inform screen reader users that the table can be scrolled. Defaults to “Scrollable table“.
ths	Array`<th>`	true	An array of `th` header cell elements for table
trs	Array`<tr>`	true	An array of `tr` row elements for table
sortBy	string	false (unless “sortable” variant set)	Sets the `data-aria-sort` attribute for the table. Used as a prefix for the `aria-label` to announce to screen readers when the table is sorted by a column. For example, “Sort by Date, ascending”.
ariaAsc	string	false (unless “sortable” variant set)	Sets the `data-aria-asc` attribute for the table. Used to update `aria-sort` attribute to announce to screen readers how a table is sorted by a column, for example, "Sort by Date, ascending".
ariaDesc	string	false (unless “sortable” variant set)	Sets the `data-aria-desc` attribute for the table. Used to update `aria-sort` attribute to announce to screen readers how a table is sorted by a column, for example, "Sort by Date, descending".
tfoot	Array`<tfoot>`	false	An array of `td` elements for a `tfoot` footer element

th
Name	Type	Required	Description
thClasses	string	false	Classes to add to the `th` element
ariaSort	string	false	Set to “ascending” or “descending” to set the default order of a table column when the page loads when setting `variants` to “sortable”. Defaults to “none”.
value	string	true	The content for the `th` cell
numeric	boolean	false	Set to “true” if all the cells in the column contain numbers. This aligns the content to the right so numbers can easily be compared.
widthPercentage	integer	false	Sets the `width` attribute for the `th` element

tr
Name	Type	Required	Description
tds	Array`<td>`	true	An array of `td` cell elements for each `tr`
id	string	false	The HTML `id` of the `tr` element
highlight	boolean	false	Set to “true” to highlight the row

td
Name	Type	Required	Description
tdClasses	string	false	Classes to add to the `td` element
id	string	false	The HTML `id` of the `td` element
data	string	false (unless “responsive” variant is set)	Set to the corresponding `th` header cell when using the “responsive” variant
dataSort	integer	false	Set the numerical order of a table cell in a column when using the “sortable” variant
value	string	false	The content for the `td` cell
numeric	boolean	false	Set to “true” if all the cells in the column contain numbers. This aligns the content to the right so numbers can easily be compared.
form	object`<form>`	false	Settings for a form within the `td` cell

form
Name	Type	Required	Description
method	string	false	The HTML `method` attribute for the form. Defaults to `post`.
action	string	true	The HTML `action` attribute for the form
button	object`<button>`	false	Settings for the form’s button
hiddenFormField	object	false	Settings for a hidden form field

hiddenFormField
Name	Type	Required	Description
name	string	false	The HTML `name` attribute for the hidden field `input`
value	string	false	The HTML `value` attribute for the hidden field `input`

button
Name	Type	Required	Description
text	string	true	Text label for the button
id	string	false	Sets the HTML `id` attribute for the button
name	string	false	Sets the HTML `name` attribute for the `<button>`. Not valid if `url` is set.
value	string	false	Sets the HTML `value` attribute for the `<button>`. Not valid if `url` is set.
url	string	false	If set, will create an HTML anchor link with the required classes and attributes
classes	string	false	Classes to add to the button component

tfoot
Name	Type	Required	Description
value	string	true	The content for the `td` cell in the `tfoot`

HTML

<table class="ons-table ons-table--">
  <caption class="ons-table__caption"> A basic table with numeric values </caption>
  <thead class="ons-table__head">
    <tr class="ons-table__row">
      <th scope="col" class="ons-table__header" width="50%">
        <span class="ons-table__header-text">Country</span>
      </th>
      <th scope="col" class="ons-table__header ons-table__header--numeric" width="25%">
        <span class="ons-table__header-text">Population mid-2020</span>
      </th>
      <th scope="col" class="ons-table__header ons-table__header--numeric" width="25%">
        <span class="ons-table__header-text">% change 2019 to 2020</span>
      </th>
    </tr>
  </thead>
  <tbody class="ons-table__body">
    <tr class="ons-table__row">
      <td class="ons-table__cell"> England </td>
      <td class="ons-table__cell ons-table__cell--numeric"> 67,081,000 </td>
      <td class="ons-table__cell ons-table__cell--numeric"> 0.43 </td>
    </tr>
    <tr class="ons-table__row">
      <td class="ons-table__cell"> Northern Ireland </td>
      <td class="ons-table__cell ons-table__cell--numeric"> 1,896,000 </td>
      <td class="ons-table__cell ons-table__cell--numeric"> 0.10 </td>
    </tr>
    <tr class="ons-table__row">
      <td class="ons-table__cell"> Scotland </td>
      <td class="ons-table__cell ons-table__cell--numeric"> 5,466,000 </td>
      <td class="ons-table__cell ons-table__cell--numeric"> 0.05 </td>
    </tr>
    <tr class="ons-table__row">
      <td class="ons-table__cell"> Wales </td>
      <td class="ons-table__cell ons-table__cell--numeric"> 3,170,000 </td>
      <td class="ons-table__cell ons-table__cell--numeric"> 0.53 </td>
    </tr>
  </tbody>
</table>

Responsive table

Setting "variants": 'responsive' will stack the cells of each table row vertically when viewing on devices with a width less than the small breakpoint.

The associated table header will display repeatedly alongside each cell.

Example Table Responsive contents

Nunjucksfor Example Table Responsive
Nunjucks macro optionsfor Example Table Responsive
HTMLfor Example Table Responsive

Nunjucks

{% from "components/table/_macro.njk" import onsTable %}
{{
    onsTable({
        "variants": 'responsive',
        "caption": "Responsive table with stacked rows for small viewports",
        "ths": [
            {
                "value": "Country"
            },
            {
                "value": "Highest mountain"
            },
            {
                "value": "Height in metres",
                "numeric": true
            }
        ],
        "trs": [
            {
                "tds": [
                    {
                        "value": "Scotland",
                        "data": "Country"
                    },
                    {
                        "value": "Ben Nevis",
                        "data": "Highest mountain"
                    },
                    {
                        "value": "1,345",
                        "data": "Height",
                        "numeric": true
                    }
                ]
            },
            {
                "tds": [
                    {
                        "value": "Wales",
                        "data": "Country"
                    },
                    {
                        "value": "Snowdon",
                        "data": "Highest mountain"
                    },
                    {
                        "value": "1,085",
                        "data": "Height",
                        "numeric": true
                    }
                ]
            },
            {
                "tds": [
                    {
                        "value": "England",
                        "data": "Country"
                    },
                    {
                        "value": "Scafell Pike",
                        "data": "Highest mountain"
                    },
                    {
                        "value": "978",
                        "data": "Height",
                        "numeric": true
                    }
                ]
            },
            {
                "tds": [
                    {
                        "value": "Northern Ireland",
                        "data": "Country"
                    },
                    {
                        "value": "Slieve Donard",
                        "data": "Highest mountain"
                    },
                    {
                        "value": "850",
                        "data": "Height",
                        "numeric": true
                    }
                ]
            }
        ]
    })
}}

Nunjucks macro options

Name	Type	Required	Description
variants	array or string	false	An array of values or single value (string) to adjust the component using available variants: “compact”, “responsive”,“scrollable”, “sortable”, and “row-hover”
tableClasses	string	false	Classes to add to the `<table>` element of the component
id	string	false	The HTML `id` of the table component
caption	string	false	The caption for the table component
hideCaption	boolean	false	Set to “true” to visually hide the caption
ariaLabel	string	false	The ARIA label to be added if ”scrollable” variant set, to inform screen reader users that the table can be scrolled. Defaults to “Scrollable table“.
ths	Array`<th>`	true	An array of `th` header cell elements for table
trs	Array`<tr>`	true	An array of `tr` row elements for table
sortBy	string	false (unless “sortable” variant set)	Sets the `data-aria-sort` attribute for the table. Used as a prefix for the `aria-label` to announce to screen readers when the table is sorted by a column. For example, “Sort by Date, ascending”.
ariaAsc	string	false (unless “sortable” variant set)	Sets the `data-aria-asc` attribute for the table. Used to update `aria-sort` attribute to announce to screen readers how a table is sorted by a column, for example, "Sort by Date, ascending".
ariaDesc	string	false (unless “sortable” variant set)	Sets the `data-aria-desc` attribute for the table. Used to update `aria-sort` attribute to announce to screen readers how a table is sorted by a column, for example, "Sort by Date, descending".
tfoot	Array`<tfoot>`	false	An array of `td` elements for a `tfoot` footer element

th
Name	Type	Required	Description
thClasses	string	false	Classes to add to the `th` element
ariaSort	string	false	Set to “ascending” or “descending” to set the default order of a table column when the page loads when setting `variants` to “sortable”. Defaults to “none”.
value	string	true	The content for the `th` cell
numeric	boolean	false	Set to “true” if all the cells in the column contain numbers. This aligns the content to the right so numbers can easily be compared.
widthPercentage	integer	false	Sets the `width` attribute for the `th` element

tr
Name	Type	Required	Description
tds	Array`<td>`	true	An array of `td` cell elements for each `tr`
id	string	false	The HTML `id` of the `tr` element
highlight	boolean	false	Set to “true” to highlight the row

td
Name	Type	Required	Description
tdClasses	string	false	Classes to add to the `td` element
id	string	false	The HTML `id` of the `td` element
data	string	false (unless “responsive” variant is set)	Set to the corresponding `th` header cell when using the “responsive” variant
dataSort	integer	false	Set the numerical order of a table cell in a column when using the “sortable” variant
value	string	false	The content for the `td` cell
numeric	boolean	false	Set to “true” if all the cells in the column contain numbers. This aligns the content to the right so numbers can easily be compared.
form	object`<form>`	false	Settings for a form within the `td` cell

form
Name	Type	Required	Description
method	string	false	The HTML `method` attribute for the form. Defaults to `post`.
action	string	true	The HTML `action` attribute for the form
button	object`<button>`	false	Settings for the form’s button
hiddenFormField	object	false	Settings for a hidden form field

hiddenFormField
Name	Type	Required	Description
name	string	false	The HTML `name` attribute for the hidden field `input`
value	string	false	The HTML `value` attribute for the hidden field `input`

button
Name	Type	Required	Description
text	string	true	Text label for the button
id	string	false	Sets the HTML `id` attribute for the button
name	string	false	Sets the HTML `name` attribute for the `<button>`. Not valid if `url` is set.
value	string	false	Sets the HTML `value` attribute for the `<button>`. Not valid if `url` is set.
url	string	false	If set, will create an HTML anchor link with the required classes and attributes
classes	string	false	Classes to add to the button component

tfoot
Name	Type	Required	Description
value	string	true	The content for the `td` cell in the `tfoot`

HTML

<table class="ons-table ons-table--responsive">
  <caption class="ons-table__caption"> Responsive table with stacked rows for small viewports </caption>
  <thead class="ons-table__head">
    <tr class="ons-table__row">
      <th scope="col" class="ons-table__header">
        <span class="ons-table__header-text">Country</span>
      </th>
      <th scope="col" class="ons-table__header">
        <span class="ons-table__header-text">Highest mountain</span>
      </th>
      <th scope="col" class="ons-table__header ons-table__header--numeric">
        <span class="ons-table__header-text">Height in metres</span>
      </th>
    </tr>
  </thead>
  <tbody class="ons-table__body">
    <tr class="ons-table__row">
      <td class="ons-table__cell" data-th="Country"> Scotland </td>
      <td class="ons-table__cell" data-th="Highest mountain"> Ben Nevis </td>
      <td class="ons-table__cell ons-table__cell--numeric" data-th="Height"> 1,345 </td>
    </tr>
    <tr class="ons-table__row">
      <td class="ons-table__cell" data-th="Country"> Wales </td>
      <td class="ons-table__cell" data-th="Highest mountain"> Snowdon </td>
      <td class="ons-table__cell ons-table__cell--numeric" data-th="Height"> 1,085 </td>
    </tr>
    <tr class="ons-table__row">
      <td class="ons-table__cell" data-th="Country"> England </td>
      <td class="ons-table__cell" data-th="Highest mountain"> Scafell Pike </td>
      <td class="ons-table__cell ons-table__cell--numeric" data-th="Height"> 978 </td>
    </tr>
    <tr class="ons-table__row">
      <td class="ons-table__cell" data-th="Country"> Northern Ireland </td>
      <td class="ons-table__cell" data-th="Highest mountain"> Slieve Donard </td>
      <td class="ons-table__cell ons-table__cell--numeric" data-th="Height"> 850 </td>
    </tr>
  </tbody>
</table>

Scrollable table

Use this only as a last resort after the responsive or compact tables. Some users find the scroll feature difficult to interact with.

Setting "variants": 'scrollable' will create a full-width, scrollable table.

Example Table Scrollable contents

Nunjucksfor Example Table Scrollable
Nunjucks macro optionsfor Example Table Scrollable
HTMLfor Example Table Scrollable

Nunjucks

{% from "components/table/_macro.njk" import onsTable %}
{{
    onsTable({
        "variants": 'scrollable',
        "caption": "Scrollable table",
        "ariaLabel": "There are 7 columns in this table. Some of the table may be off screen. Scroll or drag horizontally to bring into view.",
        "ths": [
            {
                "value": "ID"
            },
            {
                "value": "Title"
            },
            {
                "value": "Abbreviation"
            },
            {
                "value": "Legal basis"
            },
            {
                "value": "Frequency"
            },
            {
                "value": "Date"
            },
            {
                "value": "Status"
            }
        ],
        "trs": [
            {
                "tds": [
                    {
                        "value": "023"
                    },
                    {
                        "value": "Monthly Business Survey - Retail Sales Index"
                    },
                    {
                        "value": "RSI"
                    },
                    {
                        "value": "Statistics of Trade Act 1947"
                    },
                    {
                        "value": "Monthly"
                    },
                    {
                        "value": "20 Jan 2018"
                    },
                    {
                        "value": "<span class='ons-status ons-status--success'>Ready</span>"
                    }
                ]
            },
            {
                "tds": [
                    {
                        "value": "112"
                    },
                    {
                        "value": "Annual Inward Foreign Direct Investment Survey"
                    },
                    {
                        "value": "AIFDI"
                    },
                    {
                        "value": "Statistics of Trade Act 1947"
                    },
                    {
                        "value": "Annually"
                    },
                    {
                        "value": "26 Feb 2018"
                    },
                    {
                        "value": "<span class='ons-status ons-status--dead'>Not ready</span>"
                    }
                ]
            },
            {
                "tds": [
                    {
                        "value": "332"
                    },
                    {
                        "value": "Business Register and Employment Survey"
                    },
                    {
                        "value": "BRES"
                    },
                    {
                        "value": "Statistics of Trade Act 1947"
                    },
                    {
                        "value": "Annually"
                    },
                    {
                        "value": "23 Jan 2013"
                    },
                    {
                        "value": "<span class='ons-status ons-status--info'>In progress</span>"
                    }
                ]
            },
            {
                "tds": [
                    {
                        "value": "654"
                    },
                    {
                        "value": "Quartely Survey of Building Materials Sand and Gravel"
                    },
                    {
                        "value": "QBMS"
                    },
                    {
                        "value": "Statistics of Trade Act 1947 - BEIS"
                    },
                    {
                        "value": "Quartely"
                    },
                    {
                        "value": "24 Jan 2015"
                    },
                    {
                        "value": "<span class='ons-status ons-status--error'>Issue</span>"
                    }
                ]
            },
            {
                "tds": [
                    {
                        "value": "765"
                    },
                    {
                        "value": "Monthly Survey of Building Materials Concrete Building Blocks"
                    },
                    {
                        "value": "MSBB"
                    },
                    {
                        "value": "Voluntary"
                    },
                    {
                        "value": "Monthly"
                    },
                    {
                        "value": "25 Jan 2014"
                    },
                    {
                        "value": "<span class='ons-status ons-status--success'>Ready</span>"
                    }
                ]
            }
        ]
    })
}}

Nunjucks macro options

Name	Type	Required	Description
variants	array or string	false	An array of values or single value (string) to adjust the component using available variants: “compact”, “responsive”,“scrollable”, “sortable”, and “row-hover”
tableClasses	string	false	Classes to add to the `<table>` element of the component
id	string	false	The HTML `id` of the table component
caption	string	false	The caption for the table component
hideCaption	boolean	false	Set to “true” to visually hide the caption
ariaLabel	string	false	The ARIA label to be added if ”scrollable” variant set, to inform screen reader users that the table can be scrolled. Defaults to “Scrollable table“.
ths	Array`<th>`	true	An array of `th` header cell elements for table
trs	Array`<tr>`	true	An array of `tr` row elements for table
sortBy	string	false (unless “sortable” variant set)	Sets the `data-aria-sort` attribute for the table. Used as a prefix for the `aria-label` to announce to screen readers when the table is sorted by a column. For example, “Sort by Date, ascending”.
ariaAsc	string	false (unless “sortable” variant set)	Sets the `data-aria-asc` attribute for the table. Used to update `aria-sort` attribute to announce to screen readers how a table is sorted by a column, for example, "Sort by Date, ascending".
ariaDesc	string	false (unless “sortable” variant set)	Sets the `data-aria-desc` attribute for the table. Used to update `aria-sort` attribute to announce to screen readers how a table is sorted by a column, for example, "Sort by Date, descending".
tfoot	Array`<tfoot>`	false	An array of `td` elements for a `tfoot` footer element

th
Name	Type	Required	Description
thClasses	string	false	Classes to add to the `th` element
ariaSort	string	false	Set to “ascending” or “descending” to set the default order of a table column when the page loads when setting `variants` to “sortable”. Defaults to “none”.
value	string	true	The content for the `th` cell
numeric	boolean	false	Set to “true” if all the cells in the column contain numbers. This aligns the content to the right so numbers can easily be compared.
widthPercentage	integer	false	Sets the `width` attribute for the `th` element

tr
Name	Type	Required	Description
tds	Array`<td>`	true	An array of `td` cell elements for each `tr`
id	string	false	The HTML `id` of the `tr` element
highlight	boolean	false	Set to “true” to highlight the row

td
Name	Type	Required	Description
tdClasses	string	false	Classes to add to the `td` element
id	string	false	The HTML `id` of the `td` element
data	string	false (unless “responsive” variant is set)	Set to the corresponding `th` header cell when using the “responsive” variant
dataSort	integer	false	Set the numerical order of a table cell in a column when using the “sortable” variant
value	string	false	The content for the `td` cell
numeric	boolean	false	Set to “true” if all the cells in the column contain numbers. This aligns the content to the right so numbers can easily be compared.
form	object`<form>`	false	Settings for a form within the `td` cell

form
Name	Type	Required	Description
method	string	false	The HTML `method` attribute for the form. Defaults to `post`.
action	string	true	The HTML `action` attribute for the form
button	object`<button>`	false	Settings for the form’s button
hiddenFormField	object	false	Settings for a hidden form field

hiddenFormField
Name	Type	Required	Description
name	string	false	The HTML `name` attribute for the hidden field `input`
value	string	false	The HTML `value` attribute for the hidden field `input`

button
Name	Type	Required	Description
text	string	true	Text label for the button
id	string	false	Sets the HTML `id` attribute for the button
name	string	false	Sets the HTML `name` attribute for the `<button>`. Not valid if `url` is set.
value	string	false	Sets the HTML `value` attribute for the `<button>`. Not valid if `url` is set.
url	string	false	If set, will create an HTML anchor link with the required classes and attributes
classes	string	false	Classes to add to the button component

tfoot
Name	Type	Required	Description
value	string	true	The content for the `td` cell in the `tfoot`

HTML

<div class="ons-table-scrollable ons-table-scrollable--on">
  <div class="ons-table-scrollable__content" tabindex="0" role="region"
    aria-label="Scrollable table. There are 7 columns in this table. Some of the table may be off screen. Scroll or drag horizontally to bring into view.">
    <table class="ons-table ons-table--scrollable">
      <caption class="ons-table__caption"> Scrollable table </caption>
      <thead class="ons-table__head">
        <tr class="ons-table__row">
          <th scope="col" class="ons-table__header">
            <span class="ons-table__header-text">ID</span>
          </th>
          <th scope="col" class="ons-table__header">
            <span class="ons-table__header-text">Title</span>
          </th>
          <th scope="col" class="ons-table__header">
            <span class="ons-table__header-text">Abbreviation</span>
          </th>
          <th scope="col" class="ons-table__header">
            <span class="ons-table__header-text">Legal basis</span>
          </th>
          <th scope="col" class="ons-table__header">
            <span class="ons-table__header-text">Frequency</span>
          </th>
          <th scope="col" class="ons-table__header">
            <span class="ons-table__header-text">Date</span>
          </th>
          <th scope="col" class="ons-table__header">
            <span class="ons-table__header-text">Status</span>
          </th>
        </tr>
      </thead>
      <tbody class="ons-table__body">
        <tr class="ons-table__row">
          <td class="ons-table__cell"> 023 </td>
          <td class="ons-table__cell"> Monthly Business Survey - Retail Sales Index </td>
          <td class="ons-table__cell"> RSI </td>
          <td class="ons-table__cell"> Statistics of Trade Act 1947 </td>
          <td class="ons-table__cell"> Monthly </td>
          <td class="ons-table__cell"> 20 Jan 2018 </td>
          <td class="ons-table__cell">
            <span class='ons-status ons-status--success'>Ready</span>
          </td>
        </tr>
        <tr class="ons-table__row">
          <td class="ons-table__cell"> 112 </td>
          <td class="ons-table__cell"> Annual Inward Foreign Direct Investment Survey </td>
          <td class="ons-table__cell"> AIFDI </td>
          <td class="ons-table__cell"> Statistics of Trade Act 1947 </td>
          <td class="ons-table__cell"> Annually </td>
          <td class="ons-table__cell"> 26 Feb 2018 </td>
          <td class="ons-table__cell">
            <span class='ons-status ons-status--dead'>Not ready</span>
          </td>
        </tr>
        <tr class="ons-table__row">
          <td class="ons-table__cell"> 332 </td>
          <td class="ons-table__cell"> Business Register and Employment Survey </td>
          <td class="ons-table__cell"> BRES </td>
          <td class="ons-table__cell"> Statistics of Trade Act 1947 </td>
          <td class="ons-table__cell"> Annually </td>
          <td class="ons-table__cell"> 23 Jan 2013 </td>
          <td class="ons-table__cell">
            <span class='ons-status ons-status--info'>In progress</span>
          </td>
        </tr>
        <tr class="ons-table__row">
          <td class="ons-table__cell"> 654 </td>
          <td class="ons-table__cell"> Quartely Survey of Building Materials Sand and Gravel </td>
          <td class="ons-table__cell"> QBMS </td>
          <td class="ons-table__cell"> Statistics of Trade Act 1947 - BEIS </td>
          <td class="ons-table__cell"> Quartely </td>
          <td class="ons-table__cell"> 24 Jan 2015 </td>
          <td class="ons-table__cell">
            <span class='ons-status ons-status--error'>Issue</span>
          </td>
        </tr>
        <tr class="ons-table__row">
          <td class="ons-table__cell"> 765 </td>
          <td class="ons-table__cell"> Monthly Survey of Building Materials Concrete Building Blocks </td>
          <td class="ons-table__cell"> MSBB </td>
          <td class="ons-table__cell"> Voluntary </td>
          <td class="ons-table__cell"> Monthly </td>
          <td class="ons-table__cell"> 25 Jan 2014 </td>
          <td class="ons-table__cell">
            <span class='ons-status ons-status--success'>Ready</span>
          </td>
        </tr>
      </tbody>
    </table>
  </div>
</div>

Sortable table

This variant is useful for tables that are regularly updated.

Setting "variants": 'sortable' will apply a JavaScript enhancement to allow each column to be sorted.

By default, the column will be sorted alphabetically, but an optional parameter "dataSort": '<number>' can be added to each table cell to control it’s position for sorting.

Example Table Sortable contents

Nunjucksfor Example Table Sortable
Nunjucks macro optionsfor Example Table Sortable
HTMLfor Example Table Sortable

Nunjucks

{% from "components/table/_macro.njk" import onsTable %}

{{
    onsTable({
        "variants": 'sortable',
        "caption": "Javascript enhanced sortable table",
        "sortBy": "Sort by",
        "ariaAsc": "ascending",
        "ariaDesc": "descending",
        "ths": [
            {
                "value": "ID"
            },
            {
                "value": "Title"
            },
            {
                "value": "Abbreviation"
            },
            {
                "value": "Legal basis"
            },
            {
                "value": "Frequency"
            },
            {
                "value": "Date"
            },
            {
                "value": "Status"
            }
        ],
        "trs": [
            {
                "tds": [
                    {
                        "value": "023"
                    },
                    {
                        "value": "Monthly Business Survey - Retail Sales Index"
                    },
                    {
                        "value": "RSI"
                    },
                    {
                        "value": "Statistics of Trade Act 1947"
                    },
                    {
                        "value": "Monthly",
                        "dataSort": "1"
                    },
                    {
                        "value": "20 Jan 2018",
                        "dataSort": "2018-01-20"
                    },
                    {
                        "value": "<span class='ons-status ons-status--success'>Ready</span>",
                        "dataSort": "0"
                    },
                    {
                        "form": {
                            "method": "Get",
                            "action": "#",
                            "button": {
                                "type": "button",
                                "text": "View details",
                                "variants": ["small", "secondary"],
                                "url": "#0"
                            }
                        }
                    }
                ]
            },
            {
                "tds": [
                    {
                        "value": "112"
                    },
                    {
                        "value": "Annual Inward Foreign Direct Investment Survey"
                    },
                    {
                        "value": "AIFDI"
                    },
                    {
                        "value": "Statistics of Trade Act 1947"
                    },
                    {
                        "value": "Annually",
                        "dataSort": "12"
                    },
                    {
                        "value": "26 Feb 2018",
                        "dataSort": "2018-02-26"
                    },
                    {
                        "value": "<span class='ons-status ons-status--dead'>Not ready</span>",
                        "dataSort": "1"
                    },
                    {
                        "form": {
                            "method": "Get",
                            "action": "#",
                            "button": {
                                "type": "button",
                                "text": "View details",
                                "variants": ["small", "secondary"],
                                "url": "#0"
                            }
                        }
                    }
                ]
            },
            {
                "tds": [
                    {
                        "value": "332"
                    },
                    {
                        "value": "Business Register and Employment Survey"
                    },
                    {
                        "value": "BRES"
                    },
                    {
                        "value": "Statistics of Trade Act 1947"
                    },
                    {
                        "value": "Annually",
                        "dataSort": "12"
                    },
                    {
                        "value": "23 Jan 2013",
                        "dataSort": "2013-01-23"
                    },
                    {
                        "value": "<span class='ons-status ons-status--info'>In progress</span>",
                        "dataSort": "2"
                    },
                    {
                        "form": {
                            "method": "Get",
                            "action": "#",
                            "button": {
                                "type": "button",
                                "text": "View details",
                                "variants": ["small", "secondary"],
                                "url": "#0"
                            }
                        }
                    }
                ]
            },
            {
                "tds": [
                    {
                        "value": "654"
                    },
                    {
                        "value": "Quartely Survey of Building Materials Sand and Gravel"
                    },
                    {
                        "value": "QBMS"
                    },
                    {
                        "value": "Statistics of Trade Act 1947 - BEIS"
                    },
                    {
                        "value": "Quartely",
                        "dataSort": "3"
                    },
                    {
                        "value": "24 Jan 2015",
                        "dataSort": "2015-01-24"
                    },
                    {
                        "value": "<span class='ons-status ons-status--error'>Issue</span>",
                        "dataSort": "3"
                    },
                    {
                        "form": {
                            "method": "Get",
                            "action": "#",
                            "button": {
                                "type": "button",
                                "text": "View details",
                                "variants": ["small", "secondary"],
                                "url": "#0"
                            }
                        }
                    }
                ]
            },
            {
                "tds": [
                    {
                        "value": "765"
                    },
                    {
                        "value": "Monthly Survey of Building Materials Concrete Building Blocks"
                    },
                    {
                        "value": "MSBB"
                    },
                    {
                        "value": "Voluntary"
                    },
                    {
                        "value": "Monthly",
                        "dataSort": "1"
                    },
                    {
                        "value": "25 Jan 2014",
                        "dataSort": "2014-01-25"
                    },
                    {
                        "value": "<span class='ons-status ons-status--success'>Ready</span>",
                        "dataSort": "0"
                    },
                    {
                        "form": {
                            "method": "Get",
                            "action": "#",
                            "button": {
                                "type": "button",
                                "text": "View details",
                                "variants": ["small", "secondary"],
                                "url": "#0"
                            }
                        }
                    }
                ]
            }
        ]
    })
}}

Nunjucks macro options

Name	Type	Required	Description
variants	array or string	false	An array of values or single value (string) to adjust the component using available variants: “compact”, “responsive”,“scrollable”, “sortable”, and “row-hover”
tableClasses	string	false	Classes to add to the `<table>` element of the component
id	string	false	The HTML `id` of the table component
caption	string	false	The caption for the table component
hideCaption	boolean	false	Set to “true” to visually hide the caption
ariaLabel	string	false	The ARIA label to be added if ”scrollable” variant set, to inform screen reader users that the table can be scrolled. Defaults to “Scrollable table“.
ths	Array`<th>`	true	An array of `th` header cell elements for table
trs	Array`<tr>`	true	An array of `tr` row elements for table
sortBy	string	false (unless “sortable” variant set)	Sets the `data-aria-sort` attribute for the table. Used as a prefix for the `aria-label` to announce to screen readers when the table is sorted by a column. For example, “Sort by Date, ascending”.
ariaAsc	string	false (unless “sortable” variant set)	Sets the `data-aria-asc` attribute for the table. Used to update `aria-sort` attribute to announce to screen readers how a table is sorted by a column, for example, "Sort by Date, ascending".
ariaDesc	string	false (unless “sortable” variant set)	Sets the `data-aria-desc` attribute for the table. Used to update `aria-sort` attribute to announce to screen readers how a table is sorted by a column, for example, "Sort by Date, descending".
tfoot	Array`<tfoot>`	false	An array of `td` elements for a `tfoot` footer element

th
Name	Type	Required	Description
thClasses	string	false	Classes to add to the `th` element
ariaSort	string	false	Set to “ascending” or “descending” to set the default order of a table column when the page loads when setting `variants` to “sortable”. Defaults to “none”.
value	string	true	The content for the `th` cell
numeric	boolean	false	Set to “true” if all the cells in the column contain numbers. This aligns the content to the right so numbers can easily be compared.
widthPercentage	integer	false	Sets the `width` attribute for the `th` element

tr
Name	Type	Required	Description
tds	Array`<td>`	true	An array of `td` cell elements for each `tr`
id	string	false	The HTML `id` of the `tr` element
highlight	boolean	false	Set to “true” to highlight the row

td
Name	Type	Required	Description
tdClasses	string	false	Classes to add to the `td` element
id	string	false	The HTML `id` of the `td` element
data	string	false (unless “responsive” variant is set)	Set to the corresponding `th` header cell when using the “responsive” variant
dataSort	integer	false	Set the numerical order of a table cell in a column when using the “sortable” variant
value	string	false	The content for the `td` cell
numeric	boolean	false	Set to “true” if all the cells in the column contain numbers. This aligns the content to the right so numbers can easily be compared.
form	object`<form>`	false	Settings for a form within the `td` cell

form
Name	Type	Required	Description
method	string	false	The HTML `method` attribute for the form. Defaults to `post`.
action	string	true	The HTML `action` attribute for the form
button	object`<button>`	false	Settings for the form’s button
hiddenFormField	object	false	Settings for a hidden form field

hiddenFormField
Name	Type	Required	Description
name	string	false	The HTML `name` attribute for the hidden field `input`
value	string	false	The HTML `value` attribute for the hidden field `input`

button
Name	Type	Required	Description
text	string	true	Text label for the button
id	string	false	Sets the HTML `id` attribute for the button
name	string	false	Sets the HTML `name` attribute for the `<button>`. Not valid if `url` is set.
value	string	false	Sets the HTML `value` attribute for the `<button>`. Not valid if `url` is set.
url	string	false	If set, will create an HTML anchor link with the required classes and attributes
classes	string	false	Classes to add to the button component

tfoot
Name	Type	Required	Description
value	string	true	The content for the `td` cell in the `tfoot`

HTML

<table class="ons-table ons-table--sortable" data-aria-sort="Sort by" data-aria-asc="ascending"
  data-aria-desc="descending">
  <caption class="ons-table__caption"> Javascript enhanced sortable table </caption>
  <thead class="ons-table__head">
    <tr class="ons-table__row">
      <th scope="col" class="ons-table__header" aria-sort="none">
        <span class="ons-table__header-text">ID</span>
        <svg id="sort-sprite-id" class="ons-icon ons-u-d-no" viewBox="0 0 12 19" xmlns="http://www.w3.org/2000/svg"
          focusable="false" fill="currentColor" role="img" title="ons-icon-sort-sprite">
          <path class="ons-topTriangle" d="M6 0l6 7.2H0L6 0zm0 18.6l6-7.2H0l6 7.2zm0 3.6l6 7.2H0l6-7.2z" />
          <path class="ons-bottomTriangle" d="M6 18.6l6-7.2H0l6 7.2zm0 3.6l6 7.2H0l6-7.2z" />
        </svg>
      </th>
      <th scope="col" class="ons-table__header" aria-sort="none">
        <span class="ons-table__header-text">Title</span>
        <svg id="sort-sprite-title" class="ons-icon ons-u-d-no" viewBox="0 0 12 19" xmlns="http://www.w3.org/2000/svg"
          focusable="false" fill="currentColor" role="img" title="ons-icon-sort-sprite">
          <path class="ons-topTriangle" d="M6 0l6 7.2H0L6 0zm0 18.6l6-7.2H0l6 7.2zm0 3.6l6 7.2H0l6-7.2z" />
          <path class="ons-bottomTriangle" d="M6 18.6l6-7.2H0l6 7.2zm0 3.6l6 7.2H0l6-7.2z" />
        </svg>
      </th>
      <th scope="col" class="ons-table__header" aria-sort="none">
        <span class="ons-table__header-text">Abbreviation</span>
        <svg id="sort-sprite-abbreviation" class="ons-icon ons-u-d-no" viewBox="0 0 12 19"
          xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor" role="img"
          title="ons-icon-sort-sprite">
          <path class="ons-topTriangle" d="M6 0l6 7.2H0L6 0zm0 18.6l6-7.2H0l6 7.2zm0 3.6l6 7.2H0l6-7.2z" />
          <path class="ons-bottomTriangle" d="M6 18.6l6-7.2H0l6 7.2zm0 3.6l6 7.2H0l6-7.2z" />
        </svg>
      </th>
      <th scope="col" class="ons-table__header" aria-sort="none">
        <span class="ons-table__header-text">Legal basis</span>
        <svg id="sort-sprite-legal-basis" class="ons-icon ons-u-d-no" viewBox="0 0 12 19"
          xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor" role="img"
          title="ons-icon-sort-sprite">
          <path class="ons-topTriangle" d="M6 0l6 7.2H0L6 0zm0 18.6l6-7.2H0l6 7.2zm0 3.6l6 7.2H0l6-7.2z" />
          <path class="ons-bottomTriangle" d="M6 18.6l6-7.2H0l6 7.2zm0 3.6l6 7.2H0l6-7.2z" />
        </svg>
      </th>
      <th scope="col" class="ons-table__header" aria-sort="none">
        <span class="ons-table__header-text">Frequency</span>
        <svg id="sort-sprite-frequency" class="ons-icon ons-u-d-no" viewBox="0 0 12 19"
          xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor" role="img"
          title="ons-icon-sort-sprite">
          <path class="ons-topTriangle" d="M6 0l6 7.2H0L6 0zm0 18.6l6-7.2H0l6 7.2zm0 3.6l6 7.2H0l6-7.2z" />
          <path class="ons-bottomTriangle" d="M6 18.6l6-7.2H0l6 7.2zm0 3.6l6 7.2H0l6-7.2z" />
        </svg>
      </th>
      <th scope="col" class="ons-table__header" aria-sort="none">
        <span class="ons-table__header-text">Date</span>
        <svg id="sort-sprite-date" class="ons-icon ons-u-d-no" viewBox="0 0 12 19" xmlns="http://www.w3.org/2000/svg"
          focusable="false" fill="currentColor" role="img" title="ons-icon-sort-sprite">
          <path class="ons-topTriangle" d="M6 0l6 7.2H0L6 0zm0 18.6l6-7.2H0l6 7.2zm0 3.6l6 7.2H0l6-7.2z" />
          <path class="ons-bottomTriangle" d="M6 18.6l6-7.2H0l6 7.2zm0 3.6l6 7.2H0l6-7.2z" />
        </svg>
      </th>
      <th scope="col" class="ons-table__header" aria-sort="none">
        <span class="ons-table__header-text">Status</span>
        <svg id="sort-sprite-status" class="ons-icon ons-u-d-no" viewBox="0 0 12 19" xmlns="http://www.w3.org/2000/svg"
          focusable="false" fill="currentColor" role="img" title="ons-icon-sort-sprite">
          <path class="ons-topTriangle" d="M6 0l6 7.2H0L6 0zm0 18.6l6-7.2H0l6 7.2zm0 3.6l6 7.2H0l6-7.2z" />
          <path class="ons-bottomTriangle" d="M6 18.6l6-7.2H0l6 7.2zm0 3.6l6 7.2H0l6-7.2z" />
        </svg>
      </th>
    </tr>
  </thead>
  <tbody class="ons-table__body">
    <tr class="ons-table__row">
      <td class="ons-table__cell"> 023 </td>
      <td class="ons-table__cell"> Monthly Business Survey - Retail Sales Index </td>
      <td class="ons-table__cell"> RSI </td>
      <td class="ons-table__cell"> Statistics of Trade Act 1947 </td>
      <td class="ons-table__cell" data-sort-value="1"> Monthly </td>
      <td class="ons-table__cell" data-sort-value="2018-01-20"> 20 Jan 2018 </td>
      <td class="ons-table__cell" data-sort-value="0">
        <span class='ons-status ons-status--success'>Ready</span>
      </td>
      <td class="ons-table__cell">
        <form action="#" method="Get">
          <a href="#0" role="button" class="ons-btn ons-btn--small ons-btn--secondary ons-btn--link ons-js-submit-btn">
            <span class="ons-btn__inner"><span class="ons-btn__text">View details</span><svg
                class="ons-icon ons-u-ml-2xs" viewBox="0 0 17 13" xmlns="http://www.w3.org/2000/svg" focusable="false"
                fill="currentColor" role="img" title="ons-icon-arrow-next">
                <path
                  d="m10 .2-.9.9c-.1.1-.1.4 0 .5l4 4H.6c-.2 0-.4.2-.4.4v1.2c0 .2.2.4.4.4h12.5l-3.9 3.7c-.2.2-.2.4 0 .6l.8.9c.2.2.4.2.6 0L16.8 7c.2-.2.2-.4 0-.6L10.7.3c-.3-.2-.5-.2-.7-.1z" />
              </svg></span>
          </a>
        </form>
      </td>
    </tr>
    <tr class="ons-table__row">
      <td class="ons-table__cell"> 112 </td>
      <td class="ons-table__cell"> Annual Inward Foreign Direct Investment Survey </td>
      <td class="ons-table__cell"> AIFDI </td>
      <td class="ons-table__cell"> Statistics of Trade Act 1947 </td>
      <td class="ons-table__cell" data-sort-value="12"> Annually </td>
      <td class="ons-table__cell" data-sort-value="2018-02-26"> 26 Feb 2018 </td>
      <td class="ons-table__cell" data-sort-value="1">
        <span class='ons-status ons-status--dead'>Not ready</span>
      </td>
      <td class="ons-table__cell">
        <form action="#" method="Get">
          <a href="#0" role="button" class="ons-btn ons-btn--small ons-btn--secondary ons-btn--link ons-js-submit-btn">
            <span class="ons-btn__inner"><span class="ons-btn__text">View details</span><svg
                class="ons-icon ons-u-ml-2xs" viewBox="0 0 17 13" xmlns="http://www.w3.org/2000/svg" focusable="false"
                fill="currentColor" role="img" title="ons-icon-arrow-next">
                <path
                  d="m10 .2-.9.9c-.1.1-.1.4 0 .5l4 4H.6c-.2 0-.4.2-.4.4v1.2c0 .2.2.4.4.4h12.5l-3.9 3.7c-.2.2-.2.4 0 .6l.8.9c.2.2.4.2.6 0L16.8 7c.2-.2.2-.4 0-.6L10.7.3c-.3-.2-.5-.2-.7-.1z" />
              </svg></span>
          </a>
        </form>
      </td>
    </tr>
    <tr class="ons-table__row">
      <td class="ons-table__cell"> 332 </td>
      <td class="ons-table__cell"> Business Register and Employment Survey </td>
      <td class="ons-table__cell"> BRES </td>
      <td class="ons-table__cell"> Statistics of Trade Act 1947 </td>
      <td class="ons-table__cell" data-sort-value="12"> Annually </td>
      <td class="ons-table__cell" data-sort-value="2013-01-23"> 23 Jan 2013 </td>
      <td class="ons-table__cell" data-sort-value="2">
        <span class='ons-status ons-status--info'>In progress</span>
      </td>
      <td class="ons-table__cell">
        <form action="#" method="Get">
          <a href="#0" role="button" class="ons-btn ons-btn--small ons-btn--secondary ons-btn--link ons-js-submit-btn">
            <span class="ons-btn__inner"><span class="ons-btn__text">View details</span><svg
                class="ons-icon ons-u-ml-2xs" viewBox="0 0 17 13" xmlns="http://www.w3.org/2000/svg" focusable="false"
                fill="currentColor" role="img" title="ons-icon-arrow-next">
                <path
                  d="m10 .2-.9.9c-.1.1-.1.4 0 .5l4 4H.6c-.2 0-.4.2-.4.4v1.2c0 .2.2.4.4.4h12.5l-3.9 3.7c-.2.2-.2.4 0 .6l.8.9c.2.2.4.2.6 0L16.8 7c.2-.2.2-.4 0-.6L10.7.3c-.3-.2-.5-.2-.7-.1z" />
              </svg></span>
          </a>
        </form>
      </td>
    </tr>
    <tr class="ons-table__row">
      <td class="ons-table__cell"> 654 </td>
      <td class="ons-table__cell"> Quartely Survey of Building Materials Sand and Gravel </td>
      <td class="ons-table__cell"> QBMS </td>
      <td class="ons-table__cell"> Statistics of Trade Act 1947 - BEIS </td>
      <td class="ons-table__cell" data-sort-value="3"> Quartely </td>
      <td class="ons-table__cell" data-sort-value="2015-01-24"> 24 Jan 2015 </td>
      <td class="ons-table__cell" data-sort-value="3">
        <span class='ons-status ons-status--error'>Issue</span>
      </td>
      <td class="ons-table__cell">
        <form action="#" method="Get">
          <a href="#0" role="button" class="ons-btn ons-btn--small ons-btn--secondary ons-btn--link ons-js-submit-btn">
            <span class="ons-btn__inner"><span class="ons-btn__text">View details</span><svg
                class="ons-icon ons-u-ml-2xs" viewBox="0 0 17 13" xmlns="http://www.w3.org/2000/svg" focusable="false"
                fill="currentColor" role="img" title="ons-icon-arrow-next">
                <path
                  d="m10 .2-.9.9c-.1.1-.1.4 0 .5l4 4H.6c-.2 0-.4.2-.4.4v1.2c0 .2.2.4.4.4h12.5l-3.9 3.7c-.2.2-.2.4 0 .6l.8.9c.2.2.4.2.6 0L16.8 7c.2-.2.2-.4 0-.6L10.7.3c-.3-.2-.5-.2-.7-.1z" />
              </svg></span>
          </a>
        </form>
      </td>
    </tr>
    <tr class="ons-table__row">
      <td class="ons-table__cell"> 765 </td>
      <td class="ons-table__cell"> Monthly Survey of Building Materials Concrete Building Blocks </td>
      <td class="ons-table__cell"> MSBB </td>
      <td class="ons-table__cell"> Voluntary </td>
      <td class="ons-table__cell" data-sort-value="1"> Monthly </td>
      <td class="ons-table__cell" data-sort-value="2014-01-25"> 25 Jan 2014 </td>
      <td class="ons-table__cell" data-sort-value="0">
        <span class='ons-status ons-status--success'>Ready</span>
      </td>
      <td class="ons-table__cell">
        <form action="#" method="Get">
          <a href="#0" role="button" class="ons-btn ons-btn--small ons-btn--secondary ons-btn--link ons-js-submit-btn">
            <span class="ons-btn__inner"><span class="ons-btn__text">View details</span><svg
                class="ons-icon ons-u-ml-2xs" viewBox="0 0 17 13" xmlns="http://www.w3.org/2000/svg" focusable="false"
                fill="currentColor" role="img" title="ons-icon-arrow-next">
                <path
                  d="m10 .2-.9.9c-.1.1-.1.4 0 .5l4 4H.6c-.2 0-.4.2-.4.4v1.2c0 .2.2.4.4.4h12.5l-3.9 3.7c-.2.2-.2.4 0 .6l.8.9c.2.2.4.2.6 0L16.8 7c.2-.2.2-.4 0-.6L10.7.3c-.3-.2-.5-.2-.7-.1z" />
              </svg></span>
          </a>
        </form>
      </td>
    </tr>
  </tbody>
</table>

Help improve this page

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

Cookies on ons.gov.uk

Table

Overview

Basic table

Example Table Basic contents

Nunjucks

Nunjucks macro options

HTML

When to use this component

When not to use this component

Variants

Table with footer

Example Table Footer contents

Nunjucks

Nunjucks macro options

HTML

Compact table

Example Table Compact contents

Nunjucks

Nunjucks macro options

HTML

Numeric table

Example Table Numeric contents

Nunjucks

Nunjucks macro options

HTML

Responsive table

Example Table Responsive contents

Nunjucks

Nunjucks macro options

HTML

Scrollable table

Example Table Scrollable contents

Nunjucks

Nunjucks macro options

HTML

Sortable table

Example Table Sortable contents

Nunjucks

Nunjucks macro options

HTML

Help improve this page