Home / Best Practices / ARIA

ARIA

Basics

  1. All content on a webpage should be contained inside landmarks.
  2. Use ARIA roles to describe the type of widget presented.
  3. Use an aria-label attribute to identify form controls without label.
  4. Use tabindex or ARIA roles to ensure an element can receive keyboard focus.
  5. Alert users to dynamic changes in content by defining live regions, especially error messages.
  6. Use ARIA states to describe the state widgets are in.

In depth

The Web Accessibility Initiative (WAI) defines Accessible Rich Internet Applications (ARIA) as:

a way to make Web content and Web applications more accessible to people with disabilities. It especially helps with dynamic content and advanced user interface controls developed with Ajax, HTML, JavaScript, and related technologies.

Most HTML elements have a default role that's understood by browsers and assistive devices--a button has the role of button, for instance.  Some have additional properties and states as well--for example, a link can be active or visted.  But many elements, such as divs and spans, are without a role.  

ARIA allows developers to define roles, states and properties that are not natively available in HTML and to override the HTML defaults of elements. ARIA is supported by most browsers and screen readers, and it is a powerful tool in a developer's accessibility arsenal.

Landmarks: HTML5 and ARIA roles

Landmarks identify the major structural parts of a webpage and can be used by screen reader and other users for keyboard navigation. All content on a webpage should be contained inside landmarks.

There are two ways to define landmarks: with an HTML5 landmark element or an ARIA landmark role. Because some elements and roles are not yet supported by all browsers or screen readers, it's recommended to use both when possible. If no HTML5 landmark element is available (for instance, if you can only use a <div>), an ARIA landmark role alone will define the landmark.

HTML5
landmark
element
ARIA
landmark
role
DefinitionUsage
<header>role="banner"Site-oriented content at the beginning of each pageOnly one per page. Must be a top-level landmark.
<nav>role="navigation"Groups of links intended for website or page navigationIf more than one, each should have a unique label.
<main>role="main"Primary contentOnly one per page. Must be a top-level landmark.
<section>role="region"Content relevant to a specific, author-specified purposeMust have an unique label.
<aside>role="complementary"Supporting section that complements and is related to the main content but remains meaningful when separated from itMust be a top-level landmark.  If more than one, each should have an unique label.
<footer>role="contentinfo"Common information at the bottom of each pageOnly one per page. Must be a top-level landmark.
<form>role="form"Collection of items and objects that together create a formMust have an unique label.
Nonerole="search"Contains search functionality for the siteIf more than one, each should have an unique label.

Example of recommended HTML5 and ARIA landmark roles

<header role="banner">
  ...
</header>
<nav role="navigation">
  ...
</nav>
<main role="main">
  ...
</main>
<footer role="contentinfo">
  ...
</footer>

Example of ARIA landmark roles alone

<div role="banner">
  ...
</div>
<div role="navigation">
  ...
</div>
<div role="main">
  ...
</div>
<div role="contentinfo">
  ...
</div>

Labels for HTML5 and ARIA landmarks

Some HTML5 and ARIA landmarks require labels.

  • The <header>, <main> and <footer> landmarks do not need labels because they can only be defined once per page.
  • Landmarks such as <form> and <section> must always be labeled, even when they are the only landmark of that type on the page.
  • Landmarks such as <nav> and <aside> must have a unique label if more than one is used per page.

You can uniquely label landmarks using the aria-labelledby, aria-label, and title properties:

aria-labelledby: Identifies the element that labels the current landmark.

<aside aria-labelledby="comp1">
<h2 id="comp1">Title for Complementary Area 1</h2>
...
</aside>

aria-label: Provides text that labels the current landmark when no other label exists; is visible only to assistive technologies.

<aside aria-label="Title for Complementary Area 1">
...
</aside>

title: Identifies the element that labels the current landmark and may be available as a tooltip on some browsers.

<aside title="comp1">
<h2 id="comp1">Title for Complementary Area 1</h2>
...
</aside>

ARIA roles to describe widgets

ARIA roles can be used to define many otherwise meaningless HTML5 elements (such as divs and spans). Attaching a role gives assistive technologies information about how to handle each element. For example, the following seems to be a simple list:

<ul>
  <li><a href="#bio">Bio</a></li>
  <li><a href="#resume">Resume</a></li>
  <li><a href="#awards">Awards</a></li>
</ul>

But it could instead be tabs or a menu, which function quite differently.  In the absence of visual cues, adding ARIA roles defines elements so assistive devices know how they should behave.

<ul role="tablist">
  <li><a role="tab" href="#bio">Bio</a></li>

Live regions for dynamic content

For content that changes dynamically without page reload, ARIA provides a way to alert assistive device users of those changes: the aria-live property.

<select>
<option> .... </option>
</select>

<div aria-live="polite">
...
</div>

Possible values for aria-live are:

  • off: screen reader will not announce the changes unless focused on the region
  • polite: changes will be announced when the user pauses next
  • assertive: changes are immediately announced

aria-live="assertive" is often used for dynamic error messages and is equivalent to role="alert".

Tabindex and ARIA roles to set focus

An important component of keyboard accessibility is the ability to set focus on an element. By default only links, buttons and forms can receive focus.  NOTE: An anchor with an empty HREF (an "empty link") is not focusable or keyboard accessible (see more in Javascript).

Tabindex to make elements focusable

Setting tabindex="0" on an element places the element in the logical navigation flow of the document and allows it to receive focus.  For instance, tabindex will allow focus to be set on a normally unfocusable element, such as a <div>:

<div id="menu-container" tabindex="0">

ARIA-roles to make elements focusable

The ARIA-role attribute can add a role to otherwise meaningless (or "role-less") elements such as spans and divs, thus allowing them to receive focus.  For example:

<span id="checkbox" role=”checkbox” aria-checked=”false”>...</span>

<div class="button" aria-role="button">Go back</div>

ARIA states

ARIA provides for many states that can add, supplement or alter the current condition of an HTML5 element. For example:

<input aria-disabled="true">
<input aria-required="false">
<input aria-hidden="true">
<input aria-checked="false">

There are many aria states and properties to enhance the accessibility of HTML5 elements. See a list of all ARIA properties and states.

Resources

An excellent resource for learning ARIA is the Ryerson University online textbook, Web Accessibility for Developers.

For a table of ARIA roles and attributes, see the ARIA Role Matrices from WhatSock.

The A11y Project is a good source for accessible widgets.  Additionally, the "Design Patterns and Widgets" section of the WAI-ARIA Authoring Practices 1.1 provides extensive documentation on creating accessible Javascript widgets, such as:

  • Accordion
  • Alert and Message Dialogs
  • Breadcrumb
  • Button
  • Checkbox
  • Combo Box
  • Dialog (Modal and non-modal)
  • Grids
  • Link
  • Listbox
  • Menu or Menu bar
  • Menu Button
  • Radio Group
  • Slider
  • Spinbutton
  • Table
  • Tabs
  • Toolbar
  • Tree View
  • Window Splitter

For more information on WAI-ARIA, see:

Relevant W3C WAI documents

  • WCAG 2.1 Guideline 2.1.1 Keyboard: All functionality of the content is operable through a keyboard interface without requiring specific timings for individual keystrokes, except where the underlying function requires input that depends on the path of the user's movement and not just the endpoints.
  • How to Meet WCAG 2.1 Guideline 2.1.1
  • WCAG 2.1 Guideline 2.4.4 Link Purpose (In Context): The purpose of each link can be determined from the link text alone or from the link text together with its programmatically determined link context, except where the purpose of the link would be ambiguous to users in general.
  • How to Meet WCAG 2.1 Guideline 2.4.4
  • WCAG 2.1 Guideline 4.1.2 — Name, Role, Value: For all user interface components (including but not limited to: form elements, links and components generated by scripts), the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to user agents, including assistive technologies. (Level A)
  • How to Meet WCAG 2.1 Guideline 4.1.2