ARIA: main role - Accessibility

ARIA: main role
===============

The `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.

```html
<div id="main" role="main">
  <h1>Avocados</h1>
  <!-- main section content -->
</div>
```

This is the main section of a document that discusses avocados. Subsections of this document could discuss their history, the different types, regions where they grow, etc.

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

The `main` role is a navigational landmark role identifying the main content of a document. Landmarks can be used by assistive technology such as screen readers to quickly identify and navigate to large sections of the document.

By classifying and labeling sections of a page, structural information conveyed visually through layout can be represented programmatically. Screen readers use landmark roles to provide keyboard navigation to important sections of a page. For those navigating via landmark roles, the main role is an alternative for "skip to main content" links.

There should only be one `main` landmark role per document.

The `<main>` element has a role of `main`. Developers should use semantic HTML — in this case `<main>` — over using ARIA.

### Associated ARIA roles, states, and properties

`aria-owns`

The `aria-owns` attribute establishes relationships in the accessibility layer that aren't present in the DOM. Documents and applications can be nested in the DOM, which may lead to having more than one main element as DOM descendants. If this is the case, include `aria-owns` to identify the relationship of the main to its document or application ancestor.

`aria-label` or `aria-labelledby`

Identify the accessible name with `aria-labelledby` if a visible header is present. Otherwise, including an `aria-label` can be helpful for orienting assistive technology users, especially in single-page applications where main content changes happen without generating a page load event.

Example
-------

```html
<body>
  <!-- primary navigation -->

  <div role="main">
    <h1>The First Indochina War</h1>
    <!-- article content -->
  </div>

  <!-- sidebar and footer -->
</body>
```

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

### Use only one `main` role per document

The `main` landmark role should only be used once per document.

If a document contains two `main` roles, say updating page content when triggered by JavaScript, the inactive `main` role's presence should be removed from assistive technology via techniques such as toggling the `hidden` attribute.

```html
<main>
  <h1>Active `main` element</h1>
  <!-- content -->
</main>

<main hidden>
  <h1>Hidden `main` element</h1>
  <!-- content -->
</main>
```

It is also helpful to include an accessible name to help orient assistive technology users, especially in single-page applications where main content changes happen without generating a page load event. This can be added with `aria-labelledby` if there is an appropriate name in the content, or `aria-label` if not.

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

### Prefer HTML

Using the `<main>` element will automatically communicate a section has a role of `main`. If at all possible, prefer using it instead.

### Skip navigation

Skip navigation, also known as "skipnav", is a technique that allows an assistive technology user to quickly bypass large sections of repeated content (main navigation, info banners, etc.). This allows the user to access the main content of the page faster.

Adding an `id` attribute to the element with a declaration of `role="main"` allows it to be a target of a skip navigation link users.

```html
<body>
  <a href="#main-content">Skip to main content</a>

  <!-- navigation and header content -->

  <div id="main-content" role="main">
    <!-- main page content -->
  </div>
</body>
```

Which is the equivalent of:

```html
<body>
  <a href="#main-content">Skip to main content</a>

  <!-- navigation and header content -->

  <main id="main-content">
    <!-- main page content -->
  </main>
</body>
```

* WebAIM: "Skip Navigation" Links
Specifications
--------------

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

See also
--------

* The `<main>` element
* Using HTML sections and outlines
* Using WAI-ARIA Landmarks – 2013 | The Paciello Group
* Accessible Landmarks | scottohara.me
* The main element | HTML5 Doctor


ARIA: grid role - Accessibility

ARIA: grid role
===============

The 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.

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

The `grid` role is a composite widget containing a collection of one or more rows with one or more cells where some or all cells in the grid are focusable by using methods of two-dimensional navigation, such as directional arrow keys.

```html
<table role="grid" aria-labelledby="id-select-your-seat">
  <caption id="id-select-your-seat">
    Select your seat
  </caption>
  <tbody role="presentation">
    <tr role="presentation">
      <td></td>
      <th>Row A</th>
      <th>Row B</th>
    </tr>
    <tr>
      <th scope="row">Aisle 1</th>
      <td tabindex="0">
        <button id="1a" tabindex="-1">1A</button>
      </td>
      <td tabindex="-1">
        <button id="1b" tabindex="-1">1B</button>
      </td>
      <!-- More Columns -->
    </tr>
    <tr>
      <th scope="row">Aisle 2</th>
      <td tabindex="-1">
        <button id="2a" tabindex="-1">2A</button>
      </td>
      <td tabindex="-1">
        <button id="2b" tabindex="-1">2B</button>
      </td>
      <!-- More Columns -->
    </tr>
  </tbody>
</table>
```

A grid widget contains one or more rows with one or more cells of thematically related interactive content. While it does not imply a specific visual presentation, it implies a relationship among elements. Uses fall into two categories: presenting tabular information (data grids) and grouping other widgets (layout grids). Even though both data grids and layout grids employ the same ARIA roles, states, and properties, differences in their content and purpose surface factors that are important to consider in keyboard interaction design. See ARIA Authoring Practices Guide for more details.

Cell elements have the role `gridcell`, unless they are a row or column header. Then the elements are `rowheader` and `columnheader`, respectively. Cell elements need to be owned by elements with a `row` role. Rows can be grouped using `rowgroups`.

If the grid is used as an interactive widget, keyboard interactions need to be implemented.

### Associated ARIA roles, states, and properties

#### Roles

treegrid (subclass)

If a grid has columns that can expanded or collapsed, a treegrid can be used.

row

A row inside the grid.

rowgroup

A group containing one or multiple rows.

#### States and properties

aria-level

Indicates the hierarchical level of the grid within other structures.

aria-multiselectable

If `aria-multiselectable` is set to `true`, multiple items in the grid can be selected. The default value is `false`.

aria-readonly

If the user can navigate the grid but not change the value or values of the grid, the `aria-readonly` should be set to `true`. The default value is `false`.

**Note:** For many use cases, an HTML `<table>` element is sufficient as it and the various table elements already include many ARIA roles.

### Keyboard interactions

When a keyboard user encounters a grid, they navigate the rows and columns using the `left`, `right`, `top` and `down` keys. To activate the interactive component, they will use the `return` and `space` keys.

| Key | Action |
| --- | --- |
| `→` | Moves focus one cell to the right. Optionally (layout grids), if focus is on the right-most cell in the row, focus may move to the first cell in the following row. If focus is on the last cell in the grid, focus does not move. |
| `←` | Moves focus one cell to the left. Optionally (layout grids), if focus is on the left-most cell in the row, focus may move to the last cell in the previous row. If focus is on the first cell in the grid, focus does not move. |
| `↓` | Moves focus one cell down. Optionally (layout grids), if focus is on the bottom cell in the column, focus may move to the top cell in the following column. If focus is on the last cell in the grid, focus does not move. |
| `↑` | Moves focus one cell up. Optionally (layout grids), if focus is on the top cell in the column, focus may move to the bottom cell in the previous column. If focus is on the first cell in the grid, focus does not move. |
| `Page Down` | Moves focus down an author-determined number of rows, typically scrolling so the bottom row in the currently visible set of rows becomes one of the first visible rows. If focus is in the last row of the grid, focus does not move. |
| `Page Up` | Moves focus up an author-determined number of rows, typically scrolling so the top row in the currently visible set of rows becomes one of the last visible rows. If focus is in the first row of the grid, focus does not move. |
| `Home` | Moves focus to the first cell in the row that contains focus. |
| `End` | Moves focus to the last cell in the row that contains focus. |
| `ctrl` + `Home` | Moves focus to the first cell in the first row. |
| `ctrl` + `End` | Moves focus to the last cell in the last row. |

If cells, rows, or columns can be selected, the following key combination are commonly used:

| Key combination | Action |
| --- | --- |
| `ctrl` + `Space` | Select the column that contains the focus. |
| `shift` + `Space` | Selects the row that contains the focus. If the grid includes a column with checkboxes to select rows, this key combination can be used to check that box even if the focus is not on the checkbox. |
| `ctrl` + `A` | Selects all cells. |
| `shift` + `→` | Extends selection one cell to the right. |
| `shift` + `←` | Extends selection one cell to the left. |
| `shift` + `↓` | Extends selection one cell down. |
| `shift` + `↑` | Extends selection one cell up. |

Examples
--------

### Calendar example

#### HTML

```html
<table role="grid" aria-labelledby="calendarheader">
  <caption id="calendarheader">
    September 2018
  </caption>
  <thead role="rowgroup">
    <tr role="row">
      <td></td>
      <th role="columnheader" aria-label="Sunday">S</th>
      <th role="columnheader" aria-label="Monday">M</th>
      <th role="columnheader" aria-label="Tuesday">T</th>
      <th role="columnheader" aria-label="Wednesday">W</th>
      <th role="columnheader" aria-label="Thursday">T</th>
      <th role="columnheader" aria-label="Friday">F</th>
      <th role="columnheader" aria-label="Saturday">S</th>
    </tr>
  </thead>
  <tbody role="rowgroup">
    <tr role="row">
      <th scope="row" role="rowheader">Week 1</th>
      <td>26</td>
      <td>27</td>
      <td>28</td>
      <td>29</td>
      <td>30</td>
      <td>31</td>
      <td role="gridcell" tabindex="-1">1</td>
    </tr>
    <tr role="row">
      <th scope="row" role="rowheader">Week 2</th>
      <td role="gridcell" tabindex="-1">2</td>
      <td role="gridcell" tabindex="-1">3</td>
      <td role="gridcell" tabindex="-1">4</td>
      <td role="gridcell" tabindex="-1">5</td>
      <td role="gridcell" tabindex="-1">6</td>
      <td role="gridcell" tabindex="-1">7</td>
      <td role="gridcell" tabindex="-1">8</td>
    </tr>
    <tr role="row">
      <th scope="row" role="rowheader">Week 3</th>
      <td role="gridcell" tabindex="-1">9</td>
      <td role="gridcell" tabindex="-1">10</td>
      <td role="gridcell" tabindex="-1">11</td>
      <td role="gridcell" tabindex="-1">12</td>
      <td role="gridcell" tabindex="-1">13</td>
      <td role="gridcell" tabindex="-1">14</td>
      <td role="gridcell" tabindex="-1">15</td>
    </tr>
    <tr role="row">
      <th scope="row" role="rowheader">Week 4</th>
      <td role="gridcell" tabindex="-1">16</td>
      <td role="gridcell" tabindex="-1">17</td>
      <td role="gridcell" tabindex="-1">18</td>
      <td role="gridcell" tabindex="-1">19</td>
      <td role="gridcell" tabindex="-1">20</td>
      <td role="gridcell" tabindex="-1">21</td>
      <td role="gridcell" tabindex="-1">22</td>
    </tr>
    <tr role="row">
      <th scope="row" role="rowheader">Week 5</th>
      <td role="gridcell" tabindex="-1">23</td>
      <td role="gridcell" tabindex="-1">24</td>
      <td role="gridcell" tabindex="-1">25</td>
      <td role="gridcell" tabindex="-1">26</td>
      <td role="gridcell" tabindex="-1">27</td>
      <td role="gridcell" tabindex="-1">28</td>
      <td role="gridcell" tabindex="-1">29</td>
    </tr>
    <tr role="row">
      <th scope="row" role="rowheader">Week 6</th>
      <td role="gridcell" tabindex="-1">30</td>
      <td>1</td>
      <td>2</td>
      <td>3</td>
      <td>4</td>
      <td>5</td>
      <td>6</td>
    </tr>
  </tbody>
</table>
```

#### CSS

```css
table {
  margin: 0;
  border-collapse: collapse;
  font-variant-numeric: tabular-nums;
}

tbody th,
tbody td {
  padding: 5px;
}

tbody td {
  border: 1px solid #000;
  text-align: right;
  color: #767676;
}

tbody td[role="gridcell"] {
  color: #000;
}

tbody td[role="gridcell"]:hover,
tbody td[role="gridcell"]:focus {
  background-color: #f6f6f6;
  outline: 3px solid blue;
}
```

#### JavaScript

```js
const selectables = document.querySelectorAll('table td[role="gridcell"]');

selectables[0].setAttribute("tabindex", 0);

const trs = document.querySelectorAll("table tbody tr");
let row = 0;
let col = 0;
let maxrow = trs.length - 1;
let maxcol = 0;

trs.forEach((gridrow) => {
  gridrow.querySelectorAll("td").forEach((el) => {
    el.dataset.row = row;
    el.dataset.col = col;
    col++;
  });
  if (col > maxcol) {
    maxcol = col - 1;
  }
  col = 0;
  row++;
});

function moveto(newrow, newcol) {
  const tgt = document.querySelector(
    `[data-row="${newrow}"][data-col="${newcol}"]`,
  );
  if (tgt?.getAttribute("role") === "gridcell") {
    document.querySelectorAll("[role=gridcell]").forEach((el) => {
      el.setAttribute("tabindex", "-1");
    });
    tgt.setAttribute("tabindex", "0");
    tgt.focus();
    return true;
  } else {
    return false;
  }
}

document.querySelector("table").addEventListener("keydown", (event) => {
  const col = parseInt(event.target.dataset.col, 10);
  const row = parseInt(event.target.dataset.row, 10);
  switch (event.key) {
    case "ArrowRight": {
      const newrow = col === 6 ? row + 1 : row;
      const newcol = col === 6 ? 0 : col + 1;
      moveto(newrow, newcol);
      break;
    }
    case "ArrowLeft": {
      const newrow = col === 0 ? row - 1 : row;
      const newcol = col === 0 ? 6 : col - 1;
      moveto(newrow, newcol);
      break;
    }
    case "ArrowDown":
      moveto(row + 1, col);
      break;
    case "ArrowUp":
      moveto(row - 1, col);
      break;
    case "Home": {
      if (event.ctrlKey) {
        let i = 0;
        let result;
        do {
          let j = 0;
          do {
            result = moveto(i, j);
            j++;
          } while (!result);
          i++;
        } while (!result);
      } else {
        moveto(row, 0);
      }
      break;
    }
    case "End": {
      if (event.ctrlKey) {
        let i = maxrow;
        let result;
        do {
          let j = maxcol;
          do {
            result = moveto(i, j);
            j--;
          } while (!result);
          i--;
        } while (!result);
      } else {
        moveto(
          row,
          document.querySelector(
            `[data-row="${event.target.dataset.row}"]:last-of-type`,
          ).dataset.col,
        );
      }
      break;
    }
    case "PageUp": {
      let i = 0;
      let result;
      do {
        result = moveto(i, col);
        i++;
      } while (!result);
      break;
    }
    case "PageDown": {
      let i = maxrow;
      let result;
      do {
        result = moveto(i, col);
        i--;
      } while (!result);
      break;
    }
    case "Enter": {
      console.log(event.target.textContent);
      break;
    }
  }
  event.preventDefault();
});
```

### More examples

* Data Grid Examples
* Layout Grids Examples
* W3C/WAI Tutorial: Tables
Accessibility concerns
----------------------

Even if the keyboard use is properly implemented, some users might not be aware that they have to use the arrow keys. Make sure that the functionality and interaction needed can be best achieved using the grid role.

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

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

See also
--------

* ARIA `composite` role
* ARIA `table` role
* ARIA `treegrid` role
* ARIA `row` role
* ARIA `rowgroup` role
* ARIA: `gridcell` role
* ARIA: `rowheader` role
* ARIA: columnheader role
* HTML `<table>` element
* `aria-level`
* `aria-multiselectable`
* `aria-readonly`


ARIA: toolbar role - Accessibility

ARIA: toolbar role
==================

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

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

A toolbar is a collection of commonly used controls, such as buttons or checkboxes, grouped together in a compact visual form. The `toolbar` role can be used to communicate the presence and purpose of such a grouping to screen reader users and can help reduce the number of tab stops for keyboard users. Only use the `toolbar` role to group 3 or more controls.

The toolbar is commonly a subset of functions found in a `menubar` as a way to reduce user effort. If you have more than one toolbar in a menubar, each toolbar requires a label; which you can include with `aria-labelledby` or `aria-label`.

When creating a toolbar, you need to implement focus management and keyboard interactions within the toolbar, handling when the same keyboard interactions is used both in the toolbar and in included native control. The `Left Arrow` and `Right Arrow` should be used to navigate between the controls within a horizontal tool bar. The `Up Arrow` and `Down Arrow` should be used if the toolbar is vertical — in which case you also want to include the `aria-orientation="vertical"` — or, in a horizontal toolbar, can be reserved for operating controls, such as spin buttons that require vertical arrow keys to operate.

Avoid including controls whose operation requires arrow keys used for toolbar navigation. If you must include such a control, make it the last control in the toolbar. For example, in a horizontal toolbar, a textbox could be included as the last element.

If any of the otherwise interactive elements within the toolbar are temporarily disabled, consider letting them remain focusable so screen reader users can be made aware of their presence.

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

`aria-orientation`

Elements with the role toolbar have an implicit `aria-orientation` value of horizontal.

`aria-labelledby` / `aria-label`

If the toolbar has a visible label, reference it by ID with the `aria-labelledby` attribute. Otherwise, provide an `aria-label`. If there is more than one toolbar in a menu, naming is required.

### Keyboard interactions

Implement focus management so the keyboard tab sequence includes one stop for the toolbar and arrow keys move focus among the controls in the toolbar.

`Tab` and `Shift + Tab`

Move focus into and out of the toolbar. When focus moves into a toolbar:

* If focus is moving into the toolbar for the first time, focus is set on the first control that is not disabled.
* If the toolbar has previously contained focus, focus is optionally set on the control that last had focus. Otherwise, it is set on the first control that is not disabled.

`Home` (Optional)

Moves focus to first element.

`End` (Optional)

Moves focus to last element.

#### Horizontal toolbar

Elements with the role toolbar have an implicit `aria-orientation` value of horizontal. If the toolbar indeed has this orientation, the following keyboard interactions need to be implemented:

`Left Arrow` (For a horizontal toolbar (the default)

Moves focus to the previous control. Optionally, focus movement may wrap from the first element to the last element.

`Right Arrow` (For a horizontal toolbar (the default)

Moves focus to the next control. Optionally, focus movement may wrap from the last element to the first element.

In toolbars with multiple rows of controls, allow the left and right arrows to wraps from row to row, leaving the option of reserving vertical arrow keys for operating controls, such as navigating among radios buttons, or incrementing/decrementing a numeric spinner.

#### Vertical toolbar

If the toolbar is vertical, ensure `aria-orientation="vertical"` is set, and the following keyboard interactions are implemented:

`Down Arrow` (For a horizontal toolbar (the default)

Moves focus to the previous control. Optionally, focus movement may wrap from the first element to the last element.

`Up Arrow` (For a horizontal toolbar (the default)

Moves focus to the next control. Optionally, focus movement may wrap from the last element to the first element.

### Required JavaScript features

Implement focus management so the keyboard tab sequence includes one stop for the toolbar and arrow keys move focus among the controls in the toolbar. When tabbing into the toolbar, focus returns to the control that last had focus.

While the toolbar element itself does not receive focus, focus on movement into, out of, and within the toolbar has to be managed. On load, the first element in the tabbing sequence within the toolbar has `tabindex="0"` with `tabindex="-1"` set on all other focusable elements within the toolbar. Depending on the [keyboard interaction], the element receiving focus gets set to `tabindex="0"` and the element that just lost focus gets switched back to `tabindex="-1"`. Set focus, `element.focus()`, on the element that has `tabindex="0"`. This is called "roving tabindex". A benefit of using roving tabindex to manage focus is that the browser will scroll the newly focused element into view.

If the design calls for a specific element to be focused the next time the user moves focus into the toolbar with `Tab` or `Shift + Tab`, check if that target element has `tabindex="0"` when toolbar loses focus.

When the toolbar has focus within it, provide visual cues. When an element within the toolbar has focus, a visual cue must be included on both the toolbar itself - to help the toolbar supports directional navigation with the arrow keys - and the control that has focus. The CSS pseudoclasses of `:focus` and `:focus-within` can be used to target both elements.

Examples
--------

Toolbar example from W3C, the World Wide Web Consortium

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

Avoid including controls whose operation requires arrow keys used for toolbar navigation (right and left arrows, or top and bottom for vertical toolbars). If you must include such a control, make it the last control in the toolbar. For example, in a horizontal toolbar, a textbox could be included as the last element.

If any of the otherwise interactive elements within the toolbar are disabled, consider letting them remain focusable so screen reader users can be made aware of their presence.

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

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

See Also
--------

* The CSS `:focus` pseudoclass
* The CSS `:focus-within` pseudoclass


ARIA: select role - Accessibility

ARIA: select role
=================

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

**Note:** The `select` role is an abstract role. It is included here for completeness of documentation. It **should not be used** by web authors.

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

The structural `select` role, an abstract role, is superclass role for four form widgets, `listbox`, `menu`, `radiogroup`, and `tree`, which allow users to make selections from a set of choices.

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

Do not use.

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

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

See Also
--------

* ARIA: `composite` role
* ARIA: `group` role
* ARIA: `listbox` role
* ARIA: `menu` role
* ARIA: `radiogroup` role
* ARIA: `tree` role


ARIA: switch role - Accessibility

ARIA: switch role
=================

The 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."

This example creates a widget and assigns the ARIA `switch` role to it.

```html
<button
 type="button"
 role="switch"
 aria-checked="true"
 id="speakerPower"
 class="switch">
  <span aria-hidden="true">off</span>
  <span aria-hidden="true">on</span>
</button>
<label for="speakerPower" class="switch">Speaker power</label>
```

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

The ARIA **`switch`** role is identical to the checkbox role, except instead of being "checked" or "unchecked", it is either "on" or "off". Like the checkbox role, the `aria-checked` attribute is required. The two possible values are `true` and `false`. Unlike an `<input type="checkbox">` or `role="checkbox"`, there is no `indeterminate` or `mixed` state. The `switch` role does not support the value `mixed` for the `aria-checked` attribute; assigning a value of `mixed` to a `switch` instead sets the value to `false`.

Assistive technologies may choose to represent `switch` widgets with a specialized presentation to reflect the notion of an on/off switch.

Since a switch is an interactive control, it must be focusable and keyboard accessible. If the role is applied to a non-focusable element, use the `tabindex` attribute to change this. The expected keyboard shortcut for toggling the value of a switch is the `Space` key. The developer is required to change the value of the `aria-checked` attribute dynamically when the switch is toggled.

### All descendants are presentational

There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. Accessibility APIs do not have a way of representing semantic elements contained in a `switch`. To deal with this limitation, browsers, automatically apply role `presentation` to all descendant elements of any `switch` element as it is a role that does not support semantic children.

For example, consider the following `switch` element, which contains a heading.

```html
<div role="switch"><h3>Title of my switch</h3></div>
```

Because descendants of `switch` are presentational, the following code is equivalent:

```html
<div role="switch"><h3 role="presentation">Title of my switch</h3></div>
```

From the assistive technology user's perspective, the heading does not exist since the previous code snippets are equivalent to the following in the accessibility tree:

```html
<div role="switch">Title of my switch</div>
```

### Associated ARIA roles, states, and properties

`aria-checked` attribute

The `aria-checked` attribute is **required** when using the `switch` role, as it represents the current state of the widget that the `switch` role is applied to. A value of `true` represents the "on" state; `false` represents the "off" state; a value of `mixed` is not supported by the switch role, and is treated as `false`. The default value is `false`.

`aria-readonly` attribute

The `aria-readonly` attribute is supported by the `switch` role. It indicates whether the widget's state is editable by the user. A value of `false` means that the user *can* change the widget's state; a value of `true` means that the user *cannot* change the widget's state. The default value is `false`.

### Required JavaScript features

Handler for click events

When the user clicks on the switch widget, a click event is fired, which must be handled in order to change the state of the widget.

Changing the `aria-checked` attribute

When a click event is fired on the switch widget, the handler must change the value of the `aria-checked` attribute from `true` to `false`, or vice versa.

Possible effects on user agents and assistive technology
--------------------------------------------------------

When the `switch` role is added to an element, the user agent handles it like this:

* The element is exposed to the system's accessibility infrastructure as having the `switch` role.
* When the `aria-checked` attribute's value changes, an accessible event is fired using the system's accessibility API if one is available and it supports the `switch` role.
* All elements that are descendants of an element with the `switch` role applied to it are automatically assigned role `presentation`. This prevents elements that are used to construct the switch from being interacted with individually by assistive technologies. Text in these elements remains visible to the user agent and may be read or otherwise delivered to the user, unless it's expressly hidden using `display: none` or `aria-hidden="true"`.

The assistive technology, if it supports the `switch` role, responds by doing the following:

* Screen readers should announce the element as a switch, optionally providing instructions as to how to activate the switch.

**Note:** There are varying opinions on how assistive technologies should handle this role; the above is a suggested practice and may differ from other sources.

Examples
--------

The following examples should help you understand how to apply and use the `switch` role.

### Adding the switch role in ARIA

This simple example just creates a widget and assigns the ARIA `switch` role to it. The button is styled with an appearance reminiscent of an on/off power switch.

#### HTML

The HTML is fairly simple here. The switch is implemented as a `<button>` element which is initially checked courtesy of its `aria-checked` attribute being set to `"true"`. The switch has two child elements containing the "off" and "on" labels and is followed by a `<label>` identifying the switch.

```html
<button role="switch" aria-checked="true" id="speakerPower" class="switch">
  <span>off</span>
  <span>on</span>
</button>
<label for="speakerPower" class="switch">Speaker power</label>
```

#### JavaScript

This JavaScript code defines and applies a function to handle click events on switch widgets. The function changes the `aria-checked` attribute from `true` to `false`, or vice versa.

```js
document.querySelectorAll(".switch").forEach((theSwitch) => {
  theSwitch.addEventListener("click", handleClickEvent, false);
});

function handleClickEvent(evt) {
  const el = evt.target;

  if (el.getAttribute("aria-checked") === "true") {
    el.setAttribute("aria-checked", "false");
  } else {
    el.setAttribute("aria-checked", "true");
  }
}
```

#### CSS

The purpose of the CSS is to establish a look and feel for the switch that's reminiscent of the power switch paradigm.

```css
button.switch {
  margin: 0;
  padding: 0;
  width: 70px;
  height: 26px;
  border: 2px solid black;
  display: inline-block;
  margin-right: 0.25em;
  line-height: 20px;
  vertical-align: middle;
  text-align: center;
  font:
    12px "Open Sans",
    "Arial",
    serif;
}

button.switch span {
  padding: 0 4px;
  pointer-events: none;
}

[role="switch"][aria-checked="false"] :first-child,
[role="switch"][aria-checked="true"] :last-child {
  background: #262;
  color: #eef;
}

[role="switch"][aria-checked="false"] :last-child,
[role="switch"][aria-checked="true"] :first-child {
  color: #bbd;
}

label.switch {
  font:
    16px "Open Sans",
    "Arial",
    sans-serif;
  line-height: 20px;
  vertical-align: middle;
  user-select: none;
}
```

The most interesting part is probably the use of attribute selectors and the `:first-child` and `:last-child` pseudo-classes to do all the heavy lifting of changing the appearance of the switch based on whether it's on or off.

#### Result

The result looks like this:

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

| Specification |
| --- |
| Accessible Rich Internet Applications (WAI-ARIA) # switch |
| ARIA in HTML # index-aria-switch |

See also
--------

* ARIA: checkbox role
* `<input type="checkbox">`
* `aria-hidden`


ARIA: dialog role - Accessibility

ARIA: dialog role
=================

The `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).

```html
<div
 role="dialog"
 aria-labelledby="dialog1Title"
 aria-describedby="dialog1Desc">
  <h2 id="dialog1Title">Your personal details were successfully updated</h2>
  <p id="dialog1Desc">
    You can change your details at any time in the user account section.
  </p>
  <button>Close</button>
</div>
```

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

A dialog is a descendant window of the primary window of a web application. For HTML pages, the primary application window is the entire web document, i.e., the body element.

Marking up a dialog element with the `dialog` role helps assistive technology identify the dialog's content as being grouped and separated from the rest of the page content. However, adding `role="dialog"` alone is not sufficient to make a dialog accessible. Additionally, the following needs to be done:

* The dialog must be properly labeled
* Keyboard focus must be managed correctly

The sections below describe how these two requirements can be met.

### Labeling

Even though it is not required for the dialog itself to be able to receive focus, it still needs to be labeled. The label given to the dialog will provide contextual information for the interactive controls inside the dialog. In other words, the dialog's label acts like a grouping label for the controls inside it (similar to how a `<legend>` element provides a grouping label for the controls inside a `<fieldset>` element).

If a dialog already has a visible title bar, the text inside that bar can be used to label the dialog itself. The best way to achieve this is by using the `aria-labelledby` attribute to the `role="dialog"` element. Additionally, if the dialog contains additional descriptive text besides the dialog title, this text can be associated with the dialog using the `aria-describedby` attribute. This approach is shown in the code snippet below:

```html
<div
 role="dialog"
 aria-labelledby="dialog1Title"
 aria-describedby="dialog1Desc">
  <h2 id="dialog1Title">Your personal details were successfully updated</h2>
  <p id="dialog1Desc">
    You can change your details at any time in the user account section.
  </p>
  <button>Close</button>
</div>
```

**Note:** Keep in mind that a dialog's title and description text do not have to be focusable in order to be perceived by screen readers operating in a non-virtual mode. The combination of the ARIA dialog role and labeling techniques should make the screen reader announce the dialog's information when focus is moved into it.

### Required JavaScript features

#### Focus management

A dialog has particular requirements for how keyboard focus should be managed:

* Dialogs should always have at least one focusable control. For many dialogs, there will be a button like "Close", "OK" or "Cancel". In addition to the needed control, dialogs can contain any number of focusable elements, even entire forms or other container widgets like tabs.
* When the dialog appears on the screen, keyboard focus (whose control depends upon the dialog's purpose) should be moved to the default focusable control inside the dialog. For dialogs that only provide a basic message, it could be an "OK" button. For dialogs containing a form it could be the first field in the form.
* After the dialog is dismissed, keyboard focus should be moved back to where it was before it moved into the dialog. Otherwise the focus can be dropped to the beginning of the page.
* For most dialogs, the expected behavior is that the dialog's tab order *wraps*, which means that when the user tabs through the focusable elements in the dialog, the first focusable element will be focused after the last one has been reached. In other words, the tab order should be contained within and by the dialog.
* If the dialog can be moved or resized, ensure that these actions must be performable by keyboard users as well as mouse users. Similarly, if a dialog provides special features like toolbars or context menus, these must be reachable and operable by keyboard users as well.
* Dialogs can be modal or non-modal. When a *modal* dialog appears on the screen, it's not possible to interact with any page content outside the dialog. In other words, the main application UI or page content is considered to be temporarily disabled as long as the modal dialog is showing. For *non-modal* dialogs it is still possible to interact with content outside of the dialog while the dialog is showing. Note that for non-modal dialogs there will have to be a global keyboard shortcut that allows focus to be moved between opened dialogs and the main page.
### Associated ARIA roles, states, and properties

`aria-labelledby`

Use this attribute to label the dialog. Often, the value of the `aria-labelledby` attribute will be the id of the element used to title the dialog.

`aria-describedby`

Use this attribute to describe the contents of the dialog.

### Possible effects on user agents and assistive technology

When the `dialog` role is used, the user agent should do the following:

* Expose the element as a dialog in the operating system's accessibility API.

When the dialog is correctly labeled and focus is moved to an element (often an interactive element, such as a button) inside the dialog, screen readers should announce the dialog's accessible role, name and optionally description, along with announcing the focused element.

**Note:** Opinions may differ on how assistive technology should handle this technique, and the order of announcements may differ depending on the assistive technology used. The information provided above is one of those opinions and may change as the specification is defined.

Examples
--------

### A dialog containing a form

```html
<div
 role="dialog"
 aria-labelledby="dialog1Title"
 aria-describedby="dialog1Desc">
  <h2 id="dialog1Title">Subscription Form</h2>
  <p id="dialog1Desc">We will not share this information with third parties.</p>
  <form>
    <p>
      <label for="firstName">First Name</label>
      <input id="firstName" type="text" />
    </p>
    <p>
      <label for="lastName">Last Name</label>
      <input id="lastName" type="text" />
    </p>
    <p>
      <label for="interests">Interests</label>
      <textarea id="interests"></textarea>
    </p>
    <p>
      <input type="checkbox" id="autoLogin" name="autoLogin" />
      <label for="autoLogin">Auto-login?</label>
    </p>
    <p>
      <input type="submit" value="Save Information" />
    </p>
  </form>
</div>
```

#### Working Examples

* jQuery-UI Dialog
### Notes

**Note:** While it is possible to prevent keyboard users from moving focus to elements outside of the dialog, screen reader users may still be able to navigate to that content using their screen reader's virtual cursor.
 It is important for developers to ensure that content outside of the modal dialog is inaccessible to all users while the modal dialog is active.

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

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

Coming soon

See also
--------

* ARIA: alertdialog role
* The HTML `<dialog>` element


ARIA: generic role - Accessibility

ARIA: generic role
==================

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

**Note:** The `generic` role is the implicit role of generic elements used by user agents. It is included here for completeness of documentation. It should not be used by web authors.

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

While ARIA is primarily used to express semantics, there are some elements that shouldn't expose a semantic name to assistive technologies. The `generic` role indicates an element's role is equivalent to that of the non-semantic `<div>` and `<span>` elements.

The `generic` role is intended for use as the implicit role of generic elements in host languages for use by user agents only; not for use by developers. Instead, to remove implicit accessibility semantics, use `presentation` or `none`, the `<div>` and `<span>` elements that have no semantic meaning, or semantic container roles such as `group` to semantically group descendants in a named container.

Like an element with role `presentation`, an element with `role="generic"` can provide a limited number of accessible states and properties for its descendants, such as `aria-live` attributes. However, unlike elements with role `presentation`, `generic` elements are exposed in accessibility APIs so that assistive technologies can gather certain properties such as layout and bounds.

Because the generic role is nameless, the `aria-labelledby` and `aria-label` attributes are prohibited. Because the role is generic, the `aria-roledescription` and `aria-brailleroledescription` attributes are also prohibited.

**Note:** The element with `role="generic"` should not have an accessible name or role description.

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

None. If a global ARIA state and property is set, `generic` or `none` will be ignored, and the implicit role of the element will be used.

Examples
--------

This role is for use by user agents and not by developers. As such, no appropriate example exists.

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

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

See Also
--------

* HTML `<div>` and `<span>` elements
* `presentation` roles such as
* `group` role


ARIA: tree role - Accessibility

ARIA: tree role
===============

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

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

A `tree` widget is a hierarchical list with parent and child nodes that can expand and collapse. Any item in the hierarchy may have child tree items, set with `role="treeitem"`. Tree items that have children can be expanded or collapsed, showing and hiding their children.

An example of a `tree` is a file system selection user interface: a tree view displaying folders and files. Folder items can be expanded to reveal the contents of the folder — which may be files, folders, or both — and collapsed, hiding its contents.

ARIA tree views are navigated primarily with arrow keys on the keyboard instead of the `Tab`. This form of navigation is not common for most browser content, though normal and expected for native applications. For this reason, before creating a tree view, consider alternative options to address the functionality you need.

**Warning:** Tree views use navigation more similar to native applications than to web applications. For this reason, consider alternative options to address the functionality you need before creating a tree view.

### Single and multiple select trees

Trees can be "single-select", allowing users to choose just one item for an action, or "multi-select", where users are able to select more than one item for an action. In multi-select trees, the `tree` has `aria-multiselectable` set to true. Otherwise, `aria-multiselectable` is either set to `false` or the default value of `false` is implied. In both cases, to be keyboard accessible, focus must be managed for all tree descendants.

In some implementations of single-select tree, the focused item also has a selected state; this is known as "selection follows focus". When a single-select tree receives focus, if none of the tree items are selected before the tree receives focus, focus is set on the first node. If a tree item is selected before the tree receives focus, focus is set on the selected tree item. In single-select trees, `aria-selected` is set to `true` for the selected tree items and it is not present on any other tree item in the tree.

In multi-select trees, all selected tree items have `aria-selected="true"` set and all tree item nodes that are selectable but not currently selected have `aria-selected="false"` set. Do not includes the `aria-selected` attribute on tree items that are not selectable.

When a multi-select tree receives focus, if none of the tree items are selected before the tree receives focus, focus is set on the first tree item. If one or more tree items are selected before the tree receives focus, focus is set on the first selected node.

In multi-select trees, the selected state is always independent of the focus. For example, in a typical file system navigator, the user can move focus to select any number of files for an action, such as copy or move. The visual design should make it clear which items are selected and which item has focus.

### Tree hierarchy

In a tree view, the `tree` node is the root node; it can have child, grandchild, and further descendant `treeitem` nodes.

Each element serving as a tree node has role `treeitem`, except for the root tree node which has a role of `tree`. A `tree` does not have a parent `tree` node - it is the root node. If a node is both nested in a tree and has descendant tree items, then it has the role `treeitem` and the `aria-expanded` attribute; `aria-expanded="false"` is set when the node is in a closed state, `aria-expanded="true"` is set when the node is in an open state.

`treeitem` nodes can be direct children of the `tree` root node, nested within a `treeitem` node, or, optionally nested in a `group` element, which, when nested in a `tree` is an expandable collections of treeitem elements.

Do not include `aria-expanded` on end nodes — those without tree item children — as that would incorrectly describe the node as a parent node to assistive technologies.

### DOM placement and presence

All treeitems are contained in or owned by an element with role `tree`. If there are any tree items that are not direct descendants of the `tree` in the markup, include `aria-owns` on the owning tree container to include elements that are not DOM children of the container. These non-child owned elements will appear in the reading order in the sequence they are referenced and after any tree items that are DOM children. Scripts that manage focus need to ensure the visual focus order matches this assistive technology reading order.

If the complete set of available nodes is not present in the DOM due to dynamic loading as the user moves focus in or scrolls the tree, each node has `aria-level`, `aria-setsize`, and `aria-posinset` specified.

### Accessible name

The `tree` must be provided with an accessible name. Either reference a visible label referenced with `aria-labelledby` or specify a label with `aria-label`.

### Menu orientation

Elements with the role `tree` have an implicit `aria-orientation` value of vertical. If the tree element is horizontally oriented, include `aria-orientation="horizontal"`.

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

`role="treeitem"`

An item in a tree.

`role="group"`

An expandable collection of tree items.

`aria-labelledby`

Identifies the element (or elements) that labels the `tree` providing the required accessible name when a visible label is present. Otherwise use `aria-label`.

`aria-label`

Defines a string value that labels the `tree` when no visible label is present.

`aria-orientation`

indicates whether the tree orientation is horizontal or vertical; defaults to `vertical` if omitted.

`aria-multiselectable`

When set to true, indicates the user may select more than one tree item from the tree's current selectable descendants.

### Keyboard interactions

For a vertically oriented `tree`, which is the default orientation:

|  |  |
| --- | --- |
| `Right arrow` | * When focus is on a closed node, opens the node; focus does not move.
* When focus is on an open node, moves focus to the first child node.
* When focus is on an end node (a tree item with no children), does nothing.
 |
| `Left arrow` | * When focus is on an open node, closes the node.
* When focus is on a child node that is also either an end node or a closed node, moves focus to its parent node.
* When focus is on a closed `tree`, does nothing.
 |
| `Down Arrow` | Moves focus to the next node that is focusable without opening or closing a node. |
| `Up Arrow` | Moves focus to the previous node that is focusable without opening or closing a node. |
| `Home` | Moves focus to the first node in the tree without opening or closing a node. |
| `End` | Moves focus to the last node in the tree that is focusable without opening the node. |
| `Enter` | Performs the default action of the currently focused node. For parent nodes, it opens or closes the node. In single-select trees, if the node has no children, selects the current node if not already selected (which is the default action). |
| Type a character\* | * Focus moves to the next node with a name that starts with the typed character.
* If multiple characters are typed in rapid succession, focus moves to the next node with a name that starts with the string of characters typed.
 |
| `\*` (Optional) | Expands all siblings that are at the same level as the current node. |

\* Type-ahead is recommended for all trees, especially for trees with more than 7 root nodes

### Multi-select keyboard interactions

There are two interaction models for multi-select trees: While you can require that users press a modifier key, such as `Shift` or `Control` while navigating the list in order to avoid losing selection states, the model that does not require the user to hold a modifier key is recommended.

#### Recommended multi user select model

|  |  |
| --- | --- |
| `Space` | Toggles the selection state of the focused node. |
| `Shift + Down Arrow` (Optional) | Moves focus to and toggles the selection state of the next node. |
| `Shift + Up Arrow` (Optional) | Moves focus to and toggles the selection state of the previous node. |
| `Shift + Space` (Optional) | Selects contiguous nodes from the most recently selected node to the current node. |
| `Control + Shift + Home` (Optional) | Selects the node with focus and all nodes up to the first node. Optionally, moves focus to the first node. |
| `Control + Shift + End` (Optional) | Selects the node with focus and all nodes down to the last node. Optionally, moves focus to the last node. |
| `Control + A` (Optional) | Selects all nodes in the tree. Optionally, if all nodes are selected, it can also unselect all nodes. |

#### Alternative multi-selection model

The alternative multi-selection model is a modifier key model in which moving focus without holding a modifier key such as `Shift` or `Control` unselects all selected nodes except for the focused node:

|  |  |
| --- | --- |
| `Shift + Down Arrow` | Moves focus to and toggles the selection state of the next node. |
| `Shift + Up Arrow` | Moves focus to and toggles the selection state of the previous node. |
| `Control + Down Arrow` | Without changing the selection state, moves focus to the next node. |
| `Control + Up Arrow` | Without changing the selection state, moves focus to the previous node. |
| `Control + Space` | Toggles the selection state of the focused node. |
| `Shift + Space` (Optional) | Selects contiguous nodes from the most recently selected node to the current node. |
| `Control + Shift + Home` (Optional) | Selects the node with focus and all nodes up to the first node. Optionally, moves focus to the first node. |
| `Control + Shift + End` (Optional) | Selects the node with focus and all nodes down to the last node. Optionally, moves focus to the last node. |
| `Control + A` (Optional) | Selects all nodes in the tree. Optionally, if all nodes are selected, it can also unselect all nodes. |

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

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

See Also
--------


ARIA: status role - Accessibility

ARIA: status role
=================

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

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

A `status` is a type of live region providing advisory information that is not important enough to justify an alert, which would immediately interrupt the announcement of a user's current activity. It is often, but not necessarily, presented as a status bar.

Do not give focus to the status when its content updates. Live regions are meant to inform users of dynamic updates that have occurred in other areas of the current web page, but which do not necessitate interrupting the user's current activity with a change in context. If a situation requires that focus needs to be moved, then using a `status`, or other live region, are likely not appropriate.

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

### 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 `status` have an implicit aria-atomic value of `true`.

`aria-live`

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

`aria-label` or `aria-labelledby`

Some screen readers announce the name of a status element before announcing its contents. If a name is visible, reference it using `aria-labelledby`. Including an `aria-label` provides a method for prefacing the visible content of a status element with text that is not displayed when a screen reader reads the content. Naming a status is not required so if nothing is appropriate both these attributes can be omitted.

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

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

See Also
--------

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


ARIA: application role - Accessibility

ARIA: application role
======================

The `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.

```html
<div role="application" aria-label="…">…</div>
```

By specifying the `application` role, it indicates this `div` element and all of its descendants are to be treated like they are part of a desktop application.

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

The `application` document structure role, indicates to assistive technologies that this part of the web content contains elements that do not conform to any other known HTML element or WAI-ARIA widget. Any sort of special interpretation of HTML structures and widgets should be suspended, and control should be completely handed over to the browser and web application to handle mouse, keyboard, or touch interaction.

In this mode, the web author is completely responsible for handling any and all keyboard input, focus management, and other interactions and cannot assume assistive technologies would do any processing on their end.

If the web application encompassed by the application role contains parts that *should* be treated like normal web content, a role of `document` or `article` should be used to contain such content.

### Background

For historic reasons, especially on Windows, screen readers and some other assistive technologies (AT) have traditionally grabbed the whole web content from the browser at once after it had finished loading. The ATs build their own representation of it that makes the most sense for a visually impaired user to consume the content. This is often referred to as *virtual document*, *browse mode*, or similar terms. The document is streamlined to a single-column view. A keyboard interaction model is generated that is very similar to a word processor where users can read line by line, sentence by sentence, or paragraph by paragraph. The AT will read any semantics like links, headings, form controls, tables, lists, or images.

In addition, a set of so-called *quick navigation keys* has been established over the years that allows visually impaired users to skim through a page via a certain element type. Such elements usually include headings, form fields, lists, tables, links, graphics, or landmark regions.

For all of this to work, ATs intercept almost all keyboard input and consume it themselves, letting nothing through to the browser or other user agent. To be able to interact with a web page, a standard set of widgets is recognized that, when pressing a certain key (usually the `Enter` key) this mode is switched off. The screen reader mode, often called *forms mode* or *focus mode*, lets all keyboard input go through to the browser again. `Escape` is the most common way of switching back to *browse* mode, but when within a specific `application` section, some screen readers may require other keys to purposefully exit this mode. For instance `NUMPAD PLUS` with JAWS.

The `application` role is designed to provide a means for widgets that are not part of the standard set to be accessible for direct interaction in ATs that use both *browse* and *focus* modes for interacting with web content. Most common widgets have expected keyboard interaction behaviors. Because of this, a custom keyboard experience created by a web author would create a confusing experience.

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

`document`, `article`

Used to indicate parts of the application that should be treated as normal web content

`aria-activedescendant`

Used to manage focus inside the application.

`aria-label`

Used to provide the name of the application or purpose of the widget that is being exposed.

`aria-describedby`

Used to indicate the idref of an element that contains additional instructions for navigating or operating this element.

`aria-roledescription`

Used to give the application a more descriptive role text for screen readers to speak. This should be localized.

`aria-disabled`

Indicates that an element is visible but disabled

`aria-errormessage`

A reference to the element that provides the error message for the element on which it is set

`aria-expanded`

If set to `true`, the grouping element owned or controlled by this element is expanded, or `false` if collapsed.

`aria-haspopup`

Indicates there is a popup, such as menu or dialog, that can be triggered by the element.

### Keyboard interactions

Keyboard interaction is completely under the web author's control and can be anything associated with the particular widget being implemented. In a slides application, for example, a widget could be created that uses the arrow keys to position elements on the slide, and uses audio feedback via an ARIA live region to communicate the position and overlap status with other objects. Focus is being managed via *aria-activedescendant*.

The `Tab`, `Space` and `Enter` keys, as well as `Escape`, must be handled by the application. The one exception is if focus is set to a standard widget inside the application that supports keyboard navigation from the browser, for example an input element.

### Required JavaScript features

keyPress

Used to handle keyboard input and control the focus

Click, Touch

Handle as appropriate for your widget as well

Changing attribute values

`aria-activedescendant` is used to manage the focus inside the application container. Set in response to keyboard or other application events that change focus or point of interaction.

>
> **Note** The `application` role does not have a related HTML widget and thus is completely free form. The author of the application must take full responsibility for not letting users get stuck in a focus trap inside something the user cannot exit from. All aspects of interaction, including returning to the regular web content on other parts of the page, must be handled. Use wisely, and cautiously, and remember to test!
>
>
>

Examples
--------

Some prominent web applications that use or have used the application role properly are:

* Google Docs, Sheets and Slides
* CKEditor and TinyMCE WYSIWYG web editors, like the one used on the Mozilla Developer Network
* Some parts of Gmail
Accessibility concerns
----------------------

Improperly using the `application` role can unintentionally take away access from information on a web page, so be very mindful of using it. Think hard on if you actually need it and cannot just use a set of other known widgets to accomplish the same task.

If used, the application role should be added to the lowest common container possible, not on the `<body>` element, for example. Also be sure to test what you have written with assistive technology, to verify it works as intended.

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

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

Precedence order
----------------

Applying the `application` role will cause this and all of the descendant elements of this element to be treated like application content, not web content. Any reading mechanisms assistive technologies may have for web content will not apply.

See also
--------

* If you use the WAI-ARIA role `application`, please do so wisely - blog post by Marco Zehe
* Using the ARIA `application` role - by Léonie Watson


ARIA: row role - Accessibility

ARIA: row role
==============

An 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`.

```html
<div
 role="table"
 aria-label="Populations"
 aria-describedby="country\_population\_desc">
  <div id="country\_population\_desc">World Populations by Country</div>
  <div role="rowgroup">
    <div role="row">
      <span role="columnheader" aria-sort="descending">Country</span>
      <span role="columnheader" aria-sort="none">Population</span>
    </div>
  </div>
  <div role="rowgroup">
    <div role="row">
      <span role="cell">Finland</span>
      <span role="cell">5.5 million</span>
    </div>
    <div role="row">
      <span role="cell">France</span>
      <span role="cell">67 million</span>
    </div>
  </div>
</div>
```

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

The element `role="row"` is a row within a `grid`, `table` or `treegrid`, and optionally within a `rowgroup`, that is a container for one or more `cells`, `gridcells`, `columnheaders`, or `rowheaders` within a static tabular structure. Using native HTML `<tr>` elements, whenever possible, is strongly encouraged.

To create an ARIA row, add `role="row"` to the container element. That row should be nested within a grid, table or treegrid. A group of rows can be nested within a grid, table or treegrid directly, or within a rowgroup in one of those containers. Each row contains child cells. These cells can be of different types, depending on whether they are column or row headers, or grid or regular cells.

A row can contain a number of attributes clarifying the row's role, including `aria-colindex`, `aria-level`, `aria-rowindex`, and `aria-selected`.

If the row is within a treegrid, rows can include the `aria-expanded` attribute, using the attribute to indicate the present status. This is not the case for an ordinary table or grid, in which the `aria-expanded` attribute is not present.

To create an interactive widget that has a tabular structure, use the grid pattern instead. If the interaction provides for the selection state of individual cells, if left to right and top to bottom navigation is provided, or if the user interface allows the rearranging of cell order or otherwise changing individual cell order such as through drag and drop, use grid or treegrid instead.

**Note:** Using the native HTML table element (`<table>`) along with the table row element (`<tr>`) whenever possible is strongly encouraged.

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

#### Context roles

role="rowgroup"

An optional contextual row parent, it establishes a relationship between descendant rows. It is a structural equivalent to the thead, tfoot, and tbody elements in an HTML table element.

role="table"

One of the three possible contexts (along with grid and treegrid) in which you'll find a row, it identifies the row as being part of a non-interactive table structure containing data arranged in rows and columns, similar to the native `<table>` HTML element.

role="grid"

One of the three possible contexts (along with table and treegrid) in which you'll find a row, it identifies the row as being part of a non-interactive table structure containing data arranged in rows and columns, similar to the native `<table>` HTML element.

role="treegrid"

Similar to a grid, but with rows that can be expanded and collapsed in the same manner as for a tree.

#### Descendant roles

role="cell"

A cell in a row within a tabular container.

role="gridcell"

A cell in a row within a grid or treegrid.

role="columnheader"

A header cell that is the structural equivalent of the HTML `<th>` element with a column scope (`<tr scope="col">`). Unlike a plain cell, the columnheader role establishes a relationship between it and all cells in the corresponding column.

role="rowheader"

A header cell that is the structural equivalent of the HTML `<th>` element with a row scope (`<tr scope="row">`). Unlike a plain cell, the rowheader role establishes a relationship between it and all cells in the corresponding row.

#### States and properties

`aria-expanded` state

The `aria-expanded` attribute, which defines the state of the row, can take one of three values, or be omitted:

* `aria-expanded="true`: Row is currently expanded.
* `aria-expanded="false"`: Row is currently collapsed.
* `aria-expanded="undefined"` or the attribute is missing: The row is neither expandable nor collapsible.

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

`aria-selected` state

Only relevant if the row is in an interactive container, such as a grid or treegrid, but not relevant if the row is in a table. The `aria-selected` attribute can take one of three values, or be omitted:

* `aria-selected="true`: Row is currently selected
* `aria-selected="false"`: Row is not currently selected.
* `aria-selected="undefined"` or the attribute is missing: The row is not selectable.

`aria-colindex` attribute

The `aria-colindex` attribute is only needed if columns are hidden from the DOM. It is generally placed on row children, rather than on the row itself. If the columns displayed are contiguous, then it can be placed on the row.

The attribute takes as its value an integer between 1 and the total number of columns within the table, grid or treegrid. When placed on the row, the `aria-colindex` defines an element's column index or position with respect to the total number of columns within a row. For example, in a table with 15 columns, and columns 4, 5, and 6 are in the DOM, `aria-colindex="4"` could be set on every row.

If the set of columns which is present in the DOM is **not** contiguous, or if there are cells spanning more than one row or column, put the `aria-colindex` on all of the children of each row instead of on the row itself.

If all the columns are in the DOM, this attribute is not necessary.

`aria-rowindex` attribute

The `aria-rowindex` attribute is only needed if rows are hidden from the DOM, to indicate which row, in the list of total rows, is being read. The attribute, placed with a unique value on each row, takes as its value an integer between 1 and the total number of rows within the table, grid or treegrid, indicating the position, or index, of each row. For example, if a table has 1,500 rows, but only the header and rows 47 and 52 are in the DOM, `aria-rowindex="1"` would be set on the header row, and `aria-rowindex="47"` and `aria-rowindex="52"` would be set on the 47th and 52nd row, respectively.

If all the rows are present in the DOM, this attribute is not necessary.

### Keyboard Interactions

None

### Required JavaScript features

None. For sortable columns, see the `columnheader` aria role.

**Note:** The first rule of ARIA use is you can use a native feature 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. Employ the HTML `<table>` element instead of the ARIA role of table whenever possible.

Examples
--------

```html
<div
 role="table"
 aria-label="Semantic Elements"
 aria-describedby="semantic\_elements\_table\_desc"
 aria-rowcount="81">
  <div id="semantic\_elements\_table\_desc">
    Semantic Elements to use instead of ARIA's roles
  </div>
  <div role="rowgroup">
    <div role="row">
      <span role="columnheader" aria-sort="none">ARIA Role</span>
      <span role="columnheader" aria-sort="none">Semantic Element</span>
    </div>
  </div>
  <div role="rowgroup">
    <div role="row" aria-rowindex="11">
      <span role="cell">header</span>
      <span role="cell">h1</span>
    </div>
    <div role="row" aria-rowindex="16">
      <span role="cell">header</span>
      <span role="cell">h6</span>
    </div>
    <div role="row" aria-rowindex="18">
      <span role="cell">rowgroup</span>
      <span role="cell">thead</span>
    </div>
    <div role="row" aria-rowindex="24">
      <span role="cell">term</span>
      <span role="cell">dt</span>
    </div>
  </div>
</div>
```

The above is a non-semantic ARIA table with five of 81 rows present in the DOM: One within a table header and four rows within the table body. The header row, alone in a header rowgroup, has two column headers. The columns are sortable, but not currently sorted, as indicated by the `aria-sort` property. The table body is in a separate rowgroup, with four rows currently in the DOM. Because not all the rows are in the DOM, we've included the `aria-rowindex` property on every row.

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

Only use `<table>`, `<tbody>`, `<thead>`, `<tr>`, `<th>`, `<td>`, etc., for data table structure. You can add these ARIA roles to ensure accessibility should the native semantics of the table be removed, such as with CSS. A relevant use case for the ARIA table role is when the native semantics of a table are overridden by CSS's display property, such as by display: grid. In this case, you can use the ARIA table roles to add the semantics back in.

```html
<table
 role="table"
 aria-label="Semantic Elements"
 aria-describedby="semantic\_elements\_table\_desc"
 aria-rowcount="81">
  <caption id="semantic\_elements\_table\_desc">
    Semantic Elements to use instead of ARIA's roles
  </caption>
  <thead role="rowgroup">
    <tr role="row">
      <th role="columnheader" aria-sort="none">ARIA Role</th>
      <th role="columnheader" aria-sort="none">Semantic Element</th>
    </tr>
  </thead>
  <tbody role="rowgroup">
    <tr role="row" aria-rowindex="11">
      <td role="cell">header</td>
      <td role="cell">h1</td>
    </tr>
    <tr role="row" aria-rowindex="16">
      <td role="cell">header</td>
      <td role="cell">h6</td>
    </tr>
    <tr role="row" aria-rowindex="18">
      <td role="cell">rowgroup</td>
      <td role="cell">thead</td>
    </tr>
    <tr role="row" aria-rowindex="24">
      <td role="cell">term</td>
      <td role="cell">dt</td>
    </tr>
  </tbody>
</table>
```

Above is the semantic way of writing a table. The ARIA roles are only necessary if the native semantics of the table, and therefore the table rows, are obliterated, such as via setting the display property to flex or grid.

### Added benefits

none

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

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

See also
--------

* The HTML `<tr>` table row element
* `<table>`
* The `rowgroup` role
* The `table` role
* The `grid` role
* The `treegrid` role
* The `cell` role
* The `gridcell` role
* The `columnheader` role
* The `rowheader` role


ARIA: progressbar role - Accessibility

ARIA: progressbar role
======================

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

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

The `progressbar` range widget indicates that a request has been received and the application is making progress toward completing the requested action.

Authors **may** set aria-valuemin and aria-valuemax to indicate the minimum and maximum progress indicator values. Otherwise, their implicit values follow the same rules as HTML's `<input type="range"`>:

* If `aria-valuemin` is missing or not a number, it defaults to `0` (zero).
* If `aria-valuemax` is missing or not a number, it defaults to `100`.
* The `aria-valuemin` and `aria-valuemax` properties only need to be set for the `progressbar` role when the progress bar's minimum is not `0` or the maximum value is not `100`.
* The read-only `aria-valuenow` should be provided and updated unless the value is `indeterminate`, in which case don't include the attribute. If set, make sure the `aria-valuenow` value is between the minimum and maximum values.

If the `progressbar` role is applied to an HTML `<progress>` element, the accessible name can come from the associated `<label>`. Otherwise use `aria-labelledby` if a visible label is present or `aria-label` if a visible label is not present.

### All descendants are presentational

There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. Accessibility APIs do not have a way of representing semantic elements contained in a `progressbar`. To deal with this limitation, browsers, automatically apply role `presentation` to all descendant elements of any `progressbar` element as it is a role that does not support semantic children.

For example, consider the following `progressbar` element, which contains a heading.

```html
<div role="progressbar"><h3>Title of my progressbar</h3></div>
```

Because descendants of `progressbar` are presentational, the following code is equivalent:

```html
<div role="progressbar">
  <h3 role="presentation">Title of my progressbar</h3>
</div>
```

From the assistive technology user's perspective, the heading does not exist since the previous code snippets are equivalent to the following in the accessibility tree:

```html
<div role="progressbar">Title of my progressbar</div>
```

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

`aria-valuenow`

Only present and required if the value is not indeterminate. Set to a decimal value between `0`, or `aria-valuemin` if present, and `aria-valuemax` indicating the current value of the progress bar.

`aria-valuetext`

Assistive technologies often present the value of `aria-valuenow` as a percentage. If this would not be accurate use this property to make the progress bar value understandable.

`aria-valuemin`

Set to a decimal value representing the minimum value, and less than `aria-valuemax`. If not present, the default value is `0`.

`aria-valuemax`

Set to a decimal value representing the maximum value, and greater than `aria-valuemin`. If not present, the default value is `100`.

`aria-label` or `aria-labelledby`

Defines the string value or identifies the element (or elements) that label the progressbar element providing an accessible name. An accessible name is required.

It is recommended to use a native `<progress>` or `<input type="range">` elements rather than the `progressbar` role. User agents provide a stylize widget for the `<progress>` element based on the current `value` as it relates to the `0`, the minimum value, and the `max` value. When using non-semantic elements, all features of the native semantic element need to be recreated with ARIA attributes, JavaScript and CSS.

Examples
--------

In the example below, the progress bar uses the default values of 0 and 100 for `aria-valuemin` and `aria-valuemax`:

```html
<div>
  <span id="loadinglabel">Loading:</span>
  <span role="progressbar" aria-labelledby="loadinglabel" aria-valuenow="23">
    <svg width="100" height="10">
      <rect height="10" width="100" stroke="black" fill="black" />
      <rect height="10" width="23" fill="white" />
    </svg>
  </span>
</div>
```

Using semantic HTML, this could be written as:

```html
<label for="loadinglabel">Loading:</label>
<progress id="loadinglabel" max="100" value="23"></progress>
```

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

If the progress bar is describing the loading progress of a particular region of a page, include the `aria-describedby` attribute to reference the progress bar's status, and set the `aria-busy` attribute to `true` on the region until it is finished loading.

### Prefer HTML

It is recommended to use a native `<progress>` or `<input type="range">` elements rather than the `progressbar` role.

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

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

See Also
--------

* HTML `<progress>` element
* Other range widgets include:
    + `meter`
    + `scrollbar`
    + `separator` (if focusable)
    + `slider`
    + `spinbutton`


ARIA: alertdialog role - Accessibility

ARIA: alertdialog role
======================

The **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.

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

The `alertdialog` role is used to notify users of urgent information that demands the user's immediate attention. Including `role="alertdialog"` on the element containing the dialog helps assistive technology identify the content as being grouped and separated from the rest of the page content. Examples include error messages that require confirmation and other action confirmation prompts.

As the name implies, `alertdialog` is a mashup of the `dialog` and `alert` roles. `alertdialog` is a type of `dialog` with similar use cases as `alert`, but for when a user response is required.

**Note:** The `alertdialog` role should only be used for alert messages that have associated interactive controls. If an alert dialog only contains static content and has no interactive controls at all, use `alert` instead.

Being a type of dialog, the `dialog` role's states, properties, and keyboard focus requirements are applicable to the `alertdialog` role as well.

Because of its urgent nature, interrupting the user's workflow, alert dialogs must always be modal.

The alert dialog must have at least one focusable control — such as Confirm, Close, and Cancel — and focus must be moved to that control when the alert dialog appears. Alertdialogs can have additional interactive controls such as text fields and checkboxes.

The `alertdialog` role is not to be used as a replacement for other dialogs, including no-confirmation-required `alert` dialogs (`Window.alert()`) and prompts (`Window.prompt()`).

Adding `role="alertdialog"` alone is not sufficient to make an alert dialog accessible. The following also need to be done:

* The alert dialog must be properly labeled
* Keyboard focus must be managed correctly

The `alertdialog` must have an accessible name, defined with `aria-labelledby` or `aria-label`. The alert dialog text must have an accessible description using `aria-describedby`.

Examples
--------

### Example 1: A basic alert dialog

```html
<div
 role="alertdialog"
 aria-labelledby="dialog1Title"
 aria-describedby="dialog1Desc">
  <div role="document" tabindex="0">
    <h2 id="dialog1Title">Your login session is about to expire</h2>
    <p id="dialog1Desc">To extend your session, click the OK button</p>
    <button>OK</button>
  </div>
</div>
```

The code snippet above shows how to mark up an alert dialog that only provides a message and an OK button.

### Example 2: Confirmation dialog with two options

```html
<div
 id="alert\_dialog"
 role="alertdialog"
 aria-modal="true"
 aria-labelledby="dialog\_label"
 aria-describedby="dialog\_desc">
  <h2 id="dialog\_label">Confirmation</h2>
  <div id="dialog\_desc">
    <p>Are you sure you want to delete this image?</p>
    <p>This change can't be undone.</p>
  </div>
  <ul>
    <li>
      <button type="button" onclick="closeThis()">No</button>
    </li>
    <li>
      <button
 type="button"
 aria-controls="form"
 id="delete\_file\_confirm"
 onclick="deleteFile()">
        Yes
      </button>
    </li>
  </ul>
</div>
```

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

`aria-labelledby`

Use this attribute to label the alertdialog. The `aria-labelledby` attribute is generally the id of the element used to title the alertdialog.

`aria-describedby`

Use this attribute to encompass the description of the contents of the alert dialog. The value of the `aria-describedby` attribute is generally the ID of the element containing the alert dialog's messaging, usually coming right after the title.

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

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

See Also
--------

* HTML `<dialog>` element
* The `dialog` role
* The `alert` role
* `aria-modal` attribute
* `Window.alert()`
* `Window.prompt()`


ARIA: listbox role - Accessibility

ARIA: listbox role
==================

The `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.

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

The `listbox` role is used to identify an element that creates a list from which a user may select one or more static items, similar to the HTML `<select>` element. Unlike `<select>`, a listbox can contain images. Each child of a listbox should have a role of option.

It is highly recommended using the HTML select element, or a group of radio buttons if only one item can be selected, or a group of checkboxes if multiple items can be selected, because there is a lot of keyboard interactivity to manage focus for all the descendants, and native HTML elements provide this functionality for you for free.

Elements with the role `listbox` have an implicit `aria-orientation` value of `vertical`.

When a list is tabbed to, the first item in the list will be selected if nothing else already is. Up/down arrows navigate the list, and pressing Shift + Up/Down arrows will move and extend the selection. Typing one or more letters will navigate the list items (same letter goes to each item starting with that, different letters go to the first item starting with that entire string). If the current item has an associated context menu, Shift+F10 will launch that menu. If list items are checkable, Space can be used to toggle checkboxes. For selectable list items, Space toggles their selection, Shift+Space can be used to select contiguous items, Ctrl+Arrow moves without selecting, and Ctrl+Space can be used to select non-contiguous items. It is recommended that a checkbox, link or other method be used to select all items, and Ctrl+A could be used as a shortcut key for this.

When the listbox role is added to an element, or such an element becomes visible, screen readers announce the label and role of the listbox when it gets focus. If an option or item is focused within the list, it gets announced next, followed by an indication of the item's position with the list if the screen reader supports this. As focus moves within the list, the screen reader announces the relevant items.

### Associated ARIA roles, states, and properties

#### Associated Roles

`option` role

One or more nested options are required. All selected options have `aria-selected` set to `true`. All options that are not selected have `aria-selected` set to `false`. If an option is not selectable, omit the `aria-selected`.

`list` role

A section containing `listitem` elements

#### States and Properties

`aria-activedescendant`

Holds the `id` string of the currently active element within the listbox. If that's an option element, then that would be the `id` of the most recently interacted with option, regardless of whether that option has an `aria-selected` value of `true` or not. Takes the value of only one `id`, even in a multiselectable listbox. If the `id` does not refer to a DOM descendant of the listbox, then that `id` must be included among the IDs in the `aria-owns` attribute.

`aria-owns`

This is a space-separated list of element IDs which are not DOM child elements of the listbox. IDs listed here cannot also be listed in `aria-owns` attributes of any other elements.

`aria-multiselectable`

Include and set to `true` if the user can select more than one option. If set to `true`, *every* selectable option should have an `aria-selected` attribute included and set to `true` or `false`. Options which are *not* selectable *should not* have the `aria-selected` attribute. If `false` or omitted, only the currently selected option, if any option is selected, needs the `aria-selected` attribute, and it must be set to `true`.

`aria-required`

A Boolean attribute which indicates that an option with a non-empty string value must be selected.

`aria-readonly`

The user cannot change which options are selected or unselected, but the listbox is otherwise operable.

`aria-label`

A human-readable string value which identifies the listbox. If there's a visible label, then `aria-labelledby` should be used instead to refer to that label.

`aria-labelledby`

Identifies the visible element or elements in a space-separated list of element IDs which identify the listbox. If there's no visible label, then `aria-label` should be used instead to include a label. (Note: "labelled", with two L's, is the correct spelling based on the accessibility API conventions.)

`aria-roledescription`

A human-readable string value which more clearly identifies the role of the listbox. Screen readers will often read this value to the user after reading the label (if there is one), in place of saying "listbox".

### Keyboard interactions

* When a single-select listbox receives focus:
    + If none of the options are selected before the listbox receives focus, the first option receives focus. Optionally, the first option may be automatically selected.
    + If an option is selected before the listbox receives focus, focus is set on the selected option.
* When a multi-select listbox receives focus:
    + If none of the options are selected before the listbox receives focus, focus is set on the first option and there is no automatic change in the selection state.
    + If one or more options are selected before the listbox receives focus, focus is set on the first option in the list that is selected.
* `Down Arrow`
 : Moves focus to the next option. Optionally, in a single-select listbox, selection may also move with focus.
* `Up Arrow`
 : Moves focus to the previous option. Optionally, in a single-select listbox, selection may also move with focus.
* `Home`
 (Optional): Moves focus to first option. Optionally, in a single-select listbox, selection may also move with focus. Supporting this key is strongly recommended for lists with more than five options.
* `End`
 (Optional): Moves focus to last option. Optionally, in a single-select listbox, selection may also move with focus. Supporting this key is strongly recommended for lists with more than five options.
* Type-ahead is recommended for all listboxes, especially those with more than seven options:
    + Type a character: focus moves to the next item with a name that starts with the typed character.
    + Type multiple characters in rapid succession: focus moves to the next item with a name that starts with the string of characters typed.
* **Multiple Selection**: Authors may implement either of two interaction models to support multiple selection: a recommended model that does not require the user to hold a modifier key, such as
 `Shift`
 or
 `Control`
 , while navigating the list or an alternative model that does require modifier keys to be held while navigating in order to avoid losing selection states.
    + Recommended selection model — holding modifier keys is not necessary:
        - `Space`
         : changes the selection state of the focused option .
        - `Shift + Down Arrow`
         (Optional): Moves focus to and toggles the selected state of the next option.
        - `Shift + Up Arrow`
         (Optional): Moves focus to and toggles the selected state of the previous option.
        - `Shift + Space`
         (Optional): Selects contiguous items from the most recently selected item to the focused item.
        - `Control + Shift + Home`
         (Optional): Selects the focused option and all options up to the first option. Optionally, moves focus to the first option.
        - `Control + Shift + End`
         (Optional): Selects the focused option and all options down to the last option. Optionally, moves focus to the last option.
        - `Control + A`
         (Optional): Selects all options in the list. Optionally, if all options are selected, it may also unselect all options.
### Required JavaScript features

#### selecting an option in a single select listbox

When the user selects an option, the following must occur:

1. Deselect the previously selected option, setting the `aria-selected` to `false`, or removing the attribute altogether, changing the appearance of the newly unselected option to appear not selected.
2. Select the newly selected option, setting `aria-selected="true"` on the option and changing the appearance of the newly selected option to appear selected.
3. Update the `aria-activedescendant` value on the listbox to the id of the newly selected option
4. Visually handle the blur, focus, and selected states of the option

#### Toggling the state of an option in a multi select listbox

When the user clicks on an option, hits `Space` when focused on an option, or otherwise toggles the state of an option, the following must occur:

1. Toggle the `aria-selected` state of the currently focused option, changing the state of the `aria-selected` to true if it was false or false if it was true.
2. Change the appearance of the option to reflect its selected state
3. Update the `aria-activedescendant` value on the listbox to the ID of the option the user just interacted with, even if they toggled the option to be unselected.

**Note:** The first rule of ARIA use is you can use a native feature 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. The `<select>` element with descendant `<option>` elements handles all the needed interactions natively.

Examples
--------

### Example 1: A single select listbox that uses `aria-activedescendant`

The snippet below, using `aria-activedescendant`, shows how the listbox role is added directly into the HTML source code.

```html
<p id="listbox1label" role="label">Select a color:</p>
<div
 role="listbox"
 tabindex="0"
 id="listbox1"
 aria-labelledby="listbox1label"
 onclick="return listItemClick(event);"
 onkeydown="return listItemKeyEvent(event);"
 onkeypress="return listItemKeyEvent(event);"
 aria-activedescendant="listbox1-1">
  <div role="option" id="listbox1-1" class="selected" aria-selected="true">
    Green
  </div>
  <div role="option" id="listbox1-2">Orange</div>
  <div role="option" id="listbox1-3">Red</div>
  <div role="option" id="listbox1-4">Blue</div>
  <div role="option" id="listbox1-5">Violet</div>
  <div role="option" id="listbox1-6">Periwinkle</div>
</div>
```

This could have more easily been handled with the native HTML `<select>` and `<label>` elements.

```html
<label for="listbox1">Select a color:</label>
<select id="listbox1">
  <option selected>Green</option>
  <option>Orange</option>
  <option>Red</option>
  <option>Blue</option>
  <option>Violet</option>
  <option>Periwinkle</option>
</select>
```

### More examples

* Scrollable Listbox Example: Single-select listbox that scrolls to reveal more options, similar to HTML `<select>` with `size` attribute greater than one.
* Listbox Example with Grouped Options: Single-select listbox with grouped options, similar to HTML `<select>` with the attribute `size` set to greater than `"1"` and options grouped with `optgroup` elements.
* Example Listboxes with Rearrangeable Options: Examples of both single-select and multi-select listboxes with accompanying toolbars where options can be added, moved, and removed.
Best practices
--------------

* To be keyboard-accessible, authors should manage focus of all descendants of this role.
* It is recommended that authors use different styling for the selection when the list is not focused, e.g. a non-active selection is often shown with a lighter background color.
* If the listbox is not part of another widget, it should have the `aria-labelledby` property set.
* If one or more entries are not DOM children of listbox, additional `aria-*` properties will need to be set (see ARIA Best Practices).
* If there is a valid reason to expand the listbox, the `combobox` role may be more appropriate.
Specifications
--------------

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

See also
--------

* HTML `<select>` element
* HTML `<label>` element
* HTML `<option>` element
* ARIA: `combobox` role
* ARIA: `option` role
* ARIA: `list` role
* ARIA: `listitem` role
* ARIA Best Practices – Listbox
* ARIA Role Model – Listbox