Do not use links in aria-described areas like hint text

Areas of GOV.UK component that use aria-described such as hint text are designed to be a single paragraph of text. Changing this can cause accessibility issues.

Typical example that causes barriers

This example can happen when a question is ‘one thing per page’ or if multiple things are on a page.

Example
HTML
Nunjucks

<form class="govuk-!-width-two-thirds" action="#" method="post">
  <div class="govuk-form-group">
    <fieldset class="govuk-fieldset" aria-describedby="signIn-hint">
      <legend class="govuk-fieldset__legend govuk-fieldset__legend--l">
        <h1 class="govuk-fieldset__heading">
          How do you want to sign in?
        </h1>
      </legend>
      <div id="signIn-hint" class="govuk-hint">
        You’ll need an account to prove your identity and <a class="govuk-link" href="#">complete your Self Assessment</a> if you have not filed a tax return online before</a>.
      </div>
      <div class="govuk-radios" data-module="govuk-radios">
        <div class="govuk-radios__item">
          <input class="govuk-radios__input" id="signIn" name="signIn" type="radio" value="government-gateway" aria-describedby="signIn-item-hint">
          <label class="govuk-label govuk-radios__label" for="signIn">
            Sign in with Government Gateway
          </label>
          <div id="signIn-item-hint" class="govuk-hint govuk-radios__hint">
            You’ll have a user ID if you’ve registered for Self Assessment or filed a tax return online before.
          </div>
        </div>
        <div class="govuk-radios__item">
          <input class="govuk-radios__input" id="signIn-2" name="signIn" type="radio" value="govuk-one-login" aria-describedby="signIn-2-item-hint">
          <label class="govuk-label govuk-radios__label" for="signIn-2">
            Sign in with GOV.UK One Login
          </label>
          <div id="signIn-2-item-hint" class="govuk-hint govuk-radios__hint">
            If you don’t have a GOV.UK One Login, you can create one.
          </div>
        </div>
      </div>
    </fieldset>
  </div>
  <button type="submit" class="govuk-button" data-module="govuk-button">
    Continue
  </button>
</form>

<form class="govuk-!-width-two-thirds" action="#" method="post">
  {{ govukRadios({
    fieldset: {
      legend: {
        classes: "govuk-fieldset__legend--l",
        text: "How do you want to sign in?",
        isPageHeading: true
      }
    },
    hint: {
      html: 'You’ll need an account to prove your identity and <a class="govuk-link" href="#">complete your Self Assessment</a> if you have not filed a tax return online before</a>.'
    },
    name: "signIn",
    items: [
      {
        value: "government-gateway",
        text: "Sign in with Government Gateway",
        hint: {
          text: "You’ll have a user ID if you’ve registered for Self Assessment or filed a tax return online before."
        }
      },
      {
        value: "govuk-one-login",
        text: "Sign in with GOV.UK One Login",
        hint: {
          text: "If you don’t have a GOV.UK One Login, you can create one."
        }
      }
    ]
  }) }}

  {{ govukButton({
    text: "Continue"
  }) }}
</form>

Hints (information between the input legend and the input field) must be simple without complex formatting or links. If extra formatting like lists and links are put in the hint area between an input legend and the input, a screen reader may not read them correctly.

Example
HTML
Nunjucks

<form class="govuk-!-width-two-thirds" action="#" method="post">
  <div class="govuk-form-group">
    <fieldset class="govuk-fieldset" aria-describedby="signIn-hint">
      <legend class="govuk-fieldset__legend govuk-fieldset__legend--l">
        <h1 class="govuk-fieldset__heading">
          How do you want to sign in?
        </h1>
      </legend>
      <div id="signIn-hint" class="govuk-hint">
        You’ll need an account to prove your identity and complete your Self Assessment and not filed a tax return online before&lt;/a&gt;.
      </div>
      <div class="govuk-radios" data-module="govuk-radios">
        <div class="govuk-radios__item">
          <input class="govuk-radios__input" id="signIn" name="signIn" type="radio" value="government-gateway" aria-describedby="signIn-item-hint">
          <label class="govuk-label govuk-radios__label" for="signIn">
            Sign in with Government Gateway
          </label>
          <div id="signIn-item-hint" class="govuk-hint govuk-radios__hint">
            You’ll have a user ID if you’ve registered for Self Assessment or <a class="govuk-link" href="#">filed a tax return online before</a>.
          </div>
        </div>
        <div class="govuk-radios__item">
          <input class="govuk-radios__input" id="signIn-2" name="signIn" type="radio" value="govuk-one-login" aria-describedby="signIn-2-item-hint">
          <label class="govuk-label govuk-radios__label" for="signIn-2">
            Sign in with GOV.UK One Login
          </label>
          <div id="signIn-2-item-hint" class="govuk-hint govuk-radios__hint">
            If you don’t have a GOV.UK One Login, you can create one.
          </div>
        </div>
      </div>
    </fieldset>
  </div>
  <button type="submit" class="govuk-button" data-module="govuk-button">
    Continue
  </button>
</form>

<form class="govuk-!-width-two-thirds" action="#" method="post">
  {{ govukRadios({
    fieldset: {
      legend: {
        classes: "govuk-fieldset__legend--l",
        text: "How do you want to sign in?",
        isPageHeading: true
      }
    },
    hint: {
      text: "You’ll need an account to prove your identity and complete your Self Assessment and not filed a tax return online before</a>."
    },
    name: "signIn",
    items: [
      {
        value: "government-gateway",
        text: "Sign in with Government Gateway",
        hint: {
          html: 'You’ll have a user ID if you’ve registered for Self Assessment or <a class="govuk-link" href="#">filed a tax return online before</a>.'
        }
      },
      {
        value: "govuk-one-login",
        text: "Sign in with GOV.UK One Login",
        hint: {
          text: "If you don’t have a GOV.UK One Login, you can create one."
        }
      }
    ]
  }) }}

  {{ govukButton({
    text: "Continue"
  }) }}
</form>

Hints within input fields will not be read by the screen reader

<form class="govuk-!-width-two-thirds" action="#" method="post">
  <span class="govuk-caption-l">Improved version</span>
  <div class="govuk-form-group">
    <h1 class="govuk-label-wrapper">
      <label class="govuk-label govuk-label--l" for="account-number">
        What is your Self Assessment Unique Taxpayer Reference (UTR)?
      </label>
    </h1>
    <div id="account-number-hint" class="govuk-hint">
      Your UTR can be 10 or 13 digits long. You can find it in your Personal Tax Account, the HMRC app, on tax returns and other documents from HMRC. It might be called ‘reference’, ‘UTR’ or ‘official use’.
    </div>
    <input
      class="govuk-input govuk-input--width-10" id="account-number" name="accountNumber" type="text" spellcheck="false" aria-describedby="account-number-hint" inputmode="numeric">
  </div>
  <p class="govuk-body">
    <a class="govuk-link" href="https://www.gov.uk/find-utr-number">How to find your UTR</a>
  </p>
  <button type="submit" class="govuk-button" data-module="govuk-button">
    Continue
  </button>
</form>

<form class="govuk-!-width-two-thirds" action="#" method="post">
  <span class="govuk-caption-l">Improved version</span>

  {{ govukInput({
    label: {
      classes: "govuk-label--l",
      text: "What is your Self Assessment Unique Taxpayer Reference (UTR)?",
      isPageHeading: true
    },
    hint: {
      text: "Your UTR can be 10 or 13 digits long. You can find it in your Personal Tax Account, the HMRC app, on tax returns and other documents from HMRC. It might be called ‘reference’, ‘UTR’ or ‘official use’."
    },
    classes: "govuk-input--width-10",
    id: "account-number",
    name: "accountNumber",
    inputmode: "numeric",
    spellcheck: false
  }) }}

  <p class="govuk-body">
    <a class="govuk-link" href="https://www.gov.uk/find-utr-number">How to find your UTR</a>
  </p>

  {{ govukButton({
    text: "Continue"
  }) }}
</form>

Simple hints will be read out as expected by screen readers. If the input needs significant guidance and links, it should be rewritten as a complex question.

Do not use links in aria-described areas like hint text

Typical example that causes barriers

Contents

Contents

Improved version

Contents