Accessible form error messages: identify, explain, help users fix

What accessible form error messages require (WCAG 3.3.1)

Success Criterion 3.3.1 Error Identification applies when an input error is automatically detected: the item in error must be identified and the error described to the user in text. The W3C states the goal plainly: users know an error exists and what is wrong.

The W3C notably cites two cases of input error: information the page requires but the user left out, and information the user provided that falls outside the required data format or allowed values. Its examples are concrete: an incorrect state, province or region abbreviation, a non-existent zip or postal code, a birth date two years in the future, letters or parentheses typed into a phone field that only accepts numbers, or a bid below the previous bid.

An often-missed case: if the page automatically changes a value that is too high or too low so it falls within the allowed range, the error still has to be described to the user. A message telling the person about the changed value meets both 3.3.1 and 3.3.3.

Color, an icon or an image are fine, but only in addition to the text. The criterion does not mandate a location either: a list of errors at the top of the form, inline messages next to each field, an alert or a dialog. The only requirement is that errors are presented in text or a text alternative.

• Name the field in error in the message (for example "Email address").
• Describe the nature of the error: empty required field, wrong format, value not in the list.
• Never rely on red color or an icon alone.
• Also report automatic corrections made by the page.

Suggesting a fix: Success Criterion 3.3.3

Success Criterion 3.3.3 Error Suggestion (Level AA) goes further: if an input error is automatically detected and suggestions for correction are known, they must be provided to the user, unless that would jeopardize the security or purpose of the content. The W3C points out that knowing an error exists is not always enough: people with cognitive limitations may find it hard to work out how to fix it, and a user who is unsure may abandon the form.

The W3C's wording example for 3.3.1 and 3.3.3 is a good model. "Email is not valid" passes 3.3.1. "Please provide a valid email address in the format [email protected]" also explains how to fix it, and passes both criteria.

Another example from the documentation: a field expects a month name and the user types "12". The correction can be a list of acceptable values ("Choose one of: January, February… December") or an interpretation of the input ("Do you mean 'December'?"). The W3C also describes a form that was not submitted successfully and shows the error in place, along with the correct input and additional help for the field.

• Expected format: give a concrete example ([email protected], dd/mm/yyyy).
• Closed list: restate the allowed values or offer the most likely one.
• Exception: suggest nothing that would jeopardize the security or purpose of the content.

Preventing errors with labels and instructions (3.3.2)

The best error message is the one you never display. Success Criterion 3.3.2 Labels or Instructions (Level A) requires labels or instructions when content requires user input. "Requires" does not mean required fields only: the criterion applies to all fields, required or optional. It does not apply to links or other controls not associated with data entry, such as an expand/collapse widget.

For radio buttons, checkboxes and comboboxes, each choice needs its own label. If the labels of the choices are enough to convey the purpose of the group, a visible label for the group may not be necessary; otherwise, you need to provide a label, legend or instructions for the whole group. Instructions can specify the expected format, especially when it is unusual or follows specific rules for correct input. The W3C also warns against overdoing it: too much information can be just as harmful as too little. Instructions can appear only when the control has focus, or be reachable through a link, especially when they are long.

Mind the scope: 3.3.2 does not require the label to be correctly marked up and associated with the field; that is covered by 1.3.1. Conversely, a field can have an accessible name through aria-label and pass 4.1.2, yet fail 3.3.2 if the label is presented only to assistive technology users. Whether a label is clear is covered by 2.4.6.

• A date field with the expected format stated in text (dd/mm/yyyy or mm/dd/yyyy).
• A username field with the rules about allowed characters.
• Two fields labeled "Given Name" and "Family Name" instead of a single "Name" label for both.
• A search field whose magnifying glass icon serves as its visible label.

<!-- Associated label (H44), required field stated in the label (H90)
     and expected format with an example (G89) -->
<label for="date-of-birth">Date of birth (required)</label>
<p id="date-of-birth-hint">Expected format: dd/mm/yyyy, for example 14/07/1990</p>
<input type="text" id="date-of-birth" name="date-of-birth"
       aria-describedby="date-of-birth-hint" aria-required="true">

<!-- Group of fields: fieldset and legend (H71),
     with a visible label for each sub-field (H44) -->
<fieldset>
  <legend>Address</legend>
  <label for="postcode">Postcode</label>
  <input type="text" id="postcode" name="postcode">
  <label for="city">City</label>
  <input type="text" id="city" name="city">
</fieldset>

Announcing errors to screen readers: W3C techniques

Success Criterion 3.3.1 does not require programmatic information: text, or a text alternative, that identifies the field and describes the error is enough to satisfy it. The W3C does note that error identification can be combined with information that browsers and assistive technologies can use, which may be covered by other criteria such as 4.1.2 Name, Role, Value. The sufficient techniques listed for 3.3.1, grouped by situation, include ARIA21 "Using aria-invalid to Indicate An Error Field" for required fields left empty, as well as ARIA19 "Using ARIA role=alert or Live Regions to Identify Errors", ARIA18 "Using aria-alertdialog to Identify Errors" and SCR32 "Providing client-side validation and adding error text via the DOM" for input outside the required format or values.

One possible implementation combines a message tied to the field with aria-describedby, an aria-invalid attribute on the field in error and a summary in a role="alert" region. As advisory techniques, the W3C also lists G139 "Creating a mechanism that allows users to jump to errors", which you can build with links to each field in the summary, and G199 "Providing success feedback when data is submitted successfully".

<form id="signup" novalidate>
  <div id="error-summary" role="alert"></div>

  <label for="email">Email address (required)</label>
  <input type="email" id="email" name="email" aria-describedby="email-error">
  <p id="email-error" hidden></p>

  <button type="submit">Create my account</button>
</form>

<script>
  const form = document.getElementById('signup');
  form.addEventListener('submit', (e) => {
    const field = document.getElementById('email');
    const msg = document.getElementById('email-error');
    const summary = document.getElementById('error-summary');
    // Reset before each check
    msg.textContent = '';
    msg.hidden = true;
    summary.innerHTML = '';
    field.removeAttribute('aria-invalid');

    let error = '';
    if (!field.value.trim()) {
      error = 'Email address: this field is required.';
    } else if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(field.value)) {
      error = 'Email address: invalid format. Enter an address in the format [email protected].';
    }
    if (error) {
      e.preventDefault();
      msg.textContent = error;
      msg.hidden = false;
      field.setAttribute('aria-invalid', 'true');
      summary.innerHTML = '<p>1 error: <a href="#email">Email address</a></p>';
    }
  });
</script>

Is native HTML validation enough?

With native HTML validation (required, type="email" and so on), the browser prevents submission of an incomplete or invalid form and shows a generic message. It generally moves focus back to the first field in error, and in most common browser and screen reader combinations, the screen reader announces the error message and the programmatic name of the field. The W3C considers that this meets 3.3.1.

The W3C still lists several drawbacks, and notes that developers need to carefully consider whether native validation is accessibility supported in the WCAG sense.

• Depending on the browser, the message may not be permanent or may fail to scroll with the page.
• Depending on the browser, the message is not magnified when the user zooms: it stays at the size of the browser interface and may be too small to read.
• Default messages are generally generic and may not provide suggestions helpful enough for 3.3.3.
• Only the first error is exposed: the user may have to correct and resubmit the form several times.

Frequently asked questions

Further reading on Conformly

• How to fix a form field without a label in HTML
• RGAA criterion 11.10 on input validation
• RGAA criterion 11.11 on correction suggestions

Sources

This article relies on the official sources listed at the end of the page.

• W3C — Comprendre 3.3.1
• W3C — Comprendre 3.3.3
• W3C — Comprendre 3.3.2