aria-invalid

The aria-invalid attribute is used to indicate that the value entered into an input field is not in a format or a value the application will accept. This may include formats such as email addresses or telephone numbers. aria-invalid can also be used to indicate that a required field is empty.

The aria-invalid attribute can be used with any typical HTML form element, and is not limited to elements that have an ARIA role assigned.

The attribute should be set with JavaScript as a result of a validation process. If a value is determined to be invalid or out-of-range, set aria-invalid="true" and tell the user there is an error. For better user experience, provide suggestions for how the error can be corrected. Do not set aria-invalid="true" on empty required elements until after the user attempts to submit the form. They may still be working on filling it out.

There are currently four values: in addition to true and false we have grammar which can be used when a grammatical error is detected and spelling for spelling errors. If the attribute is not present, or its value is false, or its value is an empty string, the default value of false applies. Any other value is treated as if true were set.

HTML has native form validation. When a user submits a form with a control containing errors, the first form control with an invalid value displays an error message, natively.

If there is a required attribute on a form control that isn't filled out, the form will not submit, and an error message appears reading "Please fill out this field" or something similar. The messaging for native validation varies depending on the browser, and cannot be styled.

<input type="number" step="2" min="0" max="100" required />

If the user had entered a value in the preceding input example above the maximum, below the minimum, or that doesn't match the step value, an error message would appear. If the user had entered "3", the native error message would be similar to "Please enter a valid value."

If you are creating your own form validation scripts, make sure to include aria-invalid on invalid form controls, along with styling (use the [aria-invalid="true"] attribute selector) and messaging (with aria-errormessage) to help users understand where the mistake is and how they can fix it.

grammar

A grammatical error was detected.

false (default)

There are no detected errors in the value.

spelling

A spelling error was detected.

true

The value entered by the user has failed validation.

Any value not in this list will be treated as true.

The following snippet shows a simplified version of two form fields with a validation function attached to the blur event. Note that since the default value for aria-invalid is false, it is not strictly necessary to add the attribute to input.

<ul>
  <li>
    <label for="name">Full Name</label>
    <input
      type="text"
      name="name"
      id="name"
      aria-required="true"
      aria-invalid="false"
      onblur="checkValidity('name', ' ', 'Invalid name entered (requires both first and last name)');" />
  </li>
  <li>
    <label for="email">Email Address</label>
    <input
      type="email"
      name="email"
      id="email"
      aria-required="true"
      aria-invalid="false"
      onblur="checkValidity('email', '@', 'Invalid email address');" />
  </li>
</ul>

Note that it is not necessary to validate the fields immediately on blur; the application could wait until the form is submitted (though this is not necessarily recommended).

The snippet below shows a very simple validation function, which only checks for the presence of a particular character (in the real world, validation will likely be more sophisticated):

function checkValidity(id, searchTerm, msg) {
  const elem = document.getElementById(id);
  if (elem.value.includes(searchTerm)) {
    elem.setAttribute("aria-invalid", "false");
    updateAlert();
  } else {
    elem.setAttribute("aria-invalid", "true");
    updateAlert(msg);
  }
}

The snippet below shows the alert functions, which add (or remove) the error message:

function updateAlert(msg) {
  const oldAlert = document.getElementById("alert");
  if (oldAlert) {
    oldAlert.remove();
  }

  if (msg) {
    const newAlert = document.createElement("div");
    newAlert.setAttribute("role", "alert");
    newAlert.setAttribute("id", "alert");
    const content = document.createTextNode(msg);
    newAlert.appendChild(content);
    document.body.appendChild(newAlert);
  }
}

Note that the alert has the ARIA role attribute set to alert.

Used in roles:

• application
• checkbox
• combobox
• gridcell
• listbox
• radiogroup
• slider
• spinbutton
• textbox
• tree

Inherited into role:

• columnheader
• rowheader
• searchbox
• switch
• treegrid

• aria-errormessage
• CSS :valid pseudoclass
• CSS :invalid pseudoclass
• Form Validation tutorial