ARIA Deep Dive

What is ARIA?

ARIA stands for Accessible Rich Internet Applications and is defined by the World Wide Web Consortium. ARIA is used to help users who rely on screen readers understand what’s going on when a custom JavaScript event or script that is fired. Imagine you’re reading content on a website and an alert pops up in a corner of your screen, perhaps to say that a download is complete or that there has been some kind of error. Unless that popup event is tied to an action in ARIA, any user with a screen reader would have no idea that it ever occured, and their reader would keep on reading whatever text they were previously focused on.

One way to think about ARIA is that it is analogous to HTML. The difference between a plain old document of just text and an HTML document is that HTML adds a layer metadata and information that a browser uses to change how the document’s text and other elements are displayed. HTML can also change how things function, like a form or link, but ignore those for a second. HTML doesn’t change the text or what the document says, it just changes what it looks like and how it is laid out.

ARIA is just like that. It adds an additional layer of metadata to the HTML document. Instead of changing how it looks and behaves, it just adds additional information that is useful for screen readers. That’s it. ARIA is ONLY useful for screen readers. It doesn’t change anything about a page visually. For example, the attribute aria-hidden="true" doesn’t visually hide anything, but it does “hide” the element from screen readers.

When Should I Use ARIA?

HTML does the job just fine most of the time. If there is a native HTML element for something you want, like a <header>, <nav>, <button>, or <form>, just use it. ARIA should be used when there is a scripting event or a custom element that requires more than standard HTML to function. In those cases, browsers, screen readers, and other renderers must be able to determine the following attributes:

• label (or name)
• role
• properties
• state (for widgets that can change state)

and must be notified of any changes to these attributes, particularly state.

If you’re going to use ARIA, you must be thorough! Go all in or don’t use it at all. Imagine a user that is reliant on but also very experienced with screen reader technologies. The following situations are in order of preference:

1. An ARIA-compliant site. All of the controls work the way they’re supposed to, and interactions are easy and follow expected conventions.
2. A site with no ARIA code at all. It’s a pain in the neck to get around, but it’s something that the user is unfortunately kind of used to. Things aren’t easy, but at least all of their keyboard shortcuts don’t break.
3. A site that has some ARIA in places, but not all. What a mess! The site behaves in unpredictable ways. Some controls work and some require switching to another set of shortcuts and keystrokes. The experience is extremely frustrating and everything has to be learned one element at a time.

The Web Accessibility initiative has a wonderful write-up on why no ARIA is better than bad ARIA.

A helpful way to remember this is the ARIA axioms:

• NEVER use ARIA unless you have to.
• ALWAYS use ARIA when you have to.
• You’re probably doing it wrong.

ARIA Lifecycle and Why It Matters

Web browsers are designed to load and draw the screen as quickly as possible. As soon as the HTML and CSS are downloaded, the browser instantly builds a DOM (Document Object Model) and applies all of the relevant CSS rules to it. Then it draws that DOM to the screen before it even tries to load, parse, and run additional JavaScript code, unless specifically designed to do it differently. Occasionally, that JavaScript code has to do with measuring the active window’s size in order to apply certain styles or effects, which can lead to really awkward jitter as the page has to quickly be redrawn just after it has loaded. You’ve probably seen it countless times as pages struggle to load on mobile devices and elements appear only to quickly disappear.

Similarly, web browsers and screen readers parse a page’s initial HTML code to create an Accessibility Tree. This happens as soon as the DOM is created, and before the JavaScript is executed. What this means is that if you want a browser or screen reader to be aware of any element, that element must be present in the intial HTML.

Imagine you want an “alert” widget that pops up on the screen when something important happens. If you didn’t need to worry about accessibility, you can do this any number of ways. You could just create elements on the fly and add them to the DOM using JavaScript, like this:

// Bad, inaccessible way to add a popup widget.
function showAlert(alertMessage) {
  // Creates a new div. This will NOT be parsed in the Accessibility Tree.
  const newAlertDiv = document.createElement('div')
  const newAlertText = document.createTextNode(alertMessage)
  newAlertDiv.appendChild(newAlertText)

  // Add that new div to the some container that holds and styles all the alerts.
  const alertsContainer = document.getElementById('alertsContainer')
  alertsContainer.appendChild(newAlertDiv)
}

In order to make the same sort of behavior happen accessibly:

1. The accessible elements must exist when the HTML DOM and Accessibility Tree are created.
2. The accessible elements must be given the correct role attribute so that behaviors and event listeners can be added properly.
3. The elements must be used and updated in a way that will be recognized by screen readers.

For this example, we would load the page with something like this:

<div id='alertContainer' role='alert' aria-live='polite'></div>

By creating an empty element with the proper role, the Accessibility Tree will add a listener automatically. Whenever the content of an alert widget is updated, the screen reader is advised and will read whatever is in the <div> as soon as it’s done reading whatever element it’s currently on. That specific behavior based on the polite value; if we changed the attribute to aria-live='assertive', then it would read the alert immediately, interrupting the screen reader. With this setup done, the new accessible version of the code is even simpler.

// Good, accessible code PROVIDED that the HTML is preloaded and tagged correctly.
function showAlert(alertMessage) {
  // Add the message to the container. ARIA's 'alert' role can handle the rest!
  document.getElementById('alertContainer').innerHTML(alertMessage)
}

For working examples of this and other widgets, see the Widget Example Library below.

ARIA Labels and Names

When a screen reader comes to an element, what will it say? It depends. “Accessible Names” are computed using the following priorities:

1. aria-labelledby - If this attribute exists, it will override any other name and label methods.
2. aria-label - Second choice. Note that this text is invisible except to screen readers.
3. Native Text - The text inside an element’s tags (like in a <button>) or standard alternatives (<label> on form, alt on an image).
4. title - As a last resort, the title may be used. Don’t rely on title because it generally only shows up when users hover over something, and keyboard and mobile users don’t have a hover mechanism.

aria-labelledby

The aria-labelledby property is a reference or pointer to another element where the current element’s name is. For example, if you had an image on your page with a caption under it that sighted users could read, you can use that caption as your alt text instead of adding it again to the image.

<!-- Bad example: A screen reader would read the alt text twice: once on the image and again right below it. -->
<img src="pollock_painting.png" alt="Jackson Pollock's 'drip technique' is an example of abstract art.">
<div class="citation">Jackson Pollock's 'drip technique' is an example of abstract art.</div>

<!-- Better example: When the screen reader finds the image, it will read the proper citation once. -->
<img src="pollock_painting.png" aria-labelledby="pollock_citation">
<div class="citation" id="pollock_citation">Jackson Pollock's 'drip technique' is an example of abstract art.</div>

<!-- Best example: When a semantic HTML equivalent exists, skip ARIA altogether -->
<figure>
  <img src="pollock_painting.png">
  <figcaption>Jackson Pollock's 'drip technique' is an example of abstract art.</figcaption>
</figure>

One additional strength of aria-labelledby is that you can chain multiple labels together. This is especially helpful for things like complex forms

<span id="males"> ... <span id="frank"> ... <span id="ranking"> 
<input type="text" aria-labelledby="males frank ranking">

aria-label

The aria-label property is a way to add a label to an element that does not normally appear on screen. Since aria-label is prioritized over native text, screen readers will use this instead of whatever text is already inside the element.

<!-- Screen readers should say 'Close Window' instead of 'X' -->
<button onClick="closeWindow" aria-label="Close Window">X</button>

<!-- This can be used to make links more descriptive, since links are often read in a list and lose some context -->
<a href="http://w3.org" aria-label="The World Wide Web Consortium">W3C</a>

ARIA Roles

Every HTML element has a specific role on a page, which tells a screen reader how and when to access it and what properties it ought to have. For instance, an image has different behavior from a link, and a menu is navigated differently from a table.

Landmark Roles

Landmarks are expected areas on a web page or app, and often screen readers have quick shortcuts to navigate between them. The most common landmarks are also common semantic HTML tags, so for example if you are using the <nav> tag, a screen reader will understand that it is a navigation menu the same as if you applied a role attribute, like <div role='navigation'>. Where possible, it is preferable to just use the HTML tags.

Interactivity Modes

Screen readers respond differently based on the kind of mode they’re in, which is triggered by certain role attributes.

Document Mode

The default role for a web page is role='document'. This means that the whole HTML document is broken into pieces, where lists of headers, links, and menus are combined. Links are treated specially, images’ alt text is read, and certain landmark sections are expected. If no other role attribute is applied, document is assumed.

Presentation Mode

When the attribute role='presentation' is used on an element, ALL special treatment of the document is stripped out. This means that all HTML tags are treated as <div>s or <span>s, and all text is treated as plain text. All other ARIA states and properties are ignored.

<!-- Instead of "Header Level 1: ARIA Guidebook", the reader would just say "ARIA Guidebook" -->
<h1 role='presentation'>ARIA Guidebook</h1>

<!-- Instead of saying "Link: University of Central Florida", the reader would just say "UCF" -->
<a role="presentation" href="https://ucf.edu" aria-label="University of Central Florida">UCF</a>

Application Mode

Application mode (role='application') allows developers to rework how screen readers interact with the page or app content. It turns off almost all of the default screen reader behavior in favor of custom-coded solutions. While it is sometimes necessary, avoid it when you can and limit it’s scope when you can’t.

• All keyboard navigation features are disabled except Tab, Enter/Return, space bar, and arrow keys.
• The following elements can NOT be focused on without explicit tabindex='0': <p>, <h1>-<h6>, <div>, <span>, lists, tables, etc.
• Elements cannot be interacted without explicit code.

Some widgets are Applications by default: dialogs, alertdialogs, and tablists. When using these, you may need to revert the content inside them back to documents.

<div role='alertdialog'>
  <!-- Without the role='document' attribute below, the link would not be interactive for screen readers. -->
  <div role='document'>
    Alert! There is an error. <a href="../path/to/logs">See error logs.</a>
  </div>
</div>

Math Role

While there are other ways to render mathematical and other equations to the screen, complicated equations are often saved as images with no alt text, making them inaccessible. The role='math' attribute allows screen readers to take equations and render them properly and often allows users to traverse through the equations. Without getting too much into the weeds, here is a small example:

<div role="math" aria-label="a squared plus b squared equals c squared">
  <math xmlns="http://www.w3.org/1998/Math/MathML">
    <mrow>
      <msup>
        <mi>a</mi>
        <mn>2</mn>
      </msup>
      <mo>+</mo> 
      <msup>
        <mi>b</mi>
        <mn>2</mn>
      </msup>
      <mo>=</mo>
      <msup>
        <mi>c</mi>
        <mn>2</mn>
      </msup>
    </mrow>
  </math>
</div>

Which would render as:

We recommend using MathJax as a preprocesser to make it easier for faculty to enter equations, so they don’t have to type in so much convoluted HTML code. It also has a built-in Accessibility Components which, among other things, has a process to render formulas as text output for screen readers, which can automatically be attached like the aria-label in the example above.

Pseudo HTML Roles

If at all possible, you’ll want to use the proper semantic HTML syntax for available tags. At times, you may need to retrofit existing code, and change existing elements to become accessible. For example, if you want a page header, you should simply use an <h1> tag. However, if for some reason, that isn’t feasible (like poorly-written existing JavaScript code relying on the exact number of divs in a page or some such nonsense), you can make any element behave as an <h1> using ARIA, for example:

<p role='heading' aria-level='1'>This text is a header now</p>

Again, using a role attribute to override the semantic HTML tag is BAD PRACTICE and should be avoided where possible. But in a pinch, it can turn an inaccessible element into an accessible one. Available Pseudo HTML roles are:

• button
• checkbox
• columnheader
• combobox
• contentinfo
• form
• grid
• gridcell
• heading
• img
• link
• listbox
• listitem
• option
• radio
• radiogroup
• row
• rowgroup
• rowheader
• scrollbar
• textbox

Widget Roles

If there are interactive elements on your page (like a text field, check box, or slider), they are most likely some form of <input> or <button> element. But many of these elements behave in very different ways, and need different controls for users who are constrained to a keyboard. Instead of inventing your own custom controls, your users will be able to use the ones they’re used to, as long as their device can tell what kind of widget it is. W3.org has full documentation on interface widgets and roles.

Individual Widgets

Individual widgets can be used in isolation as a standalone element OR as a part of a larger, composite widget.

Composite Widgets

Composite widget roles are applied to parent elements that contain one or more child elements, similar to <ol> or <ul> with their <li> children in basic HTML.

Extraneous Roles

There are a handful of specific element roles that are similar to widgets in that they are used for small, limited use cases, but they are not interactive in the same way. It may be helpful to think of them as a unique HTML tag that hasn’t been added to the HTML spec yet and can only be accessed via ARIA attributes, similar to the role="search" landmark for a search bar.

• The definition role may help screen readers curate lists of terms in a text, but isn’t widely supported yet.
• The note is similar to an <aside> tag or complementary role, but isn’t a landmark. It is read in context.
• The directory role used to be used for Table of Contents or similar elements, but is now deprecated.
• Abstract roles are NOT used in code, but are included in the spec. They include invisible roles that implied when other roles are used, such as composite, landmark, section, and widget.

ARIA Properties and States

The primary difference between properties and states is that properties (like aria-labelledby) are unlikely to change during a page or application’s lifecycle, where states (like aria-checked) are designed to change.

Global Properties and States

Some states and properties can be applied to ANY element globally, whether or not those elements have specific ARIA roles.

• The P/S column is to help distinguish whether a specific tag is an ARIA property or and ARIA state.
• An ID Reference List is a space-separated list of IDs, for example 'firstID secondID thirdID'.
• When the values are an enumerated list, the value in all caps is the DEFAULT.

Widget Properties and States

A widget is anything that receives user input or processes user actions. For ARIA, that includes objects with certain roles like alert, button, menu, progressbar, textbox, tooltip, etc. See the Widget Roles section above for a full list.

• The P/S column is to help distinguish whether a specific tag is an ARIA property or and ARIA state.
• When the values are an enumerated list, the value in all caps is the DEFAULT.

Widget Example Library

Before creating ANY widget using ARIA, you should absolutely check out the ARIA design patterns provided by the Web Accessibility Initiative. Helpful shortcuts for those patterns are provided below.