Accessibility: What users can do to browse more safely - Accessibility

Accessibility: What users can do to browse more safely
======================================================

This article discusses making web content accessible for those with vestibular disorders, and those who support them, by taking advantage of personalization and accessibility settings built into the operating systems. Taking advantage of personalization settings can help prevent exposure to content leading to seizures and / or other physical reactions.

Personalization and accessibility settings
------------------------------------------

From the article, "**Understanding Success Criterion 2.3.1: Three Flashes or Below Threshold**"

>
> Flashing can be caused by the display, the computer rendering the image or by the content being rendered. The author has no control of the first two. They can be addressed by the design and speed of the display and computer
>
>
>

### Hardware and operating systems on many computers offer control that is not afforded to developers

The user can do much to protect himself by learning his operating system, its personalization and accessibility settings. Those in the public sector who must accommodate those with special sensitivities, should consider setting aside at least one work station and becoming familiar with its personalization and accessibility settings. Understanding personalization and accessibility settings can actually be a money-saving endeavor. One work station can be set up to accommodate both a low-vision individual (needs high-contrast) and to accommodate an individual with photosensitive susceptibilities, by, adjusting personalization and accessibility settings.

### Use modern browsers. Learn personalization and accessibility settings

Modern browsers support the CSS media feature `prefers-reduced-motion`. Browsers can detect whether a user has requested a reduced motion experience. The user would access this through an accessibility interface, as seen below.

![Screen shot showing how to turn off animations in Windows 10.](/en-US/docs/Web/Accessibility/Accessibility:_What_users_can_to_to_browse_safely/android-remove-animations.png)

CSS Transition events are supported. Examples include:

* `transitionrun`
* `transitionstart`
* `transitionend`
* `transitioncancel`
### Safari 10.1 and above (Desktop)

Do not enable Auto-Play (does not work for gifs)

#### iOS Safari 10.3 and above (Mobile and Tablet)

Select the "Reduce motion option" in OS Accessibility settings for Apple (image source: developers.google.com from Thomas Steiner's article "Move Ya! Or maybe, don't, if the user prefers-reduced-motion!"). This will not work on animated gifs; the source of the animation is self-contained within a gif and is not affected by these settings.
 ![Screen shot showing how to reduce motion on a MAC OS](/en-US/docs/Web/Accessibility/Accessibility:_What_users_can_to_to_browse_safely/macos-reduce-motion.png)

#### Use Reader Mode on browsers

* Enable Content Blockers; Gets rid of ads, reduces and/or removes distractions
* Enables text-to-speech
* In certain browsers, enable fonts by choice
* Enable Page Zoom

#### Turn off animated GIFs in the browser

Browsers offer much power to their users; it's just a matter of knowing where to go. Using Firefox as an example, it explains that by changing the value the **image.animation\_mode** from "normal" to "none", all animated images will be blocked. To reverse it, you will have to change the value back to "normal"

![Screenshot of image.animation.mode selected in Firefox](/en-US/docs/Web/Accessibility/Accessibility:_What_users_can_to_to_browse_safely/image_animation_mode.png)

#### Use browser extensions

* Gif Blocker For Chrome, GIF Blocker is an extension available at the web store.
* Gif Scrubber Gif Scrubber is a chrome extension that allows you to control gifs like a video player. There is a GitHub repository for it at **https://github.com/0ui/gif-scrubber**
* Beeline Reader Beeline Reader has a browser extension that allows you to set up for grayscale and Dyslexi font, among other things

![Screenshot showing modes of Beeline Reader a user can adjust in browser](/en-US/docs/Web/Accessibility/Accessibility:_What_users_can_to_to_browse_safely/beelinereader.png)

### Take advantage Operating System accessibility features

Most operating systems such as Windows 10, have accessibility options that are surprisingly powerful. Usually they are quite easy to find by typing (or saying) in the word, "Accessibility" in the search finder of the operating system.

#### Turn off animations in the operating system

In the Windows10 operating system, the user has an ability to turn off animations. This will not work on animated gifs; the source of the animation is self-contained within a gif and is not affected by these settings.

![Screen shot showing how to turn off animations in Windows10](/en-US/docs/Web/Accessibility/Accessibility:_What_users_can_to_to_browse_safely/turnoffanimationsinwindows.png)

#### Grayscale

Those who have suffered traumatic brain injury (TBI) may be highly sensitive to color; it can require such a great "investment of cognitive energy" on their part, there's no energy for other daily tasks. Enabling grayscale presentation of the content reduces the cognitive workload. It may assist users with other disabilities, as well. An interesting discussion by users on the benefits of using grayscale may be found in the discussion thread, "What is the "grayscale" setting for in accessibility options?". Of particular interest is a user who has Photosensitive Epilepsy, and uses it when feeling "seizure-y".

Most Operating Systems have a way to let the user make an adjustment on the workstation. In the screenshot below, you can see an example of Windows 10 Accessibility Settings allowing for color filters to be selected. Grayscale is enabled when the color filters button is toggled "on"

![Shows Windows 10 Accessibility Settings for GrayScale](/en-US/docs/Web/Accessibility/Accessibility:_What_users_can_to_to_browse_safely/colorfiltersgrayscaleinwindows.png)

See also
--------

* Accessibility
* Accessibility learning path
* Web accessibility for seizures and physical reactions
* Color vision simulation
* Discussion: "What is the "grayscale" setting for in accessibility options?"
### Contributors

Many, many thanks to Eric Eggert from Knowbility; for his discussions and huge help on this topic.


Understanding the Web Content Accessibility Guidelines - Accessibility

Understanding the Web Content Accessibility Guidelines
======================================================

This set of articles provides quick explanations to help you understand the steps that need to be taken to conform to the recommendations outlined in the W3C Web Content Accessibility Guidelines 2.0 or 2.1 (or just WCAG, for the purposes of this writing).

The WCAG 2.0 and 2.1 provide a detailed set of guidelines for making web content more accessible to people with a wide variety of disabilities. It is comprehensive but incredibly detailed, and quite difficult to gain a rapid understanding of. For this reason, we have summarized the practical steps you need to take to satisfy the different recommendations, with further links to more details where required.

The four principles
-------------------

WCAG is broadly broken down into four principles — major things that web content **must be** to be considered accessible (see Understanding the Four Principles of Accessibility for the WCAG definitions).

Each of the links below will take you to pages that further expand on these areas, giving you practical advice on how to write your web content so it conforms to the success criteria outlined in each of the WCAG 2.0 and 2.1 guidelines that further sub-divides each principle.

* Perceivable: Users must be able to perceive it in some way, using one or more of their senses.
* Operable: Users must be able to control UI elements (e.g. buttons must be clickable in some way — mouse, keyboard, voice command, etc.).
* Understandable: The content must be understandable to its users.
* Robust: The content must be developed using well-adopted web standards that will work across different browsers, now and in the future.
Should I use WCAG 2.0 or 2.1?
-----------------------------

WCAG 2.1 is the most recent and relevant accessibility standard. Use WCAG 2.1 to help more people with disabilities and reduce the future legal risk for website owners. Target WCAG 2.0 first when allocating resources. Then step up to WCAG 2.1.

### What is WCAG 2.1?

WCAG 2.1 was published as an official recommendation on 05 June 2018. The European Union (EU) adopted WCAG 2.1 as the digital accessibility standard in September 2018. W3C published a press release WCAG 2.1 Adoption in Europe.

WCAG 2.1 includes:

* all of WCAG 2.0 (verbatim, word-for-word)
* 17 new Success Criteria at the A / AA / AAA levels primarily addressing user needs in these areas:
    + Mobile Accessibility
    + Low Vision
    + Cognitive
* Read more about WCAG 2.1:
    + W3C/WAI: What's new in WCAG 2.1?
    + Deque: WCAG 2.1: What is Next for Accessibility Guidelines
    + TPG: Web Content Accessibility Guidelines (WCAG) 2.1
Legal standing
--------------

This guide is intended to provide practical information to help you build better, more accessible websites. However, we are not lawyers, and none of this constitutes legal advice. If you are worried about the legal implications of web accessibility, we'd recommend that you check the specific legislation governing accessibility for the web/public resources in your country or locale, and seek the advice of a qualified lawyer.

What is accessibility? and particularity the Accessibility guidelines and the law section provide more related information.


ARIA - Accessibility

ARIA
====

Accessible Rich Internet Applications **(ARIA)** is a set of roles and attributes that define ways to make web content and web applications (especially those developed with JavaScript) more accessible to people with disabilities.

It supplements HTML so that interactions and widgets commonly used in applications can be passed to assistive technologies when there is not otherwise a mechanism. For example, ARIA enables accessible JavaScript widgets, form hints and error messages, live content updates, and more.

**Warning:** Many of these widgets are fully supported in modern browsers. **Developers should prefer using the correct semantic HTML element over using ARIA**, if such an element exists. For instance, native elements have built-in keyboard accessibility, roles and states. However, if you choose to use ARIA, you are responsible for mimicking the equivalent browser behavior in script.

The first rule of ARIA use is "If you can use a native HTML element or attribute with the semantics and behavior you require already built in, instead of re-purposing an element and adding an ARIA role, state or property to make it accessible, then do so."

**Note:** There is a saying "No ARIA is better than bad ARIA." In WebAim's survey of over one million home pages, they found that Home pages with ARIA present averaged 41% more detected errors than those without ARIA. While ARIA is designed to make web pages more accessible, if used incorrectly, it can do more harm than good.

Here's the markup for a progress bar widget:

```html
<div
 id="percent-loaded"
 role="progressbar"
 aria-valuenow="75"
 aria-valuemin="0"
 aria-valuemax="100"></div>
```

This progress bar is built using a `<div>`, which has no meaning. We include ARIA roles and properties to add meaning. In this example, the `role="progressbar"` attribute informs the browser that this element is actually a JavaScript-powered progress bar widget. The `aria-valuemin` and `aria-valuemax` attributes specify the minimum and maximum values for the progress bar, and the `aria-valuenow` describes the current state of it and therefore must be kept updated with JavaScript.

Along with placing them directly in the markup, ARIA attributes can be added to the element and updated dynamically using JavaScript code like this:

```js
// Find the progress bar <div> in the DOM.
const progressBar = document.getElementById("percent-loaded");

// Set its ARIA roles and states,
// so that assistive technologies know what kind of widget it is.
progressBar.setAttribute("role", "progressbar");
progressBar.setAttribute("aria-valuemin", 0);
progressBar.setAttribute("aria-valuemax", 100);

// Create a function that can be called at any time to update
// the value of the progress bar.
function updateProgress(percentComplete) {
  progressBar.setAttribute("aria-valuenow", percentComplete);
}
```

All content that is available to non-assistive technology users must be made available to assistive technologies. Similarly, no features should be included targeting assistive technology users that aren't also accessible to those not using assistive technologies. The above progressbar needs to be styled to make it look like a progressbar.

It would have been much simpler to use the native `<progress>` element instead:

```html
<progress id="percent-loaded" value="75" max="100">75 %</progress>
```

**Note:** The `min` attribute is not allowed for the `<progress>` element; its minimum value is always `0`.

**Note:** HTML landmark elements (`<main>`, `<header>`, `<nav>`, etc.) have built-in implicit ARIA roles, so there is no need to duplicate them.

Support
-------

Like any other web technology, there are varying degrees of support for ARIA. Support is based on the operating system and browser being used, as well as the kind of assistive technology interfacing with it. In addition, the version of the operating system, browser, and assistive technology are contributing factors. Older software versions may not support certain ARIA roles, have only partial support, or misreport its functionality.

It is also important to acknowledge that some people who rely on assistive technology are reluctant to upgrade their software, for fear of losing the ability to interact with their computer and browser. Because of this, it is important to use semantic HTML elements whenever possible, as semantic HTML has far better support for assistive technology.

It is also important to test your authored ARIA with actual assistive technology. This is because browser emulators and simulators are not really effective for testing full support. Similarly, proxy assistive technology solutions are not sufficient to fully guarantee functionality.

References
----------

ARIA roles

Reference pages covering all the WAI-ARIA roles discussed on MDN.

ARIA states and properties

Reference pages covering all the WAI-ARIA states and properties discussed on MDN.

Standardization efforts
-----------------------

WAI-ARIA specification

The W3C specification itself.

WAI-ARIA authoring practices

The official best practices documents how best to ARIA-ify common widgets and interactions. An excellent resource.

ARIA for scripted widgets
-------------------------

Writing keyboard-navigable JavaScript widgets

Built-in elements like `<input>`, `<button>`, etc. have built-in keyboard accessibility. If you 'fake' these with `<div>`s and ARIA, you must ensure your widgets are keyboard accessible.

Live regions

Live regions provide suggestions to screen readers about how to handle changes to the contents of a page.

Videos
------

The following talks are a great way to understand ARIA:

ARIA, Accessibility APIs and coding like you give a damn! – Léonie Watson


Mobile accessibility checklist - Accessibility

Mobile accessibility checklist
==============================

This document provides a concise checklist of accessibility requirements for mobile app developers. It is intended to continuously evolve as more patterns arise.

Color
-----

* Color contrast must comply with WCAG 2.1 AA level requirements:
    + Contrast ratio of 4.5:1 for normal text (less than 18 point or 14 point bold.)
    + Contrast ratio of 3:1 for large text (at least 18 point or 14 point bold.)
* Information conveyed via color must be also available by other means too (underlined text for links, etc.)
Visibility
----------

* Content hiding techniques such as zero opacity, z-index order and off-screen placement must not be used exclusively to handle visibility.
* Everything other than the currently visible screen must be *truly* invisible (especially relevant for single page apps with multiple *cards*):
    + Use the `hidden` attribute or `visibility` or `display` style properties.
    + Unless absolutely unavoidable, `aria-hidden` attribute should not be used.
Focus
-----

* All activatable elements must be focusable:
    + Standard controls such as links, buttons, and form fields are focusable by default.
    + Non-standard controls must have an appropriate ARIA Role assigned to them, such as `button`, `link`, or `checkbox`.
* Focus should be handled in a logical order and consistent manner.
Text equivalents
----------------

* Text equivalent must be provided for every non-strictly presentational non-text element within the app.
    + Use *alt* and *title* where appropriate (read Steve Faulkner's post about Using the HTML title attribute for a good guide.)
    + If the above attributes are not applicable, use appropriate ARIA States and Properties such as `aria-label`, `aria-labelledby`, or `aria-describedby`.
* Images of text must be avoided.
* All user interface components with visible text (or image of text) as labels must have the same text available in the programmatic name of the component. WCAG 2.1: Label in name.
* All form controls must have labels (`<label>` elements) for the benefit of screen reader users.
Handling state
--------------

* Standard controls such as radio buttons and checkboxes are handled by the operating system. However, for other custom controls state changes must be provided via ARIA States such as `aria-checked`, `aria-disabled`, `aria-selected`, `aria-expanded`, and `aria-pressed`.
Orientation
-----------

* Content should not be restricted to a single orientation, such as portrait or landscape, unless essential. WCAG 2.1: Orientation
    + Examples of when an orientation is essential is a piano application or a bank check.
General guidelines
------------------

* An app title must be provided.
* Headings must not break hierarchical structure

```html
<h1>Top level heading</h1>
<h2>Secondary heading</h2>
<h2>Another secondary heading</h2>
<h3>Low level heading</h3>
```

* ARIA Landmark Roles should be used to describe an app or document structure, such as `banner`, `complementary`, `contentinfo`, `main`, `navigation`, `search`.
* For touch events, at least one of the following must be true (WCAG 2.1: Pointer Cancellation):
    + The down-event should not be used to trigger any action
    + The action is triggered on the up event and an option to abort the action before its completion is available or an option to undo the action after its completion
    + The up-event will undo any action that was triggered on a down event
    + It is essential to trigger the action on the down event. For example, playing a game or a piano application.
* Touch targets must be large enough for the user to interact with (see the BBC Mobile Accessibility Guidelines for useful touch target size guidelines).

**Note:** The original version of this document was written by Yura Zenevich.


Multipart labels: Using ARIA for labels with embedded fields inside them - Accessibility

Multipart labels: Using ARIA for labels with embedded fields inside them
========================================================================

Problem
-------

You have a form where you ask your user a question, but the answer is mentioned in the question itself. A classic example we all know from our browser settings is the setting "Delete history after x days". "Delete history after" is to the left of the textbox, x is the number, for example 21, and the word "days" follows the textbox, forming a sentence that is easy to understand.

If you're using a screen reader, have you noticed that, when you go to this setting in Firefox, it tells you "Delete history after 21 days"?, followed by the announcement that you're in a textbox, and that it contains the number 21. Isn't that cool? You do not need to navigate around to find out the unit. "Days" could easily be "months" or "years", and in many ordinary dialogs, there is no way to find this out other than navigating around with screen reviewing commands.

The solution is in an ARIA attribute called `aria-labelledby`. Its parameter is a string that consists of the IDs of the HTML elements you want to concatenate into a single accessible name.

Both `aria-labelledby` and `aria-describedby` are specified on the form element that is to be labelled, for example an `<input>` In both cases, the label for/label control bindings that may also exist are overridden by `aria-labelledby`. If on an HTML page you provide `aria-labelledby`, you should also provide a label for construct to also support older browsers that do not have ARIA support yet. With Firefox 3, your visually impaired users will automatically get better accessibility from the new attribute, but the users of older browsers are not left in the dark this way.

### Example
```

body {
  margin: 1rem;
}
```

```html
<input
 aria-labelledby="labelShutdown shutdownTime shutdownUnit"
 type="checkbox" />

<span id="labelShutdown">Shut down computer after</span>

<input
 aria-labelledby="labelShutdown shutdownTime shutdownUnit"
 id="shutdownTime"
 type="text"
 value="10" />

<span id="shutdownUnit"> minutes</span>
```

A Note for JAWS 8 users
-----------------------

JAWS 8.0 has its own logic to find labels, causing it to always override the accessibleName the textbox of an HTML document gets. With JAWS 8, I have not found a way to make it to accept the label from the example above. But NVDA and Window-Eyes do it just fine, and Orca on Linux also has no problems.

**Note:** TBD: add more compatibility info

Can this be done without ARIA?
------------------------------

Community member Ben Millard has pointed out in a blog post that controls can be embedded in labels as shown in the above example using HTML 4, by embedding the input into the label. Thanks for that info, Ben! It is very useful and shows that some techniques that have been available for years escape even the gurus sometimes. This technique works in Firefox; however, it doesn't currently work in many other browsers, including IE. For labels with embedded form controls, using `aria-labelledby` is still the best approach.


Using ARIA: Roles, states, and properties - Accessibility

Using ARIA: Roles, states, and properties
=========================================

ARIA defines semantics that can be applied to elements, with these divided into **roles** (defining a type of user interface element) and **states** and **properties** that are supported by a role. Authors must assign an ARIA role and the appropriate states and properties to an element during its life-cycle, unless the element already has appropriate ARIA semantics (via use of an appropriate HTML element). Addition of ARIA semantics only exposes extra information to a browser's accessibility API, and does not affect a page's DOM.

Roles
-----

### Widget roles

* `button`
* `checkbox`
* `gridcell`
* `link`
* `menuitem`
* `menuitemcheckbox`
* `menuitemradio`
* `option`
* `progressbar`
* `radio`
* `scrollbar`
* `searchbox`
* `separator` (when focusable)
* `slider`
* `spinbutton`
* `switch`
* `tab`
* `tabpanel`
* `textbox`
* `treeitem`
### Composite roles

The techniques below describe each composite role as well as their required and optional child roles.

* `combobox`
* `grid` (including `row`, `gridcell`, `rowheader`, `columnheader` roles)
* `listbox` (including `option` role)
* `menu`
* `menubar`
* `radiogroup` (see `radio role`)
* `tablist` (including `tab` and `tabpanel` roles)
* `tree`
* `treegrid`
### Document structure roles

* `application`
* `article`
* `cell`
* `columnheader`
* `definition`
* `directory`
* `document`
* `feed`
* `figure`
* `group`
* `heading`
* `img`
* `list`
* `listitem`
* `math`
* `none`
* `note`
* `presentation`
* `row`
* `rowgroup`
* `rowheader`
* `separator`
* `table`
* `term`
* `toolbar`
* `tooltip`
### Landmark roles

* `banner`
* `complementary`
* `contentinfo`
* `form`
* `main`
* `navigation`
* `region`
* `search`
### Live Region Roles

* `alert`
* `log`
* `marquee`
* `status`
* `timer`
### Window Roles

* `alertdialog`
* `dialog`
States and properties
---------------------

### Widget attributes

* `aria-autocomplete`
* `aria-checked`
* `aria-current`
* `aria-disabled`
* `aria-errormessage`
* `aria-expanded`
* `aria-haspopup`
* `aria-hidden`
* `aria-invalid`
* `aria-label`
* `aria-level`
* `aria-modal`
* `aria-multiline`
* `aria-multiselectable`
* `aria-orientation`
* `aria-placeholder`
* `aria-pressed`
* `aria-readonly`
* `aria-required`
* `aria-selected`
* `aria-sort`
* `aria-valuemax`
* `aria-valuemin`
* `aria-valuenow`
* `aria-valuetext`
### Live region attributes

* `aria-live`
* `aria-relevant`
* `aria-atomic`
* `aria-busy`
### Drag & drop attributes

* `aria-dropeffect`
Deprecated
* `aria-grabbed`
Deprecated
### Relationship attributes

* `aria-activedescendant`
* `aria-colcount`
* `aria-colindex`
* `aria-colspan`
* `aria-controls`
* `aria-describedby`
* `aria-details`
* `aria-errormessage`
* `aria-flowto`
* `aria-labelledby`
* `aria-owns`
* `aria-posinset`
* `aria-rowcount`
* `aria-rowindex`
* `aria-rowspan`
* `aria-setsize`
### MicrosoftEdge-specific properties

* `x-ms-aria-flowfrom`
Non-standard


How to file ARIA-related bugs - Accessibility

How to file ARIA-related bugs
=============================

The state of ARIA technology has always depended on the community. If you notice an implementation issue, please take a little time and let the developers know. Here's where to file bugs:

### Screen Readers

| Software | Where to file | Notes |
| --- | --- | --- |
| Freedom Scientific JAWS | JAWS technical support form |  |
| GW Micro Window Eyes | Window-Eyes comments, questions, and feedback |  |
| Non Visual Desktop Access (NVDA) | File NVDA bugs | Discuss NVDA issues |

### Browsers

| Software | Where to file | Notes |
| --- | --- | --- |
| Apple Safari | File WebKit.org bugs |  |
| Google Chrome | File Chromium bugs |  |
| Mozilla Firefox | File Firefox bugs | Use Component: Disability Access APIs |
| Opera | File Opera bugs | Use [ARIA] in the summary field |


ARIA live regions - Accessibility

ARIA live regions
=================

Using JavaScript, it is possible to dynamically change parts of a page without requiring the entire page to reload — for instance, to update a list of search results on the fly, or to display a discreet alert or notification which does not require user interaction. While these changes are usually visually apparent to users who can see the page, they may not be obvious to users of assistive technologies. ARIA live regions fill this gap and provide a way to programmatically expose dynamic content changes in a way that can be announced by assistive technologies.

**Note:** Assistive technologies will announce *dynamic* changes in the content of a live region.
 Including an `aria-live` attribute or a specialized live region `role` (such as `role="alert"`) on the element you want to announce changes to works as long as you add the attribute before the changes occur — either in the original markup, or dynamically using JavaScript.

Live regions
------------

Dynamic content which updates without a page reload is generally either a region or a widget. Simple content changes which are not interactive should be marked as live regions. A live region is explicitly denoted using the `aria-live` attribute.

**`aria-live`**: The `aria-live=POLITENESS_SETTING` is used to set the priority with which screen reader should treat updates to live regions - the possible settings are: `off`, `polite` or `assertive`. The default setting is `off`. This attribute is by far the most important.

Normally, only `aria-live="polite"` is used. Any region which receives updates that are important for the user to receive, but not so rapid as to be annoying, should receive this attribute. The screen reader will speak changes whenever the user is idle.

`aria-live="assertive"` should only be used for time-sensitive/critical notifications that absolutely require the user's immediate attention. Generally, a change to an assertive live region will interrupt any announcement a screen reader is currently making. As such, it can be extremely annoying and disruptive and should only be used sparingly.

As `aria-live="off"` is the assumed default for elements, it should not be necessary to set this explicitly, unless you're trying to suppress the announcement of elements which have an implicit live region role (such as `role="alert"`).

### Basic example: Dropdown box updates useful onscreen information

A website specializing in providing information about planets provides a dropdown box. When a planet is selected from the dropdown, a region on the page is updated with information about the selected planet.

```html
<fieldset>
  <legend>Planet information</legend>
  <label for="planetsSelect">Planet:</label>
  <select id="planetsSelect" aria-controls="planetInfo">
    <option value="">Select a planet…</option>
    <option value="mercury">Mercury</option>
    <option value="venus">Venus</option>
    <option value="earth">Earth</option>
    <option value="mars">Mars</option>
  </select>
  <button id="renderPlanetInfoButton">Go</button>
</fieldset>

<div role="region" id="planetInfo" aria-live="polite">
  <h2 id="planetTitle">No planet selected</h2>
  <p id="planetDescription">Select a planet to view its description</p>
</div>

<p>
  <small>
    Information from
    <a href="https://en.wikipedia.org/wiki/Solar\_System">Wikipedia</a>
  </small>
</p>
```

```js
const PLANETS\_INFO = {
  mercury: {
    title: "Mercury",
    description:
      "Mercury is the smallest and innermost planet in the Solar System. It is named after the Roman deity Mercury, the messenger to the gods.",
  },

  venus: {
    title: "Venus",
    description:
      "Venus is the second planet from the Sun. It is named after the Roman goddess of love and beauty.",
  },

  earth: {
    title: "Earth",
    description:
      "Earth is the third planet from the Sun and the only object in the Universe known to harbor life.",
  },

  mars: {
    title: "Mars",
    description:
      'Mars is the fourth planet from the Sun and the second-smallest planet in the Solar System after Mercury. In English, Mars carries a name of the Roman god of war, and is often referred to as the "Red Planet".',
  },
};

function renderPlanetInfo(planet) {
  const planetTitle = document.querySelector("#planetTitle");
  const planetDescription = document.querySelector("#planetDescription");

  if (planet in PLANETS\_INFO) {
    planetTitle.textContent = PLANETS\_INFO[planet].title;
    planetDescription.textContent = PLANETS\_INFO[planet].description;
  } else {
    planetTitle.textContent = "No planet selected";
    planetDescription.textContent = "Select a planet to view its description";
  }
}

const renderPlanetInfoButton = document.querySelector(
  "#renderPlanetInfoButton",
);

renderPlanetInfoButton.addEventListener("click", (event) => {
  const planetsSelect = document.querySelector("#planetsSelect");
  const selectedPlanet =
    planetsSelect.options[planetsSelect.selectedIndex].value;

  renderPlanetInfo(selectedPlanet);
});
```

As the user selects a new planet, the information in the live region will be announced. Because the live region has `aria-live="polite"`, the screen reader will wait until the user pauses before announcing the update. Thus, moving down in the list and selecting another planet will not announce updates in the live region. Updates in the live region will only be announced for the planet finally chosen.

Here is a screenshot of VoiceOver on Mac announcing the update (via subtitles) to the live region:

![A screenshot of VoiceOver on Mac announcing the update to a live region. Subtitles are shown in the picture.](/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions/web_accessibility_aria_aria_live_regions.png)

Roles with implicit live region attributes
------------------------------------------

Elements with the following `role="…"` values act as live regions by default:

| Role | Description | Compatibility Notes |
| --- | --- | --- |
| log | Chat, error, game or other type of log | To maximize compatibility, add a redundant `aria-live="polite"` when using this role. |
| status | A status bar or area of the screen that provides an updated status of some kind. Screen reader users have a special command to read the current status. | To maximize compatibility, add a redundant `aria-live="polite"` when using this role. |
| alert | Error or warning message that flashes on the screen. Alerts are particularly important for client side validation notices to users. Alert Example. | To maximize compatibility, some people recommend adding a redundant `aria-live="assertive"` when using this role. However, adding both `aria-live` and `role="alert"` causes double speaking issues in VoiceOver on iOS. |
| progressbar | A hybrid between a widget and a live region. Use this with `aria-valuemin`, `aria-valuenow` and `aria-valuemax`. (TBD: add more info here). |  |
| marquee | Text which scrolls, such as a stock ticker. |  |
| timer | Any kind of timer or clock, such as a countdown timer or stopwatch readout. |  |

Additional live region attributes
---------------------------------

Live Regions are well supported. The Paciello Group, in 2014, posted information about the state of the support of Live Regions. Paul J. Adam has researched the support of `aria-atomic` and `aria-relevant` in particular.

1. **`aria-atomic`**: The `aria-atomic=BOOLEAN` is used to set whether or not the screen reader should always present the live region as a whole, even if only part of the region changes. The possible settings are: `false` or `true`. The default setting is `false`.
2. **`aria-relevant`**
 : The `aria-relevant=[LIST_OF_CHANGES]` is used to set what types of changes are relevant to a live region. The possible settings are one or more of: `additions`, `removals`, `text`, `all`. The default setting is: `additions text`.
### Basic examples: `aria-atomic`

As an illustration of `aria-atomic`, consider a site with a simple clock, showing hours and minutes. The clock is updated each minute, with the new remaining time overwriting the current content.

```html
<div id="clock" role="timer" aria-live="polite">
  <span id="clock-hours"></span>
  <span id="clock-mins"></span>
</div>
```

```js
/\* basic JavaScript to update the clock \*/
function updateClock() {
  const now = new Date();
  document.getElementById("clock-hours").textContent = now.getHours();
  document.getElementById("clock-mins").textContent =
    `0${now.getMinutes()}`.substr(-2);
}

/\* first run \*/
updateClock();

/\* update every minute \*/
setInterval(updateClock, 60000);
```

The first time the function executes, the entirety of the string that is added will be announced. On subsequent calls, only the parts of the content that changed compared to the previous content will be announced. For instance, when the clock changes from "17:33" to "17:34", assistive technologies will only announce "34", which won't be very useful to users.

One way around this would be to first clear all the contents of the live region (in this case, set the `innerHTML` of both `<span id="clock-hours">` and `<span id="clock-mins">` to be empty), and then inject the new content. However, this can sometimes be unreliable, as it's dependent on the exact timing of these two updates.

`aria-atomic="true"` ensures that each time the live region is updated, the entirety of the content is announced in full (e.g. "17:34").

```html
<div id="clock" role="timer" aria-live="polite" aria-atomic="true">…</div>
```

Another example of `aria-atomic` - an update/notification made as a result of a user action.

```html
<div id="date-input">
  <label for="year">Year:</label>
  <input type="text" id="year" value="1990" onblur="change(event)" />
</div>

<div id="date-output" aria-atomic="true" aria-live="polite">
  The set year is:
  <span id="year-output">1990</span>
</div>
```

```js
function change(event) {
  const yearOut = document.getElementById("year-output");

  switch (event.target.id) {
    case "year":
      yearOut.innerHTML = event.target.value;
      break;
    default:
      return;
  }
}
```

Without `aria-atomic="true"` the screen reader announces only the changed value of year. With `aria-atomic="true"`, the screen reader announces "The set year is: *changed value*"

### Basic example: `aria-relevant`

With `aria-relevant` you can specify which types of changes/updates to a live region should be announced.

As an example, consider a chat site that wants to display a list of users currently logged in. Rather than just announcing the users that are currently logged in, we also want to trigger an announcement specifically when a user is *removed* from the list. We can achieve this by specifying `aria-relevant="additions removals"`.

```html
<ul id="roster" aria-live="polite" aria-relevant="additions removals">
  <!-- use JavaScript to add and remove users here -->
</ul>
```

Breakdown of ARIA live properties:

* `aria-live="polite"` indicates that the screen reader should wait until the user is idle before presenting updates to the user. This is the most commonly used value, as interrupting the user with "assertive" might interrupt their flow.
* `aria-atomic` is not set (`false` by default) so that only the added or removed users should be spoken and not the entire roster each time.
* `aria-relevant="additions removals"` ensures that both users added or removed to the roster will be spoken.
See also
--------

* ARIA roles


ARIA Screen Reader Implementors Guide - Accessibility

ARIA Screen Reader Implementors Guide
=====================================

Live Regions
------------

This is just a guide. Live region markup is a complex area which is somewhat open to interpretation. The following is intended to provide implementation guidance that respects screen readers developers' need to try different things. The intention is to strike a balance between providing useful guidance on how to use the markup's intended meaning while supporting live regions as an area for screen readers to innovate and compete.

### Interpreting WAI-ARIA live region markup

1. Live changes are hints: in general live region markup is provided by the author as hints, and the assistive technology may allow for global, site or even region-specific settings, as well as heuristics to help with live changes on pages that have no WAI-ARIA hints.
2. Optionally, create a second, additional queue if the user configures a second hardware channel: If there are two channels for presentation (e.g. text to speech and a Braille display), then two queues can be maintained to allow for parallel presentation. The channels could be user configured for presenting live regions based on role or politeness.
3. Busy regions: Any changes in a region marked with aria-busy="true" should not be added to the queue until that attribute is cleared.
4. Politeness (`aria-live` or from role) takes first precedence,: items should be added to the queue based on their politeness level from the aria-live property or inherited from the role (e.g. role="log" is polite by default). Assertive items are first then politeness level. Alternatively, implementations may choose to have a policy of clearing more polite items, e.g. assertive items clear any polite items from the queue.
5. Time takes second precedence: Prioritize items with the same politeness level according to when the event occurs (earlier events come first). Present items of the same politeness level in the order of what occurred first.
6. Atomic (`aria-atomic="true"`) regions with multiple changes should not be presented twice with the same content. As a new event for an atomic region is added to the queue remove an earlier event for the same region. It is probably desirable to have at least a tiny timeout before presenting atomic region changes, in order to avoid presenting the region twice for two changes that occur quickly one after the other.
7. Include labels when presenting changes: if the change occurs in something with a semantic label of some kind, speak the label. This is particularly important for changes in data cells, where the column and row headers provide important contextual information.
### Ideas for Settings and Heuristics

1. Allow for a different voice (in text-to-speech) or other varying presentational characteristics to set live changes apart.
2. When no WAI-ARIA markup is present, automatically present some changes unless the user configures all live changes to off. For example, automatically speak changes that are caused by the user's own input, as part of the context of that input.
3. Allow global settings to turn off the presentation of live changes, present all live changes, use markup, or be "smart" (use heuristics)


ARIA annotations - Accessibility

ARIA annotations
================

WAI-ARIA version 1.3 sees the addition of a set of new features, collectively known as ARIA annotations, which allow the creation of accessible annotations inside web documents. Typical use cases include edit suggestions (i.e. an addition and/or deletion in an editable document), and comments (e.g. an editorial comment related to a part of a document under review).

Below we'll introduce the new features associated with ARIA annotations, and have a look at some code examples that show them in action.

**Note:** You can find all the examples discussed in this article in a demo file at aria-annotations.

ARIA annotations features
-------------------------

The ARIA attributes providing these new abilities are as follows:

* `aria-description=""` — provides a detailed description of an HTML element, as opposed to the brief label provided by `aria-label`.
* `role="insertion"` and `role="deletion"` — semantically denote HTML elements whose contents represent an insertion to or deletion from the overall document. These are semantically equivalent to the HTML `<ins>` and `<del>` elements. Note that these aren't part of the new ARIA annotations features, but they are of central relevance.
* `role="mark"` — semantically denotes HTML elements containing text that is marked/highlighted for reference purposes. This is semantically equivalent to the HTML `<mark>` element.
* `role="suggestion"` — semantically denotes a single proposed change to an editable document. This should be used on an element that wraps a single insertion and deletion (see `role="insertion"` and `role="deletion"` above).
* `role="comment"` — semantically denotes a comment/reaction to some content on the page, or to a previous comment.

To provide a semantic association between the document content being annotated and the annotation, an `aria-details` attribute can be set on the annotated content that contains the ID of the annotated element. `aria-details` has been updated so that it can support multiple IDs — this makes sense, for example you can easily envisage having multiple comments relating to the same bit of text.

ARIA annotation roles and objects are currently exposed in:

* Firefox from version 75 onwards, on Windows and Linux (on macOS, we are first waiting for Apple to define what Safari will expose as Apple-dialect attributes to VoiceOver, and will then follow suit.)
* Chrome from version 81 onwards, currently behind the `#enable-accessibility-expose-aria-annotations` flag (go to `chrome://flags` to enable this.)

Unfortunately, you won't be able to use any of these yet, as screen reader support is currently not there. For the moment, you can see the annotations data being exposed with tools like Firefox Accessibility Inspector. The annotations should just work once screen reader support is added.

Associating annotated elements with their details
-------------------------------------------------

There are a number of different ways in which you can associate UI features with text labels or descriptions for accessibility purposes. It is useful to know when to use each. You'll see examples of most of these later on in the article, but briefly:

* `aria-label=""` can be set on an element to provide a brief descriptive label when it isn't appropriate to have the label actually appearing in the UI, for example a search input in a horizontal nav bar.
* `aria-labelledby=""` can be set on an element and given a value the same as the ID of an element that contains a label for the element. This is useful when the element's label is available in the UI, but for some reason a conventional `<label>` won't work.
* `aria-description=""` is similar to `aria-label=""` in that it accepts a string of text, but is used when you want to give an element a description, in addition to its short label.
* `aria-describedby=""` is analogous to `aria-labelledby=""` in that it accepts an ID reference, but is used when you want to associate the element with a more detailed description, in addition to its short label.
* `aria-details=""` references a more complex sets of details, distinct from simple text descriptions. You can learn more about this in the next section.
### aria-details versus aria-describedby

We have already alluded to the difference between these two above — `aria-describedby` is for textual descriptions, whereas `aria-details` is for more complex sets of details. But what does this actually mean?

`aria-describedby` is appropriate for associating an element with a simple text description, where you don't have much in the way of meaningful semantics contained within. For example:

```html
<p id="description-id">An extended text description of some kind.</p>

<div aria-describedby="description-id">
  <!-- Some kind of UI feature that needs an accessible description -->
</div>
```

`aria-details` is appropriate when linking to descriptions or annotations that are a bit more complex — rather than a simple text string, it might contain multiple bits of semantic information:

```html
<div id="detail-id">
  <h2>A heading</h2>
  <p>An extended text description of some kind…</p>
  <p><time datetime="…">A timestamp</time></p>
</div>

<div aria-details="detail-id">
  <!-- Some kind of UI feature where additional details might be useful -->
</div>
```

This difference becomes apparent when you get to how the content is interpreted in the accessibility layer and presented by screen readers, both in interaction guidance and through the accessible name and description computation.

Content associated via `aria-describedby` becomes part of the accessible description and is flattened into a simple string (lists, links, etc. are not exposed). Generally it is announced after the accessible name. ARIA 1.3 also identifies which roles *disallow* its use (such as `generic`, which maps to `<div>`).

Content associated via `aria-details` is *not* factored into the accessible description computation. A screen reader would ideally make the user aware the content is available and then let the user navigate directly to that content. As such, it can contain rich content. The role of the referenced element (eg: `comment`, `definition`) may affect how a screen reader exposes or references the content. `aria-details` has no restrictions on which roles may use it.

A basic description
-------------------

Simple descriptions basically just involve usage of `aria-description` on an element to provide a description that can't be gotten from the element's text alone. As an example, let's say you have a poll/voting UI widget that shows numbers of votes, but you want to summarize the purpose of the widget in a clear description because the UI does not make it clear:

```html
<section
 aria-description="Choose your favorite fruit — the fruit with the highest number of votes will be added to the lunch options next week.">
  <form>
    <fieldset>
      <legend>
        <p>Pick your favorite fruit:</p>
      </legend>
      <ul>
        <li>
          <label
 >Apple: <input type="radio" name="fruit" value="apple"
 /></label>
        </li>
        <li>
          <label
 >Orange: <input type="radio" name="fruit" value="orange"
 /></label>
        </li>
        <li>
          <label
 >Banana: <input type="radio" name="fruit" value="banana"
 /></label>
        </li>
      </ul>
    </fieldset>
  </form>
</section>
```

If the descriptive text does appear in the UI (it should for this example), you can link the description to the widget using `aria-describedby`, like so:

```html
<p id="fruit-desc">
  Choose your favorite fruit — the fruit with the highest number of votes will
  be added to the lunch options next week.
</p>

<section aria-describedby="fruit-desc">
  <form>
    <fieldset>
      <legend>
        <p>Pick your favorite fruit:</p>
      </legend>
      <ul>
        <li>
          <label
 >Apple: <input type="radio" name="fruit" value="apple"
 /></label>
        </li>
        <li>
          <label
 >Orange: <input type="radio" name="fruit" value="orange"
 /></label>
        </li>
        <li>
          <label
 >Banana: <input type="radio" name="fruit" value="banana"
 /></label>
        </li>
      </ul>
    </fieldset>
  </form>
</section>
```

Insertions and deletions
------------------------

A common wish in online document systems like Google Docs is to be able to track changes, to see what reviewers or editors have suggested as changes to the text, before the managing editor or author accepts or rejects those changes. The semantics for this have long been available in HTML, via the `<ins>` and `<del>` elements:

```html
<p>
  Freida's pet is a <del>black Cat called Luna</del
 ><ins>purple Tyrannosaurus Rex called Tiny</ins>.
</p>
```

With the new additions, you now have new roles available to provide the same semantics, should you be unable to use `<ins>` and `<del>` elements for some reason:

```html
<p>
  Freida's pet is a <span role="deletion">black Cat called Luna</span
 ><span role="insertion">purple Tyrannosaurus Rex called Tiny</span>.
</p>
```

However, this often isn't enough — when you've got a content change like the one above that involves an insertion *and* a deletion, there is no way for a screen reader user to work out if the two are related or not. This is the job of `role="suggestion"`, which should be set on an element wrapping both of them like so:

```html
<p>
  Freida's pet is a
  <span role="suggestion"
 ><span role="deletion">black Cat called Luna</span
 ><span role="insertion">purple Tyrannosaurus Rex called Tiny</span></span
 >.
</p>
```

We could even provide an information box saying who made the suggestion and when, and associate it with the suggestion via `aria-details`:

```html
<p>
  Freida's pet is a
  <span role="suggestion" aria-details="comment-source">
    <span role="deletion">black Cat called Luna</span>
    <span role="insertion">purple Tyrannosaurus Rex called Tiny</span></span
 >.
</p>

<div id="comment-source">
  Suggested by Chris,
  <time datetime="2019-03-30T19:29">March 30 2021, 19:29</time>
</div>
```

Browsers tend to provide a default black strikethrough for deletions, and a black underline for insertions, but you'll probably want to use some more interesting styling of your own, for example:

```css
ins,
[role="insertion"] {
  color: #0c0;
  text-decoration: underline;
}

del,
[role="deletion"] {
  color: red;
  text-decoration: line-through;
}

ins,
[role="insertion"],
del,
[role="deletion"] {
  text-decoration-thickness: 2px;
  background-color: #fee;
  padding: 2px 4px;
  margin: 0 1px;
}
```

Comments
--------

Online document applications also commonly feature commenting systems, and it would be nice to have a way to semantically associate commented content and its comments. ARIA annotations can help us here too.

Let's say we have a comment box like so:

```html
<div role="comment" id="thread-1" data-author="chris">
  <h3>Chris said</h3>
  <p class="comment-text">I really think this could use more cowbell.</p>
  <p><time datetime="2019-03-30T19:29">March 30 2019, 19:29</time></p>
</div>
```

We've used `role="comment"` to mark this up as a comment. To associate the comment with the text being commented, we need to wrap the commented text with an element containing the `aria-details` attribute, the value of which should be the ID of the comment. `<mark>` is a suitable element for this purpose (a comment is a reference annotation), so the annotation could look like this:

```html
<p>
  The last half of the song is a slow-rising crescendo that peaks at the
  <mark aria-details="thread-1">end of the guitar solo</mark>, before fading
  away sharply.
</p>

<div role="comment" id="thread-1" data-author="chris">
  <h3>Chris said</h3>
  <p class="comment-text">I really think this moment could use more cowbell.</p>
  <p><time datetime="2019-03-30T19:29">March 30 2019, 19:29</time></p>
</div>
```

**Note:** If for some reason you can't use the `<mark>` element in your application, you could also use `<span role="mark"></span>`.

Since `aria-details` can now accept multiple IDs, we can associate multiple comments with the same annotation, like so:

```html
<p>
  The last half of the song is a slow-rising crescendo that peaks at the
  <mark aria-details="thread-1 thread-2">end of the guitar solo</mark>, before
  fading away sharply.
</p>

<div role="comment" id="thread-1" data-author="chris">
  <h3>Chris said</h3>
  <p class="comment-text">I really think this moment could use more cowbell.</p>
  <p><time datetime="2019-03-30T19:29">March 30 2019, 19:29</time></p>
</div>

<div role="comment" id="thread-2" data-author="chris">
  <h3>Marcus said</h3>
  <p class="comment-text">
    The guitar solo could do with a touch more chorus, and a slightly lower
    volume.
  </p>
  <p><time datetime="2019-03-29T15:35">March 29 2019, 15:35</time></p>
</div>
```

Nested comments are also possible with ARIA annotations — nest the comments inside one another, like so:

```html
<div role="comment" id="thread-1" data-author="chris">
  <h3>Chris said</h3>
  <p class="comment-text">I really think this moment could use more cowbell.</p>
  <p><time datetime="2019-03-30T19:29">March 30 2019, 19:29</time></p>

  <div role="comment" data-author="marcus">
    <h3>Marcus replied</h3>
    <p class="comment-text">
      I don't know about that. I think the cowbell could distract from the solo.
    </p>
    <p><time datetime="2019-03-30T21:02">March 30 2019, 21:02</time></p>
  </div>
</div>
```


ARIA guides - Accessibility

ARIA guides
===========

 Accessible Rich Internet Applications (**ARIA**) define ways to make the web more accessible to people with disabilities.
 This page lists the guides that you can use to help improve the accessibility of web page features such as tables, forms, and keyboard-navigation.

* Designing accessible forms
* Understanding WAI-ARIA basics
* Creating keyboard-navigable JavaScript widgets
* Using ARIA for labels with embedded fields inside them
* Managing focus in composite widgets (`aria-activedescendant` vs. roving tabindex)
* Testing ARIA
* Displaying accessible tables
See also
--------

The following references are helpful for common accessibility use cases:

* Labeling widgets
* Landmark roles
* ARIA live regions
* HTML Drag and Drop API
* ARIA: presentation role


ARIA states and properties - Accessibility

ARIA states and properties
==========================

This page lists reference pages covering all the WAI-ARIA attributes discussed on MDN.

ARIA attributes enable modifying an element's states and properties as defined in the accessibility tree.

**Note:** ARIA only modifies the accessibility tree, modifying how assistive technology presents the content to your users. ARIA doesn't change anything about an element's function or behavior. When not using semantic HTML elements for their intended purpose and default functionality, you must use JavaScript to manage behavior, focus, and ARIA states.

ARIA attribute types
--------------------

There are 4 categories of ARIA states and properties:

1. ### Widget attributes

    * `aria-autocomplete`
    * `aria-checked`
    * `aria-disabled`
    * `aria-errormessage`
    * `aria-expanded`
    * `aria-haspopup`
    * `aria-hidden`
    * `aria-invalid`
    * `aria-label`
    * `aria-level`
    * `aria-modal`
    * `aria-multiline`
    * `aria-multiselectable`
    * `aria-orientation`
    * `aria-placeholder`
    * `aria-pressed`
    * `aria-readonly`
    * `aria-required`
    * `aria-selected`
    * `aria-sort`
    * `aria-valuemax`
    * `aria-valuemin`
    * `aria-valuenow`
    * `aria-valuetext`
2. ### Live region attributes

    * `aria-busy`
    * `aria-live`
    * `aria-relevant`
    * `aria-atomic`
3. ### Drag-and-Drop attributes

    * `aria-dropeffect`
    * `aria-grabbed`
4. ### Relationship attributes

    * `aria-activedescendant`
    * `aria-colcount`
    * `aria-colindex`
    * `aria-colspan`
    * `aria-controls`
    * `aria-describedby`
    * `aria-description`
    * `aria-details`
    * `aria-errormessage`
    * `aria-flowto`
    * `aria-labelledby`
    * `aria-owns`
    * `aria-posinset`
    * `aria-rowcount`
    * `aria-rowindex`
    * `aria-rowspan`
    * `aria-setsize`
Global ARIA attributes
----------------------

Some states and properties apply to all HTML elements regardless of whether an ARIA role is applied. These are defined as "Global" attributes. Global states and properties are supported by all roles and base markup elements.

Many of the above attributes are global, meaning they can be included on any element unless specifically disallowed:

* `aria-atomic`
* `aria-busy`
* `aria-controls`
* `aria-current`
* `aria-describedby`
* `aria-description`
* `aria-details`
* `aria-disabled`
* `aria-dropeffect`
* `aria-errormessage`
* `aria-flowto`
* `aria-grabbed`
* `aria-haspopup`
* `aria-hidden`
* `aria-invalid`
* `aria-keyshortcuts`
* `aria-label`
* `aria-labelledby`
* `aria-live`
* `aria-owns`
* `aria-relevant`
* `aria-roledescription`

By "specifically disallowed," all the above attributes are global except for the `aria-label` and `aria-labelledby` properties, which are not allowed on elements with role `presentation` nor its synonym `none` role.

States and properties defined on MDN
------------------------------------

The following are the reference pages covering the WAI-ARIA states and properties discussed on MDN.

aria-activedescendantThe `aria-activedescendant` attribute identifies the currently active element when focus is on a `composite` widget, `combobox`, `textbox`, `group`, or `application`.

aria-atomicIn ARIA live regions, the global `aria-atomic` attribute indicates whether assistive technologies such as a screen reader will present all, or only parts of, the changed region based on the change notifications defined by the `aria-relevant` attribute.

aria-autocompleteThe `aria-autocomplete` attribute indicates whether inputting text could trigger display of one or more predictions of the user's intended value for a `combobox`, `searchbox`, or `textbox` and specifies how predictions will be presented if they are made.

aria-braillelabelThe global `aria-braillelabel` property defines a string value that labels the current element, which is intended to be converted into Braille.

aria-brailleroledescriptionThe global `aria-brailleroledescription` attribute defines a human-readable, author-localized abbreviated description for the role of an element intended to be converted into Braille.

aria-busyUsed in ARIA live regions, the global `aria-busy` state indicates an element is being modified and that assistive technologies may want to wait until the changes are complete before informing the user about the update.

aria-checkedThe `aria-checked` attribute indicates the current "checked" state of checkboxes, radio buttons, and other widgets.

aria-colcountThe `aria-colcount` attribute defines the total number of columns in a `table`, `grid`, or `treegrid` when not all columns are present in the DOM.

aria-colindexThe `aria-colindex` attribute defines an element's column index or position with respect to the total number of columns within a `table`, `grid`, or `treegrid`.

aria-colindextextThe `aria-colindextext` attribute defines a human-readable text alternative of the numeric `aria-colindex`.

aria-colspanThe `aria-colspan` attribute defines the number of columns spanned by a cell or gridcell within a `table`, `grid`, or `treegrid`.

aria-controlsThe global `aria-controls` property identifies the element (or elements) whose contents or presence are controlled by the element on which this attribute is set.

aria-currentA non-null `aria-current` state on an element indicates that this element represents the current item within a container or set of related elements.

aria-describedbyThe global `aria-describedby` attribute identifies the element (or elements) that describes the element on which the attribute is set.

aria-descriptionThe global `aria-description` attribute defines a string value that describes or annotates the current element.

aria-detailsThe global `aria-details` attribute identifies the element (or elements) that provide additional information related to the object.

aria-disabledThe `aria-disabled` state indicates that the element is perceivable but disabled, so it is not editable or otherwise operable.

aria-dropeffectThe global `aria-dropeffect` attribute indicates what functions may be performed when a dragged object is released on the drop target.

aria-errormessageThe `aria-errormessage` attribute on an object identifies the element that provides an error message for that object.

aria-expandedThe `aria-expanded` attribute is set on an element to indicate if a control is expanded or collapsed, and whether or not the controlled elements are displayed or hidden.

aria-flowtoThe global `aria-flowto` attribute identifies the next element (or elements) in an alternate reading order of content. This allows assistive technology to override the general default of reading in document source order at the user's discretion.

aria-grabbedThe `aria-grabbed` state indicates an element's "grabbed" state in a drag-and-drop operation.

aria-haspopupThe `aria-haspopup` attribute indicates the availability and type of interactive popup element that can be triggered by the element on which the attribute is set.

aria-hiddenThe `aria-hidden` state indicates whether the element is exposed to an accessibility API.

aria-invalidThe `aria-invalid` state indicates the entered value does not conform to the format expected by the application.

aria-keyshortcutsThe global `aria-keyshortcuts` attribute indicates keyboard shortcuts that an author has implemented to activate or give focus to an element.

aria-labelThe `aria-label` attribute defines a string value that labels an interactive element.

aria-labelledbyThe `aria-labelledby` attribute identifies the element (or elements) that labels the element it is applied to.

aria-levelThe `aria-level` attribute defines the hierarchical level of an element within a structure.

aria-liveThe global `aria-live` attribute 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.

aria-modalThe `aria-modal` attribute indicates whether an element is modal when displayed.

aria-multilineThe `aria-multiline` attribute indicates whether a `textbox` accepts multiple lines of input or only a single line.

aria-multiselectableThe `aria-multiselectable` attribute indicates that the user may select more than one item from the current selectable descendants.

aria-orientationThe `aria-orientation` attribute indicates whether the element's orientation is horizontal, vertical, or unknown/ambiguous.

aria-ownsThe `aria-owns` attribute identifies an element (or elements) in order to define a visual, functional, or contextual relationship between a parent and its child elements when the DOM hierarchy cannot be used to represent the relationship.

aria-placeholderThe `aria-placeholder` attribute defines a short hint (a word or short phrase) intended to help the user with data entry when a form control has no value. The hint can be a sample value or a brief description of the expected format.

aria-posinsetThe `aria-posinset` attribute defines an element's number or position in the current set of listitems or treeitems when not all items are present in the DOM.

aria-pressedThe `aria-pressed` attribute indicates the current "pressed" state of a toggle button.

aria-readonlyThe `aria-readonly` attribute indicates that the element is not editable, but is otherwise operable.

aria-relevantUsed in ARIA live regions, the global `aria-relevant` attribute indicates what notifications the user agent will trigger when the accessibility tree within a live region is modified.

aria-requiredThe `aria-required` attribute indicates that user input is required on the element before a form may be submitted.

aria-roledescriptionThe `aria-roledescription` attribute defines a human-readable, author-localized description for the role of an element.

aria-rowcountThe `aria-rowcount` attribute defines the total number of rows in a table, grid, or treegrid.

aria-rowindexThe `aria-rowindex` attribute defines an element's position with respect to the total number of rows within a table, grid, or treegrid.

aria-rowindextextThe `aria-rowindextext` attribute defines a human-readable text alternative of `aria-rowindex`.

aria-rowspanThe `aria-rowspan` attribute defines the number of rows spanned by a cell or gridcell within a table, grid, or treegrid.

aria-selectedThe `aria-selected` attribute indicates the current "selected" state of various widgets.

aria-setsizeThe `aria-setsize` attribute defines the number of items in the current set of listitems or treeitems when not all items in the set are present in the DOM.

aria-sortThe `aria-sort` attribute indicates if items in a table or grid are sorted in ascending or descending order.

aria-valuemaxThe `aria-valuemax` attribute defines the maximum allowed value for a range widget.

aria-valueminThe `aria-valuemin` attribute defines the minimum allowed value for a range widget.

aria-valuenowThe `aria-valuenow` attribute defines the current value for a `range` widget.

aria-valuetextThe `aria-valuetext` attribute defines the human-readable text alternative of `aria-valuenow` for a range widget.

See also
--------

* Using ARIA: roles, states, and properties


WAI-ARIA Roles - Accessibility

WAI-ARIA Roles
==============

ARIA roles provide semantic meaning to content, allowing screen readers and other tools to present and support interaction with an object in a way that is consistent with user expectations of that type of object. ARIA roles can be used to describe elements that don't natively exist in HTML or exist but don't yet have full browser support.

By default, many semantic elements in HTML have a role; for example, `<input type="radio">` has the "radio" role. Non-semantic elements in HTML do not have a role; `<div>` and `<span>` without added semantics return `null`. The `role` attribute can provide semantics.

ARIA roles are added to HTML elements using `role="role type"`, where *role type* is the name of a role in the ARIA specification. Some roles require the inclusion of associated ARIA states or properties; others are only valid in association with other roles.

For example, `<ul role="tabpanel">` will be announced as a 'tab panel' by screen readers. However, if the tab panel doesn't have nested tabs, the element with the tabpanel role is not in fact a tab panel and accessibility has actually been negatively impacted.

The ARIA states and properties associated with each role are included in the role's pages, with each attribute also having a dedicated page.

ARIA role types
---------------

There are 6 categories of ARIA roles:

### 1. Document structure roles

Document Structure roles are used to provide a structural description for a section of content. Most of these roles should no longer be used as browsers now support semantic HTML element with the same meaning. The roles without HTML equivalents, such as presentation, toolbar and tooltip roles, provide information on the document structure to assistive technologies such as screen readers as equivalent native HTML tags are not available.

* toolbar
* tooltip
* feed
* math
* presentation / none
* note

For most document structure roles, semantic HTML equivalent elements are available and supported. Avoid using:

* application
* article (use `<article>`)
* cell (use `<td>`)
* columnheader (use `<th scope="col">`)
* definition (use `<dfn>`)
* directory
* document
* figure (use `<figure>` instead)
* group
* heading (use h1 through h6)
* img (use `<img>` or `<picture>` instead)
* list (use either `<ul>` or `<ol>` instead)
* listitem (use `<li>` instead)
* meter (use `<meter>` instead)
* row (use the `<tr>` with `<table>`)
* rowgroup (use `<thead>`, `<tfoot>` and `<tbody>`)
* rowheader (use `<th scope="row">`)
* separator (use `<hr>` if it doesn't have focus)
* table (use `<table>`)
* term (use `<dfn>`)

These are included for completeness, but in most cases are rarely, if ever, useful:

* `associationlist`
* `associationlistitemkey`
* `associationlistitemvalue`
* `blockquote`
* `caption`
* `code`
* `deletion`
* `emphasis`
* `insertion`
* `paragraph`
* `strong`
* `subscript`
* `superscript`
* `time`
### 2. Widget roles

The various widget role are used to define common interactive patterns. Similar to the document structure roles, some of these roles duplicate the semantics of native HTML elements that are well supported, and should not be used. The difference between the two lists is that, generally, the widget roles require JavaScript interaction and the document structure roles don't necessarily.

* scrollbar
* searchbox
* separator (when focusable)
* slider
* spinbutton
* switch
* tab
* tabpanel
* treeitem

Avoid using button, checkbox, gridcell, link, menuitem, menuitemcheckbox, menuitemradio, option, progressbar, radio, and textbox, which we've included for completeness. For most, semantic equivalents with accessible interactivity are available and supported. See the individual role documentation for more information.

#### Composite widget roles

* combobox
* menu
* menubar
* tablist
* tree
* treegrid

Avoid using grid, listbox, and radiogroup, which we've included for completeness. See the individual role documentation for more information.

Note that there is also a widget role (`role="widget"`), which is an abstract role and not in the widget role category.

### 3. Landmark roles

Landmark roles provide a way to identify the organization and structure of a web page. By classifying and labeling sections of a page, structural information conveyed visually through layout is represented programmatically. Screen readers use landmark roles to provide keyboard navigation to important sections of a page. Use these sparingly. Too many landmark roles create "noise" in screen readers, making it difficult to understand the overall layout of the page.

* banner (document `<header>`)
* complementary (`<aside>`)
* contentinfo (document `<footer>`)
* form (`<form>`)
* main (`<main>`)
* navigation (`<nav>`)
* region (`<section>`)
* search (`<search>`)
### 4. Live region roles

Live Region roles are used to define elements with content that will be dynamically changed. Sighted users can see dynamic changes when they are visually noticeable. These roles help low vision and blind users know if content has been updated. Assistive technologies, like screen readers, can be made to announce dynamic content changes:

* alert
* log
* marquee
* status
* timer
### 5. Window roles

Window roles define sub-windows to the main document window, within the same window, such as pop up modal dialogs:

* alertdialog
* dialog
### 6. Abstract roles

Abstract roles are only intended for use by browsers to help organize and streamline a document. They should not be used by developers writing HTML markup. Doing so will not result in any meaningful information being conveyed to assistive technologies or to users.

Avoid using command, composite, input, landmark, range, roletype, section, sectionhead, select, structure, widget,and window.

**Note:** Don't use abstract roles in your sites and applications. They are for use by browsers. They are included for reference only.

**Warning:** "Abstract roles are used for the ontology. Authors **MUST NOT** use abstract roles in content." - The WAI-ARIA specification

Roles defined on MDN
--------------------

The following are the reference pages covering the WAI-ARIA roles discussed on MDN.

ARIA: alert roleThe `alert` role is for important, and usually time-sensitive, information. The `alert` is a type of `status` processed as an atomic live region.

ARIA: alertdialog roleThe **alertdialog** role is to be used on modal alert dialogs that interrupt a user's workflow to communicate an important message and require a response.

ARIA: application roleThe `application` role indicates to assistive technologies that an element *and all of its children* should be treated similar to a desktop application, and no traditional HTML interpretation techniques should be used. This role should only be used to define very dynamic and desktop-like web applications. Most mobile and desktop web apps *are not* considered applications for this purpose.

ARIA: article roleThe `article` role indicates a section of a page that could easily stand on its own on a page, in a document, or on a website. It is usually set on related content items such as comments, forum posts, newspaper articles or other items grouped together on one page.

ARIA: banner roleThe `banner` role is for defining a global site header, which usually includes a logo, company name, search feature, and possibly the global navigation or a slogan. It is generally located at the top of the page.

ARIA: button roleThe `button` role is for clickable elements that trigger a response when activated by the user. Adding `role="button"` tells the screen reader the element is a button, but provides no button functionality. Use `button` or `input` with `type="button"` instead.

ARIA: cell roleThe `cell` value of the ARIA *role* attribute identifies an element as being a cell in a tabular container that does not contain column or row header information. To be supported, the cell must be nested in an element with the role of `row`.

ARIA: checkbox roleThe `checkbox` role is for checkable interactive controls. Elements containing `role="checkbox"` must also include the `aria-checked` attribute to expose the checkbox's state to assistive technology.

ARIA: columnheader roleThe `columnheader` value of the ARIA role attribute identifies an element as being a cell in a row contains header information for a column, similar to the native `th` element with column scope.

ARIA: combobox roleThe `combobox` role identifies an element as an `input` that controls another element, such as a `listbox` or `grid`, that can dynamically pop up to help the user set the value of that `input`.

ARIA: command roleThe `command` role defines a widget that performs an action but does not receive input data.

ARIA: comment roleThe `comment` role semantically denotes a comment/reaction to some content on the page, or to a previous comment.

ARIA: complementary roleThe `complementary` landmark role is used to designate a supporting section that relates to the main content, yet can stand alone when separated. These sections are frequently presented as sidebars or call-out boxes. If possible, use the HTML <aside> element instead.

ARIA: composite roleThe `composite` abstract role indicates a widget that may contain navigable descendants or owned children.

ARIA: contentinfo roleThe `contentinfo` role defines a footer, containing identifying information such as copyright information, navigation links, and privacy statements, found on every document within a site. This section is commonly called a footer.

ARIA: definition roleThe `definition` ARIA role indicates the element is a definition of a term or concept.

ARIA: dialog roleThe `dialog` role is used to mark up an HTML based application dialog or window that separates content or UI from the rest of the web application or page. Dialogs are generally placed on top of the rest of the page content using an overlay. Dialogs can be either non-modal (it's still possible to interact with content outside of the dialog) or modal (only the content in the dialog can be interacted with).

ARIA: directory roleThe `directory` role was for a list of references to members of a group, such as a static table of contents.

ARIA: document roleThe `document` role is for focusable content within complex composite widgets or applications for which assistive technologies can switch reading context back to a reading mode.

ARIA: document structural rolesARIA document-structure roles are used to provide a structural description for a section of content.

ARIA: feed roleA `feed` is a dynamic scrollable `list` of `articles` in which articles are added to or removed from either end of the list as the user scrolls. A `feed` enables screen readers to use the browse mode reading cursor to both read and scroll through a stream of rich content that may continue scrolling infinitely by loading more content as the user reads.

ARIA: figure roleThe ARIA `figure` role can be used to identify a figure inside page content where appropriate semantics do not already exist. A figure is generally considered to be one or more images, code snippets, or other content that puts across information in a different way to a regular flow of text.

ARIA: form roleThe `form` role can be used to identify a group of elements on a page that provide equivalent functionality to an HTML form. The form is not exposed as a landmark region unless it has an accessible name.

ARIA: generic roleThe `generic` role creates a nameless container element which has no semantic meaning on its own.

ARIA: grid roleThe grid role is for a widget that contains one or more rows of cells. The position of each cell is significant and can be focused using keyboard input.

ARIA: gridcell roleThe gridcell role is used to make a cell in a grid or treegrid. It is intended to mimic the functionality of the HTML `td` element for table-style grouping of information.

ARIA: group roleThe `group` role identifies a set of user interface objects that is not intended to be included in a page summary or table of contents by assistive technologies.

ARIA: heading roleThe `heading` role defines this element as a heading to a page or section, with the `aria-level` attribute providing for more structure.

ARIA: img roleThe ARIA `img` role can be used to identify multiple elements inside page content that should be considered as a single image. These elements could be images, code snippets, text, emojis, or other content that can be combined to deliver information in a visual manner.

ARIA: input roleThe `input` abstract role is a generic type of widget that allows user input.

ARIA: landmark roleA landmark is an important subsection of a page. The `landmark` role is an abstract superclass for the aria role values for sections of content that are important enough that users will likely want to be able to navigate directly to them.

ARIA: link roleA `link` widget provides an interactive reference to a resource. The target resource can be either external or local; i.e., either outside or within the current page or application.

ARIA: list roleThe ARIA `list` role can be used to identify a list of items. It is normally used in conjunction with the `listitem` role, which is used to identify a list item contained inside the list.

ARIA: listbox roleThe `listbox` role is used for lists from which a user may select one or more items which are static and, unlike HTML `select` elements, may contain images.

ARIA: listitem roleThe ARIA `listitem` role can be used to identify an item inside a list of items. It is normally used in conjunction with the `list` role, which is used to identify a list container.

ARIA: log roleThe `log` role is used to identify an element that creates a live region where new information is added in a meaningful order and old information may disappear.

ARIA: main roleThe `main` landmark role is used to indicate the primary content of a document. The main content area consists of content that is directly related to or expands upon the central topic of a document, or the main function of an application.

ARIA: mark roleThe `mark` role denotes content which is marked or highlighted for reference or notation purposes, due to the content's relevance in the enclosing context.

ARIA: marquee roleA `marquee` is a type of live region containing non-essential information which changes frequently.

ARIA: math roleThe `math` role indicates that the content represents a mathematical expression.

ARIA: menu roleThe `menu` role is a type of composite widget that offers a list of choices to the user.

ARIA: menubar roleA `menubar` is a presentation of `menu` that usually remains visible and is usually presented horizontally.

ARIA: menuitem roleThe `menuitem` role indicates the element is an option in a set of choices contained by a `menu` or `menubar`.

ARIA: menuitemcheckbox roleA `menuitemcheckbox` is a `menuitem` with a checkable state whose possible values are `true`, `false`, or `mixed`.

ARIA: menuitemradio roleA `menuitemradio` is checkable menuitem in a set of elements with the same role, only one of which can be checked at a time.

ARIA: meter roleThe `meter` role is used to identify an element being used as a meter.

ARIA: navigation roleThe `navigation` role is used to identify major groups of links used for navigating through a website or page content.

ARIA: none roleThe `none` role is a synonym for the `presentation` role; they both remove an element's implicit ARIA semantics from being exposed to the accessibility tree.

ARIA: note roleA `note` role suggests a section whose content is parenthetic or ancillary to the main content.

ARIA: option roleThe `option` role is used for selectable items in a `listbox`.

ARIA: presentation roleThe `presentation` role and its synonym `none` remove an element's implicit ARIA semantics from being exposed to the accessibility tree.

ARIA: progressbar roleThe `progressbar` role defines an element that displays the progress status for tasks that take a long time.

ARIA: radio roleThe `radio` role is one of a group of checkable radio buttons, in a `radiogroup`, where no more than a single radio button can be checked at a time.

ARIA: radiogroup roleThe `radiogroup` role is a group of `radio` buttons.

ARIA: range roleThe `range` abstract role is a generic type of structure role representing a range of values.

ARIA: region roleThe **`region`** role is used to identify document areas the author deems significant. It is a generic landmark available to aid in navigation when none of the other landmark roles are appropriate.

ARIA: roletype roleThe **`roletype`** role, an abstract role, is the base role from which all other ARIA roles inherit.

ARIA: row roleAn element with `role="row"` is a row of cells within a tabular structure. A row contains one or more cells, grid cells or column headers, and possibly a row header, within a `grid`, `table` or `treegrid`, and optionally within a `rowgroup`.

ARIA: rowgroup roleAn element with `role="rowgroup"` is a group of rows within a tabular structure. A `rowgroup` contains one or more rows of cells, grid cells, column headers, or row headers within a `grid`, `table` or `treegrid`.

ARIA: rowheader roleAn element with `role="rowheader"` is a cell containing header information for a row within a tabular structure of a `grid`, `table` or `treegrid`.

ARIA: scrollbar roleA `scrollbar` is a graphical object that controls the scrolling of content within a viewing area.

ARIA: search roleThe `search` role is used to identify the search functionality; the section of the page used to search the page, site, or collection of sites.

ARIA: searchbox roleThe `searchbox` role indicates an element is a type of `textbox` intended for specifying search criteria.

ARIA: section roleThe **`section` role**, an abstract role, is a superclass role for renderable structural containment components.

ARIA: sectionhead roleThe **`sectionhead` role**, an abstract role, is superclass role for labels or summaries of the topic of its related section.

ARIA: select roleThe **`select` role**, an abstract role, is superclass role for form widgets that allows the user to make selections from a set of choices.

ARIA: separator roleThe `separator` role indicates the element is a divider that separates and distinguishes sections of content or groups of menuitems. The implicit ARIA role the native thematic break `hr` element is `separator`.

ARIA: slider roleThe `slider` role defines an input where the user selects a value from within a given range.

ARIA: spinbutton roleThe `spinbutton` role defines a type of range that expects the user to select a value from among discrete choices.

ARIA: status roleThe `status` role defines a live region containing advisory information for the user that is not important enough to be an `alert`.

ARIA: structure roleThe `structure` role is for document structural elements.

ARIA: suggestion roleThe `suggestion` role semantically denotes a single proposed change to an editable document. This should be used on an element that wraps an element with an `insertion` role, and one with a `deletion` role.

ARIA: switch roleThe ARIA **`switch`** role is functionally identical to the checkbox role, except that instead of representing "checked" and "unchecked" states, which are fairly generic in meaning, the `switch` role represents the states "on" and "off."

ARIA: tab roleThe ARIA `tab` role indicates an interactive element inside a `tablist` that, when activated, displays its associated `tabpanel`.

ARIA: table roleThe `table` value of the ARIA `role` attribute identifies the element containing the role as having a non-interactive table structure containing data arranged in rows and columns, similar to the native `table` HTML element.

ARIA: tablist roleThe `tablist` role identifies the element that serves as the container for a set of `tabs`. The tab content are referred to as `tabpanel` elements.

ARIA: tabpanel roleThe ARIA `tabpanel` is a container for the resources of layered content associated with a `tab`.

ARIA: term roleThe `term` role can be used for a word or phrase with an optional corresponding `definition`.

ARIA: textbox roleThe `textbox` role is used to identify an element that allows the input of free-form text. Whenever possible, rather than using this role, use an `input` element with type="text", for single-line input, or a `textarea` element for multi-line input.

ARIA: timer roleThe **`timer`** role indicates to assistive technologies that an element is a numerical counter listing the amount of elapsed time from a starting point or the remaining time until an end point. Assistive technologies will not announce updates to a timer as it has an implicit aria-live value of `off`.

ARIA: toolbar roleThe `toolbar` role defines the containing element as a collection of commonly used function buttons or controls represented in a compact visual form.

ARIA: tooltip roleA `tooltip` is a contextual text bubble that displays a description for an element that appears on pointer hover or keyboard focus.

ARIA: tree roleA `tree` is a widget that allows the user to select one or more items from a hierarchically organized collection.

ARIA: treegrid roleThe `treegrid` role identifies an element as being grid whose rows can be expanded and collapsed in the same manner as for a `tree`.

ARIA: treeitem roleA `treeitem` is an item in a `tree`.

ARIA: widget roleThe **`widget`** role, an abstract role, is an interactive component of a graphical user interface (GUI).

ARIA: window roleThe `window` role defines a browser or app window.

See also
--------

* Using ARIA: Roles, States, and Properties
* ARIA states and properties


ARIA: region role - Accessibility

ARIA: region role
=================

The **`region`** role is used to identify document areas the author deems significant. It is a generic landmark available to aid in navigation when none of the other landmark roles are appropriate.

```html
<div role="region" aria-label="Example">
  <!-- region content -->
</div>
```

Description
-----------

 The `region` role is an ARIA landmark role.
 The `region` role should be reserved for sections of content sufficiently important that users will likely want to navigate to the section easily and to have it listed in a summary of the page. A region role is a more generic term, and should only be used if the section needing to be identified is not accurately described by one of the other landmark roles, such as `banner`, `main`, `contentinfo`, `complementary`, or `navigation`.

Every element with a `region` role should include a label that describes the purpose of the content in the region, preferably with an `aria-labelledby` referencing a visible header. If no visible appropriate header is present, `aria-label` should be used.

The `region` landmark role's content should make sense if separated from the main content of the document.

Using the `<section>` element will automatically communicate a section has a role of `region` if it is given an accessible name. Developers should always prefer using the correct semantic HTML element, in this case `<section>`, over using ARIA.

### Associated WAI-ARIA Roles, States, and Properties

`aria-labelledby` or `aria-label`

Use this attribute to label the region. Often, the value of the `aria-labelledby` attribute will be the id of the element used to title the section. If no visible appropriate header is present, `aria-label` should be used.

Examples
--------

```html
<div role="region" aria-labelledby="region-heading">
  <h2 id="region-heading">
    This heading's `id` attribute helps this region have an accessible name
  </h2>
  <!-- region content -->
</div>
```

Accessibility concerns
----------------------

Use sparingly! Landmark roles are intended to be used sparingly, to identify larger overall sections of the document. Using too many landmark roles can create "noise" in screen readers, making it difficult to understand the overall layout of the page.

Only use the `region` role if no other relevant content sectioning element or landmark role applies. If multiple regions exist on a page, it may be worth reinvestigating the page's overall structure.

Best practices
--------------

### Prefer HTML

Using the `<section>` element will automatically communicate that a section has a role of `region` if it is given an accessible name. If at all possible, prefer using `<section>` instead.

### Labeling landmarks

If there is more than one `region` landmark role in a document, provide a unique label for each one. This label will allow an assistive technology user to be able to quickly understand the purpose of each landmark.

```html
<div role="region" aria-labelledby="use-discretion">
  <h3 id="use-discretion">Please use the `region` role with discretion</h3>
  <!-- content -->
</div>

…

<div role="region" aria-labelledby="please-reconsider">
  <h3 id="please-reconsider">Please reconsider your document structure</h3>
  <!-- content -->
</div>
```

In this example, the region's label is being generated by the `aria-labelledby` attribute.

### Scrolling content areas with overflow text

If there is a content area with `tabindex="0"`, add `role="region"` to convey to screen reader users that is a generic region. This is done to allow keyboard-only users to scroll regions with overflow text.

### SVG

`role="region"` can be declared on areas of `<svg>` along with an `aria-label` to allow individual sections of the SVG to be described.

Specifications
--------------

| Specification |
| --- |
| Accessible Rich Internet Applications (WAI-ARIA) # region |
| Unknown specification  |

See also
--------

* The `<section>` element
* region (role): Accessible Rich Internet Applications (WAI-ARIA) 1.1
* ARIA: `banner` role
* ARIA: `main` role
* ARIA: `contentinfo` role
* ARIA: `complementary` role
* ARIA: `navigation` role
* Landmark roles: Using ARIA: Roles, States, and Properties
* Using WAI-ARIA Landmarks – 2013 | The Paciello Group
* Accessible Landmarks | scottohara.me


ARIA: list role - Accessibility

ARIA: list role
===============

The ARIA `list` role can be used to identify a list of items. It is normally used in conjunction with the `listitem` role, which is used to identify a list item contained inside the list.

```html
<div role="list">
  <div role="listitem">List item 1</div>
  <div role="listitem">List item 2</div>
  <div role="listitem">List item 3</div>
</div>
```

Description
-----------

Any content that consists of an outer container with a list of elements inside it can be identified to assistive technologies using the `list` and `listitem` containers respectively. A `list` must have one or more `listitem` children, or, alternatively, have one or more `group`s as children, with each `group` having one or more `listitem`s as children.

There are no hard and fast rules about which elements you should use to mark up the list and list items, but you should make sure that the list items make sense in the context of a list, e.g. a shopping list, recipe steps, driving directions.

**Note:** Best practices dictate using the appropriate semantic HTML elements over ARIA roles to mark up lists and listitems — `<ul>`, `<ol>` and `<li>`. See Best practices for a full example.

### Associated WAI-ARIA Roles, States, and Properties

`listitem` role

A single item in a list or directory. Elements with role listitem can only be found in an element with the role `list` or `group`.

`group` role

A collection of related objects, limited to list items when nested in a list, not important enough to have their own place in a page's table of contents.

Best practices
--------------

Only use `role="list"` and `role="listitem"` if you have to — for example if you don't have control over your HTML but are able to improve accessibility dynamically after the fact with JavaScript.

Unlike the HTML `<ol>` and `<ul>`, the ARIA `list` roles doesn't distinguish between ordered and unordered lists. If at all possible, you should use the appropriate semantic HTML elements to mark up a list (`<ol>` and `<ul>`) and list items (`<li>`). For example, our above example should be rewritten as follows:

```html
<ul>
  <li>List item 1</li>
  <li>List item 2</li>
  <li>List item 3</li>
</ul>
```

or use an ordered list if the order of the list items matters:

```html
<ol>
  <li>List item 1</li>
  <li>List item 2</li>
  <li>List item 3</li>
</ol>
```

**Note:** The ARIA `list` / `listitem` roles don't distinguish between ordered and unordered lists.

As an aside, note that if you are using the semantic HTML elements of `<ol>` or `<ul>` and apply a role of `presentation`, each child `<li>` element inherits the `presentation` role because ARIA requires the `listitem` elements to have the parent `list` element. So, the `<li>` elements are not exposed to assistive technologies, but elements contained inside of those `<li>` elements, including nested lists, are visible to assistive technologies.

**Note:** If you are marking up a list of items that will function as a tabbed interface, you should instead use the `tab`, `tabpanel`, and `tablist` roles.

Specifications
--------------

| Specification |
| --- |
| Accessible Rich Internet Applications (WAI-ARIA) # list |

See also
--------

* The `<ul>` element
* The `<ol>` element
* The `<li>` element
* ARIA: listitem role
* ARIA: group role
* ARIA Lists examples — by Scott O'Hara
* Accessibility Object Model
* ARIA in HTML


ARIA: log role - Accessibility

ARIA: log role
==============

The `log` role is used to identify an element that creates a live region where new information is added in a meaningful order and old information may disappear.

Description
-----------

A log is a type of live region where new information is added in meaningful order and old information may disappear. 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.

In contrast to other types of live region, a log is sequentially ordered and new information is only added to the end of the log. When this role is added to an element, the browser will send out an accessible log event to assistive technology products which can then notify the user about it.

By default, updates contain only the changes to the live region and these are announced when the user is idle. Elements with the role `log` have an implicit `aria-live` value of `polite`. Where the user needs to hear the entire live region upon a change `aria-atomic="true"` should be set. To have announcements made as soon as possible and where the user may be interrupted, `aria-live="assertive"` can be set for more aggressive updates.

### Associated WAI-ARIA roles, states, and properties

`aria-atomic`

Defines whether assistive technologies should present all, or only parts of, the changed region. Elements with the role `log` have an implicit aria-atomic value of `false`.

`aria-live`

Defines when assistive technology should inform the user of updates to content. Elements with the role `log` have an implicit aria-live value of `polite`, meaning screen readers will announce changes inside the log when the user is idle.

`aria-label` and `aria-labelledby`

The `log` is required to have an accessible name. Use `aria-labelledby` if a visible label is present, otherwise use `aria-label`.

Best Practices
--------------

With an area that has scrolling text, such as a stock ticker, the `marquee` role should be used instead.

Specifications
--------------

| Specification |
| --- |
| Accessible Rich Internet Applications (WAI-ARIA) # log |

See Also
--------

* ARIA: `alert` role
* ARIA: `marquee` role
* ARIA: `status` role
* ARIA: `timer` role
* ARIA live regions