Do not use links in ‘aria-described’ areas like hint text
Code
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 examples that cause barriers
Example 1
This example can happen when a question is 'one thing per page' or if multiple things are on a page.
Contents
<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>
{{ govukRadios({
name: "signIn",
fieldset: {
legend: {
text: "How do you want to sign in?",
isPageHeading: true,
classes: "govuk-fieldset__legend--l"
}
},
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>."
},
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."
}
}
]
}) }}
<button type="submit" class="govuk-button" data-module="govuk-button">
Continue
</button>
</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 screenreader may not read them correctly.
Example 2
Contents
<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</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 <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>
{{ govukRadios({
name: "signIn",
fieldset: {
legend: {
text: "How do you want to sign in?",
isPageHeading: true,
classes: "govuk-fieldset__legend--l"
}
},
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>."
},
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."
}
}
]
}) }}
<button type="submit" class="govuk-button" data-module="govuk-button">
Continue
</button>
</form>
Hints within input fields will not be read by the screenreader
Improved version
Contents
<span class="govuk-caption-xl">
Improved version
</span>
<form class="form" action="/complex-hints/accessible-explanation" method="post">
<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>
{# Templates can include front matter data #}
{{ govukNotificationBanner({
text: "This page was last reviewed on " + (reviewed | date("d LLLL y")) + ".
It needs to be reviewed again on " + (reviewAgain | date("d LLLL y")) + "."
}) if reviewed and reviewAgain }}
{%- from "govuk/components/tag/macro.njk" import govukTag -%}
<span class="govuk-caption-xl">
Improved version
</span>
<form class="form" action="/complex-hints/accessible-explanation" method="post">
<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>
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.