English
Site menu

invalid-field-error-message

Fields marked invalid should have a shown error message

automaticWCAG 3.3.1 (A)confidence: highseverity: seriousunderstandable

Checks that an element with aria-invalid has an error message in text: its aria-errormessage should name a shown element with text, and a field with no linked message is asked about.

Applies to. Elements the page shows, in the accessibility tree and not disabled, whose aria-invalid says they are invalid: true, or a value ARIA reads as true (anything but false, grammar, spelling or empty). grammar and spelling mark text, not a value a user entered.

Expectation. The error is identified and described to the user in text (WCAG 3.3.1).

  • aria-errormessage names an element that is shown and has text: pass.
  • aria-errormessage names only elements that are hidden (ERROR_MESSAGE_HIDDEN): cantTell, leaning fail. ARIA requires the message to be shown while the field is invalid, and the page states it isn't; but, as for an empty message, the error may still be told in the label or next to the field, which meets 3.3.1.
  • aria-errormessage names only shown elements with no text (ERROR_MESSAGE_EMPTY): cantTell. ARIA sets no MUST on the message's text, and the error may be told in the label or next to the field, which meets 3.3.1. When the field's aria-describedby gives a description, the error may be there: cantTell (ERROR_MESSAGE_NOT_SHOWN_DESCRIBED).
  • aria-errormessage names no element of the page: cantTell (ERROR_MESSAGE_TARGET_MISSING); a script may add it.
  • No aria-errormessage, and aria-describedby gives a description: pass.
  • Neither: cantTell (NO_ERROR_MESSAGE). The error may be in the label or in text next to the field, which the markup doesn't tie to it; check that the user is told, in text, which field is in error and what is wrong.
  • aria-errormessage names a message that is aria-hidden itself or inside an aria-hidden element: cantTell, leaning fail (ERROR_MESSAGE_HIDDEN, with hiddenBy: 'aria-hidden'). ARIA counts such an element as hidden, and requires a pertinent error message not to be.
  • aria-errormessage names a shown message all of whose text is inside aria-hidden elements, while the message itself is not: cantTell (ERROR_MESSAGE_ARIA_HIDDEN). People who see it are told; screen reader users may not be.

An element counts as hidden when nobody sees it: display: none, visibility: hidden, hidden, a closed <details> or content-visibility: hidden on it or an ancestor; a message hidden with visibility: hidden whose text is brought back with visibility: visible is shown. Text is what the accessible name computation reads: an image's alt counts, and text hidden inside the message doesn't. The message may be named by id or set from script as an element (ariaErrorMessageElements).

What a finding reports.

  • ariaInvalid: the attribute's value.
  • hiddenBy (ERROR_MESSAGE_HIDDEN): aria-hidden when only aria-hidden hides the message; absent when nobody sees it.
  • errorMessageIds: the ids aria-errormessage names, or [] for none.

These data.details fields help to read and reproduce a finding. Apart from reasonCode and the few fields Output schema names as stable, they are not a stable contract: a field may be renamed or dropped in a minor release, so don’t build on them.

Examples

pass
<label for="email">Email</label>
<input id="email" aria-invalid="true" aria-errormessage="email-error">
<p id="email-error">Enter an email address, like name@example.com.</p>

The field is marked invalid, and the message aria-errormessage names is shown and says what is wrong.

can't tell
<label for="email">Email</label>
<input id="email" aria-invalid="true" aria-errormessage="email-error">
<p id="email-error" hidden>Enter an email address, like name@example.com.</p>

The field is marked invalid, but its error message is hidden. It leans fail: the message tied to the field can't be seen or heard, though the error may still be told in the label or next to the field.

can't tell
<label for="age">Age</label>
<input id="age" aria-invalid="true">
<p>Age must be a number.</p>

No message is tied to the field. The text next to it may describe the error; a person checks that the user is told, in text, which field is in error and why.

How to check

When this rule can’t decide, it reports cantTell and leaves the question to a person. Each question it can ask is listed here under its reason code, with the steps to answer it. A finding carries the same steps as howToCheck, in the scan’s language. See Output schema.

ERROR_MESSAGE_ARIA_HIDDEN

  1. Find the field the report names and confirm its error message is visible on screen.
  2. Inspect the message element that aria-errormessage points to and note which of its children carry aria-hidden="true".
  3. Focus the field with a screen reader running, or read its error message and description in the Accessibility pane.
  4. Note whether the error's words reach the screen reader through any route.

Pass. A screen reader user is told the same error text that is shown on screen, for example through the field's description or label.

Fail. The error is visible but hidden from assistive technology, so screen reader users are not told what is wrong, which fails WCAG 3.3.1.

ERROR_MESSAGE_EMPTY

  1. Find the field the report names and trigger its error state (submit the form or enter an invalid value) if it is not already shown.
  2. Inspect the field and find the element its aria-errormessage attribute points to; confirm it is empty.
  3. Look at the field's label and the text next to it for words that say which field is in error and what is wrong.
  4. Focus the field with a screen reader running, or check its name and description in the Accessibility pane, and note whether the error is conveyed.

Pass. Text on the page, such as the label or a message next to the field, says which field is in error and what is wrong.

Fail. No text tells the user which field is in error or what is wrong, which fails WCAG 3.3.1.

ERROR_MESSAGE_HIDDEN

  1. Make the field invalid the way a user would (submit the form empty, or type a wrong value).
  2. Look for the error message the field points to (its aria-errormessage), and check whether it appears on screen.
  3. If it doesn't, look for any text that tells you what is wrong: in the label, next to the field, or in a summary at the top of the form.
  4. With a screen reader, move to the field and listen for the error.

Pass. The error is shown in text, and announced, somewhere tied to the field, even if not in the message aria-errormessage names.

Fail. No text tells you which field is wrong and why, or a screen reader user isn't told, which fails WCAG 3.3.1.

ERROR_MESSAGE_NOT_SHOWN_DESCRIBED

  1. Find the field the report names and trigger its error state if it is not already shown.
  2. Open the Accessibility pane for the field and read its description (from aria-describedby).
  3. Compare that description with the error: decide whether it says what is wrong, or is only hint text such as an input format.
  4. Check that the same error text is visible on screen near the field.

Pass. The field's description, or other visible text, states the error in words, so both sighted and screen reader users learn what is wrong.

Fail. The description is only hint text and no visible text describes the error, which fails WCAG 3.3.1.

ERROR_MESSAGE_TARGET_MISSING

  1. Find the field the report names and note the id in its aria-errormessage attribute.
  2. Trigger the error (submit the form or enter an invalid value) and search the Elements panel for an element with that id.
  3. If the element appears, check that it is shown and has text that describes the error.
  4. If it never appears, look for other visible text near the field or in its label that says what is wrong.

Pass. Once the field is in error, a shown message with that id, or other visible text, describes the error.

Fail. The field is marked invalid but no text describes the error, which fails WCAG 3.3.1.

NO_ERROR_MESSAGE

  1. Find the field the report names; it is marked aria-invalid.
  2. Check whether the field is really in error now; if it is marked invalid before the user has entered anything, enter a valid value and see whether the mark clears.
  3. Look at the field's label and the text next to it, and any error summary on the page, for words naming this field and saying what is wrong.
  4. Focus the field with a screen reader running and note whether the error is announced.

Pass. Visible text identifies the field in error and describes what is wrong, or the field is not actually in error.

Fail. The field is in error but no text identifies it and describes the problem, which fails WCAG 3.3.1.

View source