Using the aria-invalid attribute

Description

The aria-invalid attribute is used to indicate that the value entered into an input field does not conform to the format expected by the application.This may include formats such as email addresses or telephone numbers. aria-invalid can also be used to indicate that a required field has not been filled in.The attribute should be programmatically set as a result of a validation process.

This attribute can be used with any typical HTML form element; it is not limited to elements that have an ARIA role assigned.

Values

Vocabulary:

false

(default) No errors detected

grammar

A grammatical error has been detected.

spelling

A spelling error has been detected.

true

The value has failed validation.

Any value not in this vocabulary should be treated as true.

Possible effects on user agents and assistive technology 

User agents should inform the user when a field is invalid. Application authors should provide suggestions for correcting the problem, if possible. Authors may prevent a form from being submitted.

Examples

Example 1: Simple form validation

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-required is false, it is not strictly necessary to add the attribute to input.

 <input name="name" id="name" aria-required="true" aria-invalid="false"
        onblur="checkValidity('name', ' ', 'Invalid name entered (requires both first and last name)');"/>
 <br />
 <input name="email" id="email" aria-required="true" aria-invalid="false"
         onblur="checkValidity('email', '@', 'Invalid e-mail address');"/>

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(aID, aSearchTerm, aMsg){
    var elem = document.getElementById(aID);
    var invalid = (elem.value.indexOf(aSearchTerm) < 0);
    if (invalid) {
        elem.setAttribute("aria-invalid", "true");
        updateAlert(aMsg);
    } else {
        elem.setAttribute("aria-invalid", "false");
        updateAlert();
    }
}

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

function updateAlert(msg) {
    var oldAlert = document.getElementById("alert");
    if (oldAlert) {
        document.body.removeChild(oldAlert);
    }

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

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

Working Examples:

Alert role example (uses the aria-invalid attribute)

Notes 

• When aria-invalid is used in conjunction with the aria-required attribute, aria-invalid should not be set to true before the form is submitted - only in response to validation.
• Future expansion may add terms to the vocabulary used for this attribute. Any value not in the current vocabulary should be treated as true.

Used in ARIA roles

all elements of the base markup

Related ARIA techniques 

• Using the aria-required attribute
• Using the alert role

Compatibility

TBD: Add support information for common UA and AT product combinations

Additional resources

• WAI-ARIA specification for the aria-invalid property
• WAI Authoring Practices for forms