Demystifying WAI-ARIA
16 WAI-ARIA attributes for average web developers

Defines a string value that labels the current element. The purpose of aria-label is the same as that of aria-labelledby. It provides the user with a recognizable name of the object. The most common accessibility API mapping for a label is the accessible name property. If the label text is visible on screen, authors SHOULD use aria-labelledby and SHOULD NOT use aria-label.

For more details, see aria-label in the spec

Identifies the element (or elements) that labels the current element. See related aria-describedby.

The purpose of aria-labelledby is the same as that of aria-label. It provides the user with a recognizable name of the object. Maps to accessible name property.

If the interface is such that it is not possible to have a visible label on the screen, authors SHOULD use aria-label and SHOULD NOT use aria-labelledby. As required by the text alternative computation, user agents give precedence to aria-labelledby over aria-label when computing the accessible name property.

The aria-labelledby attribute is similar to aria-describedby in that both reference other elements to calculate a text alternative, but a label should be concise, where a description is intended to provide more verbose information.

Identifies the element (or elements) that describes the object. See related aria-labelledby.

The aria-labelledby attribute is similar to the aria-describedby in that both reference other elements to calculate a text alternative, but a label should be concise, where a description is intended to provide more verbose information.

The element or elements referenced by the aria-describedby comprise the entire description. Include ID references to multiple elements if necessary, or enclose a set of elements (e.g., paragraphs) with the element referenced by the ID.

Identifies the element that provides a detailed, extended description for the object. See related aria-describedby.

The aria-details attribute references a single element that provides more detailed information than would normally be provided by aria-describedby. It enables assistive technologies to make users aware of the availability of an extended description as well as navigate to it. Authors SHOULD ensure the element referenced by aria-details is visible to all users.

Unlike elements referenced by aria-describedby, the element referenced by aria-details is not used in either the Accessible Name Computation or the Accessible Description Computation as defined in the Accessible Name and Description specification [accname-aam-1.1]. Thus, the content of an element referenced by aria-details is not flattened to a string when presented to assistive technology users. This makes aria-details particularly useful when converting the information to a string would cause a loss of information or make the extended description more difficult to understand.

In some user agents, multiple reference relationships for descriptive information are not supported by the accessibility API. In such cases, if both aria-describedby and aria-details are provided on an element, aria-details takes precedence.

A common use for aria-details is in digital publishing where an extended description needs to be conveyed in a book that requires structural markup or the embedding of other technology to provide illustrative content. The following example demonstrates this scenario.

<!-- Provision of an extended description -->
<img src="pythagorean.jpg" alt="Pythagorean Theorem" aria-details="det">
<details id="det">   <summary>Example</summary>  
<p>     The Pythagorean Theorem is a relationship in Euclidean Geometry between the three sides of a right triangle, where the square of the hypotenuse is the sum of the squares of the two     opposing sides. </p> <p> The following drawing illustrates an application of the Pythagorean Theorem when used to construct a skateboard ramp. </p>   
<object data="skatebd-ramp.svg"  type="image/svg+xml"/>   
<p> In this example you will notice a skateboard with a base and vertical board whose width is the width of the ramp. To compute how long the ramp must be, simply calculate the base length, square it, sum it with the square of the height of the ramp, and take the square root of the sum. </p> 
</details>

Alternatively, aria-details may refer to a link to a web page having the extended description, as shown in the following example.

<!-- Provision of an extended description --> 
<img src="pythagorean.jpg" alt="Pythagorean Theorem" aria-details="det"> 
<p>   See an <a href="http://foo.com/pt.html" id="det">Application of the Pythagorean Theorem</a>.
</p>

A heading for a section of the page.

Often, heading elements will be referenced with the aria-labelledby attribute of the section for which they serve as a heading. If headings are organized into a logical outline, the aria-level attribute is used to indicate the nesting level.

Defines the hierarchical level of an element within a structure.

This can be applied inside trees to tree items, to headings inside a document, to nested grids, nested tablists and to other structural items that may appear inside a container or participate in an ownership hierarchy. The value for aria-level is an integer greater than or equal to 1.

Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed.

For example, this indicates whether a portion of a tree is expanded or collapsed. In other instances, this may be applied to page sections to mark expandable and collapsible regions that are flexible for managing content density. Simplifying the user interface by collapsing sections may improve usability for all, including those with cognitive or developmental disabilities.

If the element with the aria-expanded attribute controls the expansion of another grouping container that is not 'owned by' the element, the author SHOULD reference the container by using the aria-controls attribute.

Indicates that the element is not editable, but is otherwise operable. See related aria-disabled.

This means the user can read but not set the value of the widget. Readonly elements are relevant to the user, and application authors SHOULD NOT restrict navigation to the element or its focusable descendants. Other actions such as copying the value of the element are also supported. This is in contrast to disabled elements, to which applications might not allow user navigation to descendants.

Examples include:

• A form element which represents a constant.
• Row or column headers in a spreadsheet grid.
• The result of a calculation such as a shopping cart total.

Indicates that user input is required on the element before a form may be submitted.

For example, if the user needs to fill in an address field, the author will need to set the field's aria-required attribute to true.

Unless an exactly equivalent native attribute is available, host languages SHOULD allow authors to use the aria-required attribute on host language form elements that require input or selection by the user.

Identifies the element (or elements) whose contents or presence are controlled by the current element. See related aria-owns.

For example:

• A table of contents tree view may control the content of a neighboring document pane.
• A group of checkboxes may control what commodity prices are tracked live in a table or graph.
• A tab controls the display of its associated tab panel.

Indicates that the element is perceivable but disabled, so it is not editable or otherwise operable. See related aria-hidden and aria-readonly.

For example, irrelevant options in a radio group may be disabled. Disabled elements might not receive focus from the tab order. For some disabled elements, applications might choose not to support navigation to descendants. In addition to setting the aria-disabled attribute, authors SHOULD change the appearance (grayed out, etc.) to indicate that the item has been disabled.

The state of being disabled applies to the current element and all focusable descendant elements of the element on which the aria-disabled attribute is applied.

Indicates the entered value does not conform to the format expected by the application. See related aria-errormessage.

If the value is computed to be invalid or out-of-range, the application author SHOULD set this attribute to true. User agents SHOULD inform the user of the error. Application authors SHOULD provide suggestions for corrections if they are known.

When the user attempts to submit data involving a field for which aria-required is true, authors MAY use the aria-invalid attribute to signal there is an error. However, if the user has not attempted to submit the form, authors SHOULD NOT set the aria-invalid attribute on required widgets simply because the user has not yet entered data.

For future expansion, the aria-invalid attribute is an enumerated type. Any value not recognized in the list of allowed values MUST be treated by user agents as if the value true had been provided. If the attribute is not present, or its value is false, or its value is an empty string, the default value of false applies.

Indicates the element that represents the current item within a container or set of related elements.

The aria-current attribute is an enumerated type. Any value not included in the list of allowed values SHOULD be treated by assistive technologies as if the value true had been provided. If the attribute is not present or its value is an empty string or undefined, the default value of false applies and the aria-current state MUST NOT be exposed by user agents or assistive technologies.

The aria-current attribute is used when an element within a set of related elements is visually styled to indicate it is the current item in the set. For example:

• A page token used to indicate a link within a set of pagination links, where the link is visually styled to represent the currently-displayed page.
• A step token used to indicate a link within a step indicator for a step-based process, where the link is visually styled to represent the current step.
• A location token used to indicate the image that is visually highlighted as the current component of a flow chart.
• A date token used to indicate the current date within a calendar.
• A time token used to indicate the current time within a timetable.

Authors SHOULD only mark one element in a set of elements as current with aria-current.

Authors SHOULD NOT use the aria-current attribute as a substitute for aria-selected in widgets where aria-selected has the same meaning. For example, in a tablist, aria-selected is used on a tab to indicate the currently-displayed tabpanel.

A type of live region where new information is added in meaningful order and old information may disappear. See related marquee.

Examples include chat logs, messaging history, game log, or an error log. In contrast to other live regions, in this role there is a relationship between the arrival of new items in the log and the reading order. The log contains a meaningful sequence and new information is added only to the end of the log, not at arbitrary points.

Elements with the role log have an implicit aria-live value of polite.

A type of live region with important, and usually time-sensitive, information. See related alertdialog and status.

Alerts are used to convey messages to alert the user. In the case of audio warnings this is an accessible alternative for a hearing-impaired user. The alert role goes on the node containing the alert message. Alerts are specialized forms of the status role, which will be processed as an atomic live region.

Alerts are assertive live regions and will be processed as such by assistive technologies. Neither authors nor user agents are required to set or manage focus to them in order for them to be processed. Since alerts are not required to receive focus, content authors SHOULD NOT require users to close an alert. If the operating system allows, the user agent SHOULD fire a system alert event through the accessibility API when the WAI-ARIA alert is created. If an alert requires focus to close the alert, then content authors SHOULD use alertdialog instead.

Elements with the role alert have an implicit aria-live value of assertive, and an implicit aria-atomic value of true.

A type of live region whose content is advisory information for the user but is not important enough to justify an alert, often but not necessarily presented as a status bar.

Authors SHOULD ensure an element with role status does not receive focus as a result of change in status.

Status is a form of live region. If another part of the page controls what appears in the status, authors SHOULD make the relationship explicit with the aria-controls attribute.

Assistive technologies MAY reserve some cells of a Braille display to render the status.

Elements with the role status have an implicit aria-live value of polite and an implicit aria-atomic value of true.

Indicates that an element will be updated, and describes the types of updates the user agents, assistive technologies, and user can expect from the live region.

The values of this attribute are expressed in degrees of importance. When regions are specified as polite, assistive technologies will notify users of updates but generally do not interrupt the current task, and updates take low priority. When regions are specified as assertive, assistive technologies will immediately notify the user, and could potentially clear the speech queue of previous updates.

When the property is not set on an object that needs to send updates, the politeness level is the value of the nearest ancestor that sets the aria-live attribute.

When live regions are marked as polite, assistive technologies SHOULD announce updates at the next graceful opportunity, such as at the end of speaking the current sentence or when the user pauses typing. When live regions are marked as assertive, assistive technologies SHOULD notify the user immediately. Because an interruption may disorient users or cause them to not complete their current task, authors SHOULD NOT use the assertive value unless the interruption is imperative.