DFE-Digital/govuk-components

---
title: Table
---

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

== render('/partials/example.*',
  caption: "Building a table row by row",
  code: table_normal) do

  markdown:
    Tables can be declared similarly to how they'd be built in HTML, by
    declaring the caption, head, body, rows and cells.

    Tables can have one caption which should be used to describe the contents
    of the table.

    The head and body are created using the `head` and `body` slots and can
    each contain one or more `row` elements. Each row can contain multiple
    `cell` elements.

    By default `cell` will create a `<td>` element. When `header: true` is
    passed in it will create a `<th>`. Cells values can be set using the
    `text:` argument or by passing in a block of HTML.

== render('/partials/example.*',
  caption: "Tables with header columns",
  code: table_with_header_column) do

  markdown:
    To make a column of headers, pass `header: true` to the first cell on each
    row in the `body`.

== render('/partials/example.*',
  caption: "Building a table from arrays",
  code: table_from_arrays,
  data: table_data) do

  markdown:
    If you want to build a table without advanced options, you can pass in an
    array of arrays via the `rows` argument. Each element in the outer array
    represents a `row` and each element in the inner array represents a
    `cell`.

    You can set the header columns explicitly by passing an array of headers
    using the `head` argument. If nothing is set, the first row will be used for
    headers.

    The `first_cell_is_header` parameter can be used to change the first column
    in the table body to header cells with `scope='row'`.

    An optional `foot` parameter can be used to render a [table
    footer](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/tfoot).
    Footers are usually used provide a summary of the table's contents. They
    are not part of the GOV.UK Design System so custom styles will be required.

== render('/partials/example.*',
  caption: "Table with resized columns",
  code: table_with_resized_columns) do

  markdown:
    By default the table will automatically size the columns to avoid wrapping.
    This can make tables with lots of data feel cramped.

    We can avoid this by setting the width of cells. We only need to set it
    once per column and usually this is set in the `head` section.

    The options available are `one-quarter`, `one-third`, `one-half`,
    `two-thirds`, `three-quarters` and `full`.

== render('/partials/example.*',
  caption: "Complex tables",
  code: table_complex) do

  markdown:
    Sometimes we need to build tables that have more two dimensions. To make
    these tables accessible we can use `<colgroup>` and `<col>` elements to
    describe the groups of columns, and we can add extra table headers with
    scopes to describe each axis.

    Columns can be made to stretch across multiple rows with the `rowspan` and
    columns with the `colspan` parameters.

== render('/partials/related-navigation.*', links: table_info)