Do not code lists as tables

Using tables instead of definition lists creates noise for screen reader users.

Typical example that causes barriers

This example can happen when showing information about a user that they need to check.

Example
HTML
Nunjucks

<span class="govuk-caption-l">Original version</span>
<table class="govuk-table">
  <caption class="govuk-table__caption govuk-table__caption--l">Check previous details</caption>
  <tbody class="govuk-table__body">
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">Name</td>
      <td class="govuk-table__cell">Sarah Philips</td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">Date of birth</td>
      <td class="govuk-table__cell">5 January 1978</td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">Address</td>
      <td class="govuk-table__cell">72 Guild Street<br>London<br>SE23 6FH</td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">Contact details</td>
      <td class="govuk-table__cell">
        <p class="govuk-body">07700 900457</p>
        <p class="govuk-body">sarah.phillips@example.com</p>
      </td>
    </tr>
  </tbody>
</table>
<div class="govuk-form-group">
  <fieldset class="govuk-fieldset">
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--m">
      Are these details correct?
    </legend>
    <div class="govuk-radios" data-module="govuk-radios">
      <div class="govuk-radios__item">
        <input class="govuk-radios__input" id="details" name="details" type="radio" value="">
        <label class="govuk-label govuk-radios__label" for="details">
          Yes
        </label>
      </div>
      <div class="govuk-radios__item">
        <input class="govuk-radios__input" id="details-2" name="details" type="radio" value="">
        <label class="govuk-label govuk-radios__label" for="details-2">
          No
        </label>
      </div>
    </div>
  </fieldset>
</div>
<button type="submit" class="govuk-button" data-module="govuk-button">
  Save and continue
</button>

<span class="govuk-caption-l">Original version</span>

{{ govukTable({
  caption: "Check previous details",
  captionClasses: "govuk-table__caption--l",
  rows: [
    [
      {
        text: "Name"
      },
      {
        text: "Sarah Philips"
      }
    ],
    [
      {
        text: "Date of birth"
      },
      {
        text: "5 January 1978"
      }
    ],
    [
      {
        text: "Address"
      },
      {
        html: "72 Guild Street<br>London<br>SE23 6FH"
      }
    ],
    [
      {
        text: "Contact details"
      },
      {
        html: '<p class="govuk-body">07700 900457</p><p class="govuk-body">sarah.phillips@example.com</p>'
      }
    ]
  ]
}) }}

{{ govukRadios({
  fieldset: {
    legend: {
      classes: "govuk-fieldset__legend--m",
      text: "Are these details correct?"
    }
  },
  name: "details",
  items: [
    {
      text: "Yes"
    },
    {
      text: "No"
    }
  ]
}) }}

{{ govukButton({
  text: "Save and continue"
}) }}

This is coded as a table rather than a definition list. Tables are far more ‘noisy’ for screen reader users as they read out row and columns. The table caption doubling as a page title can also confuse sighted screen reader users.

<span class="govuk-caption-l">Improved version</span>
<h1 class="govuk-heading-l">
  Check previous details
</h1>
<dl class="govuk-summary-list">
  <div class="govuk-summary-list__row">
    <dt class="govuk-summary-list__key">
      Name
    </dt>
    <dd class="govuk-summary-list__value">
      Sarah Philips
    </dd>
  </div>
  <div class="govuk-summary-list__row">
    <dt class="govuk-summary-list__key">
      Date of birth
    </dt>
    <dd class="govuk-summary-list__value">
      5 January 1978
    </dd>
  </div>
  <div class="govuk-summary-list__row">
    <dt class="govuk-summary-list__key">
      Address
    </dt>
    <dd class="govuk-summary-list__value">
      72 Guild Street<br>London<br>SE23 6FH
    </dd>
  </div>
  <div class="govuk-summary-list__row">
    <dt class="govuk-summary-list__key">
      Contact details
    </dt>
    <dd class="govuk-summary-list__value">
      <p class="govuk-body">07700 900457</p>
      <p class="govuk-body">sarah.phillips@example.com</p>
    </dd>
  </div>
</dl>
<div class="govuk-form-group">
  <fieldset class="govuk-fieldset">
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--m">
      Are these details correct?
    </legend>
    <div class="govuk-radios" data-module="govuk-radios">
      <div class="govuk-radios__item">
        <input class="govuk-radios__input" id="details" name="details" type="radio" value="">
        <label class="govuk-label govuk-radios__label" for="details">
          Yes
        </label>
      </div>
      <div class="govuk-radios__item">
        <input class="govuk-radios__input" id="details-2" name="details" type="radio" value="">
        <label class="govuk-label govuk-radios__label" for="details-2">
          No
        </label>
      </div>
    </div>
  </fieldset>
</div>
<button type="submit" class="govuk-button" data-module="govuk-button">
  Save and continue
</button>

<span class="govuk-caption-l">Improved version</span>

<h1 class="govuk-heading-l">
  Check previous details
</h1>

{{ govukSummaryList({
  rows: [{
    key: {
      text: "Name"
    },
    value: {
      text: "Sarah Philips"
    }
  }, {
    key: {
      text: "Date of birth"
    },
    value: {
      text: "5 January 1978"
    }
  }, {
    key: {
      text: "Address"
    },
    value: {
      html: "72 Guild Street<br>London<br>SE23 6FH"
    }
  }, {
    key: {
      text: "Contact details"
    },
    value: {
      html: '<p class="govuk-body">07700 900457</p><p class="govuk-body">sarah.phillips@example.com</p>'
    }
  }]
}) }}

{{ govukRadios({
  fieldset: {
    legend: {
      classes: "govuk-fieldset__legend--m",
      text: "Are these details correct?"
    }
  },
  name: "details",
  items: [
    {
      text: "Yes"
    },
    {
      text: "No"
    }
  ]
}) }}

{{ govukButton({
  text: "Save and continue"
}) }}

Using a definition list means that what is visually shown on the page is more aligned with what is read out on a screen reader.

Do not code lists as tables

Typical example that causes barriers

Contents

Improved version

Contents