WAI-ARIA: aria-errormessage (Property)

Description

New in ARIA 1.1

Identifies the element that provides an error message for the object. See related aria-invalid and aria-describedby.

The aria-errormessage attribute references another element that contains custom error message text. Authors MUST use aria-invalid in conjunction with aria-errormessage. Initially, the object is in a valid state and either has an aria-invalid set to false or no aria-invalid attribute, and the element referenced by aria-errormessage is not applicable. If the user enters an invalid value for the object, aria-invalid is set to true to indicate that aria-errormessage is now pertinent. When aria-errormessage is pertinent, authors MUST ensure the content is not hidden and is included in a container that exposes the content to the user as it is expected that the assistive technology user will navigate to the content in order to access it.

Authors MAY use live regions for the error message element applying either an aria-live property or using one of the live region roles, for example, alert. A live region scenario is when an error message is displayed to users only after they have provided invalid information. The message describes what is wrong and advises users as to what is required. For example, an error message might be, “Invalid time: the time must be between 9:00 AM and 5:00 PM”.

Screen Reader Support for aria-errormessage

Expectation	JAWS			Narrator	NVDA			Orca	TalkBack	VoiceOver (iOS)	VoiceOver (macOS)
	Chrome	Edge	Firefox	Edge	Chrome	Edge	Firefox	Firefox	Chrome	Safari	Safari
MUST convey that the referenced error message is pertinent	partial	supported	partial	none	none	none	none	supported	none	none	none
MUST NOT convey the error when the error message is NOT pertinent	supported	supported	supported	supported	supported	supported	supported	supported	supported	supported	supported

aria-errormessage Example

The following example shows the markup for the initial valid state and for the subsequent invalid state. Note the changes to aria-invalid on the text input object, and to aria-live on the element containing the text of the error message:

Initial valid state

<label for="startTime"> Please enter a start time for the meeting: </label>
<input id="startTime" type="text" aria-errormessage="msgID" value="" aria-invalid="false">
<span id="msgID" aria-live="off" style="visibility:hidden"> Invalid time: the time must be between 9:00 AM and 5:00 PM" </span>

User has input an invalid value

<label for="startTime"> Please enter a start time for the meeting: </label>
<input id="startTime" type="text" aria-errormessage="msgID" aria-invalid="true" value="11:30 PM" >
<span id="msgID" aria-live="assertive" style="visibility:visible"> Invalid time: the time must be between 9:00 AM and 5:00 PM" </span>

Characteristics

Used in Roles

All elements of the base markup

Value

ID reference
Reference to the ID of another element in the same document

Semantic HTML

No HTML element equivalent.

The aria-errormessage attribute takes an ID reference in the same manner as aria-describedby, and is only exposed when aria-invalid is set to ‘true’ on the same element. The use of a live region attribute such as aria-live=”polite” on the error message container element is optional.

Reference

• W3C (opens new window)
• A11Y Support