Code examples
Adding hint/help text
<label for="best-letter">
The best NATO letter is:
</label>
<input type="text"
id="best-letter"
aria-describedby="best-letter-hint">
<div class="hint" id="best-letter-hint">
Example: Alpha, Bravo, Charlie
</div>
Example: Alpha, Bravo, Charlie
Adding an error
Note: The alert must be structured as below to function properly in VoiceOver, with the alert text nested inside the role="alert"
element.
<label for="favorite-letter">
What is your favorite NATO letter?
<span>Required</span>
</label>
<input type="text"
id="favorite-letter"
aria-describedby="favorite-error favorite-hint"
required>
<div role="alert" class="alert inert">
<!--- Do not reference this alert element
directly with aria-describedby -->
<div id="favorite-error">
<!--- Use JS to inject the alert here -->
</div>
</div>
<div class="hint" id="favorite-hint">
Example: Alpha, Bravo, Charlie
</div>
<button id="show-error">
Toggle error
</button>
Example: Alpha, Bravo, Charlie
Developer notes
Browser + screenreader quirks
- Screenreaders do not implement alerts uniformly and must be tested
- Just because an alert pattern works in one screenreader doesn’t mean it will work in all three
- The element referenced by the
aria-describedby
attribute cannot use therole="alert"
attribute (see example above for workaround). - NVDA will read the alert twice if it appears while the input is in focus: once from the
role="alert"
being injected and from thearia-describedby
association. - NVDA needs a fraction of a second to catch up with changes in the DOM, use a
setTimeout
to delay displaying the alert
Name
- Inner text describes the hint
Role
- May have
role="alert"
if serving as an input error message
Group
- Use
aria-describedby="hint-id"
to associate an input with a hint.
Focus
- Hints should not receive focus