Web Accessibility Training
Toronto, Montreal, Ottawa and worldwide via Webex More

Demystifying WAI-ARIA
18 WAI-ARIA attributes that every web developer should know

Posted Nov 1, 2019. When a developer who is new to accessibility looks at the ARIA specification it can be seem intimidating, but it doesn't need to be. Most of the ARIA roles, states and properties in that document belong on specialized widgets, and shouldn't be attempted by developers who are new to accessibility. If you want an accessible slider, tablist, modal, accordion, carousel, etc, it would be better use the aria practices document where you can download code and view examples for each of those widgets.

However, every developer should be able to use the following ARIA roles, states, and properties in their day to day coding. They should understand what they do and when to use them and when not to use them. Below is a short list. Each of the attributes is in an HTML <details><summary> group so you can expand to see a cut down version of what the actual spec says about it. There are a few notable omissions (i.e., aria-erromessage) because they are not yet working well with screen readers.

Label

When trying to meet WCAG, the label is the attribute that maps to the Accessible Name which is handed to the screen reader. In HTML, the normal way to do this is as follows:

  • Text inside an <a …>Name of link destination</a> provides its accessible name.
  • Text inside a <button> Name of button</button> provides its accessible name.
  • Text inside a <label for="...">[Name of field]</label> provides the accessible name for a form field such as <input id="..."> or <select id="..."> etc.

The ARIA labelling attributes below override these HTML accessible names, so only use them when you can't use the generic HTML labels above. If you want to provide supplementary information use aria-describedby which is presented to the screen reader separately from the accessible name and doesn't override it.

aria-label (property)

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.

Characteristics:
Characteristic Value
Related Concepts: HTML title
Used in Roles: All elements of the base markup
Value: string

For more details, see aria-label in the ARIA specification.

aria-labelledby (property)

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.

Characteristics:
Characteristic Value
Related Concepts: HTML label
Used in Roles: All elements of the base markup
Value: ID reference list

For more details see aria-labelledby in the ARIA specification.

Description

When you need to add some supplementary information to a form field, use aria-describedby. Don't use aria-labelledby, or aria-label, because it will override the HTML label.

The aria-describedby attribute populates Accessible Description in the operating system accessible API and is used to provide additional or supplemental information. Currently, I recommend it to associate error messages with their corresponding form fields until screen readers support aria-errormessage.

aria-describedby (property)

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.

Characteristics:
Characteristic Value
Used in Roles: All elements of the base markup
Value: string

For more details see aria-describedby in the spec.

aria-details (property)

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.

EXAMPLE 17
<!-- 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.

EXAMPLE 18
<!-- 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>
Characteristics:
Characteristic Value
Used in Roles: All elements of the base markup
Value: string

For more details see aria-details in the ARIA specification.

Headings

Normally you would use HTML <h1>-<h6> But if you have a visual heading in a <div>, <span, <p> etc., that can’t be turned into an HTML heading (i.e., SEO problems etc.) then do this.
<span role=”heading”  aria-level=”2”>
This is an heading 2, change the number to correct heading level.

heading (role)

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.

Characteristics:
Characteristic Value
Superclass Role: sectionhead
Related Concepts: HTML h1, h2, h3, h4, h5, and h6
Required States and Properties: aria-level
Name From:
  • contents
  • author
Accessible Name Required: True
Implicit Value for Role: Default for aria-level is 2.

For more details see heading role in the ARIA specification.

aria-level (property)

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.

Characteristics:
Characteristic Value
Used in Roles:
Value: integer

For more details see aria-level in the ARIA specification.

Buttons and inputs

Forms are going to be one of the core places you use ARIA. In addition to these attributes below, also the section on labelling above comes into play. Use aria-describedby to associate error messages with their corresponding inputs. It is presented to the screen reader separately from the accessible name (label) and doesn't override it like the aria-label or aria-labelledby. Note: aria-errormessage is not supported by screen readers as of this writing.

aria-expanded (state)

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.

Characteristics:
Characteristic Value
Related Concepts: Tapered prompts in voice browsing. Switch in SMIL [SMIL3].
Used in Roles:
Value: true/false/undefined
Values:
Value Description
false The element, or another grouping element it controls, is collapsed.
true The element, or another grouping element it controls, is expanded.
undefined (default) The element, or another grouping element it controls, is neither expandable nor collapsible; all its child elements are shown or there are no child elements.

For more details see aria-expanded in the ARIA specification.

aria-readonly (property)

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.
Characteristics:
Characteristic Value
Related Concepts: XForms [XFORMS10] Readonly
Used in Roles:
Value: true/false
Values:
Value Description
false (default) The user can set the value of the element.
true The user cannot change the value of the element.

For more details see aria-readonly in the ARIA specification.

aria-required (property)

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.

NOTE

The fact that the element is required is often presented visually (such as a sign or symbol after the widget). Using the aria-required attribute allows the author to explicitly convey to assistive technologies that an element is required.

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.

Characteristics:
Characteristic Value
Related Concepts: HTML required
Used in Roles:
Value: true/false
Values:
Value Description
false (default) User input is not necessary to submit the form.
true Users need to provide input on an element before a form is submitted.

For more details see aria-required in the ARIA specification.

aria-controls (property)

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.
Characteristics:
Characteristic Value
Used in Roles: All elements of the base markup
Value: ID reference list

For more details see aria-controls in the ARIA specification.

aria-disabled (state)

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.

Characteristics:
Characteristic Value
Used in Roles: All elements of the base markup
Value: true/false
Values:
Value Description
false (default) The element is enabled.
true The element and all focusable descendants are disabled and its value cannot be changed by the user.

For more details see aria-disabled in the ARIA specification.

aria-invalid (state)

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.

Characteristics:
Characteristic Value
Related Concepts: XForms [XFORMS11'invalid' event. This state is true if a form field is required but empty. However, the XForms valid property would be set to false.
Used in Roles: All elements of the base markup
Value: token
Values:
Value Description
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.

For more details see aria-invalid in the ARIA specification.

Also, for forms, see the section on live regions below to announce that there are errors on the page.

Live Regions  and corresponding roles

WCAG 2.1 Success Criteria 4.1.3 requires that whenever there is a visible status message on the page, there should also be live region around it so that it is announced to users. The role="status" and role="alert" provide an easy way to turn an element into an live region without the aria-live attribute. The status role has an inherent aria-live="polite" and alert has an inherent aria-live="assertive". Both those roles read the entire node even if only a small part of it change, which is usually what we want. If you want that with aria-live you usually have to add aria-atomic. So I'm getting to like the status and alert roles instead of aria-live in many situations.

aria-live (property)

Indicates that an element will be updated, and describes the types of updates the user agentsassistive 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.

Characteristics:
Characteristic Value
Used in Roles: All elements of the base markup
Value: token
Values:
Value Description
assertive Indicates that updates to the region have the highest priority and should be presented the user immediately.
off (default) Indicates that updates to the region should not be presented to the user unless the used is currently focused on that region.
polite Indicates that updates to the region should be presented at the next graceful opportunity, such as at the end of speaking the current sentence or when the user pauses typing.

For more details see aria-live in the ARIA specification.

alert (role)

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.

Characteristics:
Characteristic Value
Superclass Role: section
Subclass Roles:
Related Concepts: XForms alert
Name From: author
Implicit Value for Role: Default for aria-live is assertive.
Default for aria-atomic is true.

For more details see the alert role in the ARIA specification.

status (role)

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.

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

Characteristics:
Characteristic Value
Superclass Role: section
Subclass Roles:
Name From: author
Implicit Value for Role: Default for aria-live is polite.
Default for aria-atomic is true.

For more details see the status role in the ARIA specification.

ARIA Landmark Roles

Most web developers use some landmarks even though they don't know it. When <header>, <main>, <footer>, <nav> and <aside> are used properly they are super useful to screen reader users. Use these HTML sections when possible. Add in role="search" to that mix because there is no HTML equivalent landmark. Add aria-label to your <nav> elements.

Mapping HTML sections to ARIA Landmarks
Landmarks
HTML (it's better to do this) If you can't use HTML sections then do this
<header> <div role="banner"  ...>
<main> <div role="main" ...>
<footer> <div role="contentinfo" ...>

SEARCH: No corresponding html section so use the ARIA role to the right

Put this around your search elements.
<div role="search" ...>
...<input ...>
</div>
<aside> <div role="complementary">
<nav aria-label="[give it a name]">

i.e. primary, secondary, social medial etc.

<div role="navigation" aria-label=[give it a name]

For more details see landmark role in the ARIA specification.

Others

Images normally will be inserted with the HTML <img> tag. But occasionally icon fonts, background images etc., require an image role. Remember to add an aria-label to any element that has role=img. See this blog post on background images.

img (role)

A container for a collection of elements that form an image.

An img can contain captions and descriptive text, as well as multiple image files that when viewed together give the impression of a single image. An img represents a single graphic within a document, whether or not it is formed by a collection of drawing objects. In order for elements with a role of img be perceivable, authors MUST provide alternative text or a label determined by the accessible name calculation.

Characteristics:
Characteristic Value
Superclass Role: section
Related Concepts:
Name From: author
Accessible Name Required: True
Children Presentational: True

For more details see img role in the ARIA specification.

aria-current (state)

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.

NOTE

In some use cases for widgets that support aria-selected, current and selected can have different meanings and can both be used within the same set of elements. For example, aria-current="page" can be used in a navigation tree to indicate which page is currently displayed, while aria-selected="true" indicates which page will be displayed if the user activates the treeitem. Furthermore, the same tree may support operating on one or more selected pages (treeitems) by way of a context menu containing options such as "delete" and "move."

Characteristics:
Characteristic Value
Used in Roles: All elements of the base markup
Value: token
Values:
Value Description
page Represents the current page within a set of pages.
step Represents the current step within a process.
location Represents the current location within an environment or context.
date Represents the current date within a collection of dates.
time Represents the current time within a set of times.
true Represents the current item within a set.
false (default) Does not represent the current item within a set.

For more details see aria-current in the ARIA specification.



Author information:

David MacDonald is a veteran WCAG member, co-editor of Using WAI ARIA in HTML5 and HTML5 Accessibility Task Force Member. Opinions are my own. Feel free to comment on Twitter @davidmacd




CONTACT US

For a quote or just to chat about your organization's needs


EMAIL

help at can hyphen adapt dot com, (spoken phonetically to trick spam bots)

PHONE

six one three, eight zero six, nine zero zero five

SOCIAL MEDIA