ARIA: table role - Accessibility

ARIA: table role
================

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

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

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

An element with `role="table"` is a static tabular structure with rows containing cells. The cells are not focusable or selectable, though widgets within individual cells of the table can be interactive. Using a native HTML `<table>` element whenever possible is strongly encouraged.

**Warning:** If a table maintains a selection state, has two-dimensional navigation, or allows the user to rearrange cell order use `grid` or `treegrid` instead.

To create an ARIA table, add `role="table"` to the container element. Within that container, each row has `role="row"` set and contains child cells. Each cell has a role of either `columnheader`, `rowheader`, or `cell`. Rows can be children of the table or within a `rowgroup`.

The table caption can be defined via `aria-labelledby` or `aria-label`. All other semantic table elements, such as `<tbody>`, `<thead>`, `<tr>`, `<th>`, and `<td>`, need to be added via associated roles, such as `rowgroup`, `row`, `columnheader`, and `cell`.

If the table contains sortable columns or rows, the `aria-sort` attribute should be added on the header cell element (not the table itself). If any rows or columns are hidden, the `aria-colcount` or `aria-rowcount` should be included indicating the total number of columns or rows, respectively, along with the `aria-colindex` or `aria-rowindex` on each cell. The `aria-colindex` or `aria-rowindex` is set to the position of a cell within the row or column, respectively. If the table includes cells that span multiple rows or multiple columns, then `aria-rowspan` or `aria-colspan` should be included as well. Realize, it is much simpler to use the `<table>` element, along with all the related semantic elements and attributes that are all supported by all assistive technologies.

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 a native HTML table element whenever possible is strongly encouraged.

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

`role="rowgroup"`

An optional child of the table, the row group encapsulates a group of rows, similar to `<thead>`, `<tbody>`, and `<tfoot>`.

`role="row"`

A row within the table, and optionally within a rowgroup, that is a container for one or more cells, columnheaders, or rowheaders.

`aria-describedby` attribute

Takes as its value the id of the element that serves as a description for the table.

`aria-label` attribute

The `aria-label` provides an accessible name for the table.

`aria-colcount` attribute

This attribute is only required if the columns are not present in the DOM all the time. It provides an explicit indication of the number of columns in the full table. Set the value to the total number of columns in the full table. If unknown, set `aria-colcount="-1"`.

`aria-rowcount` attribute

This attribute is only required if the rows are not present in the DOM all the time, such as scrollable tables that reuse rows to minimize the number of DOM nodes. It provides an explicit indication of the number of rows in the full table. Set the value to the total number of rows in the full table. If unknown, set `aria-rowcount="-1"`.

### Keyboard interactions

None

### Required JavaScript features

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

**Note:** The first rule of ARIA use is if 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 part of a table. While the full table has 81 entries, as indicated by the `aria-rowcount` property, only four are currently visible. The columns are sortable, but not currently sorted, as indicated by the `aria-sort` property on the column headers.

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 CSS's display property overrides the native semantics of a table, such as by `display: grid`. In this case, you can use the ARIA table roles to re-add the semantics.

### Added benefits

none

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

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

See also
--------

* HTML table element
* HTML table tutorial
* ARIA: `grid` role


ARIA: form role - Accessibility

ARIA: form role
===============

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

```html
<div role="form" id="contact-info" aria-label="Contact information">
  <!-- form content -->
</div>
```

This is a form that collects and saves a user's contact information.

**Warning:** Use an HTML `<form>` element to contain your form controls, rather than the ARIA `form` role, unless you have a very good reason.
 The HTML `<form>` element is sufficient to tell assistive technologies that there is a form.

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

A `form` landmark identifies a region of content that contains a collection of items and objects that, as a whole, combine to create a form when no other named landmark is appropriate (e.g. `main` or `search`).

**Note:** Using the `<form>` element will automatically communicate a section of content as a `form` landmark, if it is provided an accessible name. Developers should always prefer using the correct semantic HTML element over using ARIA.

Use the HTML `<form>` element if possible. The `<form>` element defines a `form` landmark when it has an accessible name (e.g. `aria-labelledby`, `aria-label` or `title`). Make sure to have a unique label on each form in a document to help users understand the purpose of the form. This label should be visible to all users, not just assistive technology users. Use the `search` landmark instead of the `form` landmark when the form is used for search functionality.

Use the `role="form"` to identify a region of the page; do not use it to identify every form field. Even if you are using the form landmark instead of `<form>`, you are encouraged to use native HTML form controls like `<button>`, `<input>`, `<select>`, and `<textarea>`.

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

No role specific states or properties.

### Keyboard Interactions

No role specific keyboard interactions

### Required JavaScript features

`onsubmit`

The onSubmit event handler handles the event raised when the form is submitted. Anything that is not a `<form>` cannot be submitted, therefore you would have to use JavaScript to build an alternative data submission mechanism, for example with `fetch()`.

Examples
--------

```html
<div role="form" id="send-comment" aria-label="Add a comment">
  <label for="username">Username</label>
  <input
 id="username"
 name="username"
 autocomplete="nickname"
 autocorrect="off"
 type="text" />

  <label for="email">Email</label>
  <input
 id="email"
 name="email"
 autocomplete="email"
 autocapitalize="off"
 autocorrect="off"
 spellcheck="false"
 type="text" />

  <label for="comment">Comment</label>
  <textarea id="comment" name="comment"></textarea>

  <input value="Comment" type="submit" />
</div>
```

It is recommended to use `<form>` instead.

```html
<form id="send-comment" aria-label="Add a comment">…</form>
```

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

### Use sparingly

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

### Inputs are not forms

You do not need to declare `role="form"` on every form element (inputs, text areas, selects, etc.). It should be declared on the HTML element that wraps the form elements. Ideally, use the `<form>` element as the wrapping element and do not declare `role="form"`.

### Search

If a form is used to search, you should use the more specialized `role="search"` value.

### Labeling landmarks

Each `<form>` element and form `role` that needs to be exposed as a landmark must be given an accessible name. This name will allow an assistive technology user to be able to quickly understand the purpose of the form landmark.

Use an `aria-labelledby`, `aria-label` or `title` on the same element that was given the `role="form"` to provide it an accessible name.

#### Using `role="form"`

```html
<div role="form" id="gift-cards" aria-label="Purchase a gift card">
  <!-- form content -->
</div>
```

#### Redundant descriptions

Screen readers will announce the type of role the landmark is. Because of this, you do not need to describe what the landmark is in its label. For example, a declaration of `role="form"` with an of `aria-label="Contact form"` may be announced redundantly as, "contact form form".

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

### Prefer HTML

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

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

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

See also
--------

* The `<form>` element
* The `<legend>` element
* form (role): Accessible Rich Internet Applications (WAI-ARIA) 1.1


ARIA: meter role - Accessibility

ARIA: meter role
================

The `meter` role is used to identify an element being used as a meter.

**Note:** Where possible, it is recommended that you use a native `<meter>` element rather than the `meter` role, as native elements are more widely supported by user agents and assistive technology.

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

A meter is a graphical display of a numeric value within a defined range. For example, showing battery percentage. A meter is not appropriate for values that do not have a meaningful maximum limit. Meters should not be used to indicate progress (for example loading), this should be communicated with the `<progress>` element.

Each element with `role="meter"` must also have one of the following:

* An `aria-label` attribute.
* An `aria-labelledby` attribute pointing to an element with text that describes the meter.
### 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 `meter`. To deal with this limitation, browsers, automatically apply role `presentation` to all descendant elements of any `meter` element as it is a role that does not support semantic children.

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

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

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

```html
<div role="meter"><h3 role="presentation">Title of my meter</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="meter">Title of my meter</div>
```

### Associated ARIA roles, states, and properties

`aria-valuenow`

Set to a decimal value between `aria-valuemin` and `aria-valuemax` indicating the current value of the meter.

`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 meter value understandable.

`aria-valuemin`

Set to a decimal value representing the minimum value, and less than `aria-valuemax`.

`aria-valuemax`

Set to a decimal value representing the maximum value, and greater than `aria-valuemin`.

It is recommended to use a native `<meter>` element rather than the `meter` role. User agents provide a stylize widget for the `<meter>` element based on the current `value` as it relates to the `min` and `max` values. When using non-semantic elements, all features of the native semantic element need to be recreated with ARIA attributes, JavaScript and CSS.

Examples
--------

An example of a meter using `role="meter"`:

```html
<div
 role="meter"
 aria-valuenow="90"
 aria-valuemin="0"
 aria-valuemax="100"
 aria-labelledby="cpu\_usage\_label">
  <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" style="width: 90%">
    <rect x="0" y="0" width="100%" height="100%" fill="currentcolor"></rect>
  </svg>
</div>
```

In the above scenario, when the `aria-valuenow` value updates, the width of the SVG also needs to be updated as can be seen in the W3C working meter example.

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

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

See also
--------

* `<meter>`
* `<progress>`


ARIA: range role - Accessibility

ARIA: range role
================

The `range` abstract role is a generic type of structure role representing a range of values.

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

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

The `range` role is an abstract role. It must not be used by web authors. It is the superclass for structural roles for elements that accept a value within a range of values, including the `meter` role, `progressbar` and `slider`. For these three, consider using the `<meter>` element, the `<progress>` element, and the `<input/range>`, respectively.

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

Do not use.

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

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

See Also
--------

* ARIA: `structure` role
* ARIA: `meter` role
* ARIA: `progressbar` role
* ARIA: `scrollbar` role
* ARIA: `slider` role
* ARIA: `spinbutton` role
* `<input/range>`
* `<meter>`
* `<progress>`


ARIA: roletype role - Accessibility

ARIA: roletype role
===================

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

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

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

 The `roletype` role's properties describe the structural and functional purpose of objects that are assigned this role, or "instances". A role is a concept that can be used to understand and operate instances.
 Note

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

Do not use.

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

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

See Also
--------

* ARIA: `structure` role
* ARIA: `widget` role
* ARIA: `window` role
* The HTML `rel` attribute


ARIA: columnheader role - Accessibility

ARIA: columnheader role
=======================

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

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

An element with `role="columnheader"` nested as a descendant for an element with `role="row"`, is a static tabular structure of a column header cell in a tabular container, either a table or grid, or other chart that needs to show data relationships. To be supported, the columnheader must be nested in an element with the role of `row`.

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

All columnheaders should be nested within a row. Every row, in turn, should be nested within a grid, table, or treegrid, alternatively within a rowgroup nested within one of the above.

`aria-sort`

Only applied to one column header at a time, if any, the `aria-sort` attribute indicates if a column is sorted in the three values of `ascending` or `descending` order, or `none` for not sorted.

### Keyboard interactions

This role does not support any specific keyboard interaction.

### Required JavaScript features

JavaScript is only required if the `aria-sort` attribute is used.

Examples
--------

```html
<table>
  <thead>
    <tr role="row">
      <th role="columnheader" scope="col">
        <button>First Name</button>
      </th>
      <th role="columnheader" scope="col">
        <button>Last Name</button>
      </th>
      <th role="columnheader" scope="col" aria-sort="ascending">
        <button>Company Name</button>
      </th>
      <th role="columnheader" scope="col">
        <button>Job Title</button>
      </th>
    </tr>
  </thead>
  <tbody>
    …
  </tbody>
</table>
```

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

Columnheaders should contain a title or header information for the column.

The first rule of ARIA is: if a native HTML element or attribute has the semantics and behavior you require, use it instead of re-purposing an element and adding an ARIA role, state or property to make it accessible. It is recommended to use the native HTML `<th>` element with the `scope` attribute set `<th scope="col">` instead of a `<div>` or other element. If you use semantic HTML's `<th scope="col">` the role attribute is not required, but can be included as a back up to ensure the table retains its semantics should the default semantics be removed with a CSS display property value.

The `aria-sort` attribute can be added to a `<th scope="col">` even when the ARIA role attribute is not specified.

### Prefer HTML

Columnheader has the same semantics `<th scope="col">`.

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

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

See Also
--------

* `table` role
* `grid` role
* `treegrid` role
* `row` role
* `rowgroup` role
* The `<th>` element
* The `<table>` element
* The `<tr>` element
* The `<td>` element


ARIA: radiogroup role - Accessibility

ARIA: radiogroup role
=====================

The `radiogroup` role is a group of `radio` buttons.

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

Radio groups are collections describing a set of related `radio` options. A `radiogroup` is a type of `select` list that can only have a single entry, or `radio`, checked at any one time.

When using HTML's native input radio button, `<input type="radio">`, the radio buttons are grouped when each of input radio buttons in the group is given the same `name`. Once a group of same-named input radio buttons is established, selecting any input radio button in that group automatically deselects any currently-selected input radio button in the same group. While this will associate the radio buttons together, to expose a grouping of radio buttons as a `radiogroup` explicitly set the ARIA role.

It is recommended to create radio groups by using same-named HTML input radio buttons, but, if you must use ARIA roles and attributes instead of semantic HTML form controls, custom `radio` buttons can and should act like native HTML radio input buttons.

When using non-semantic elements as radio buttons, you must ensure your users can only select one radio button from the group at a time. When one item in the group is checked, having their `aria-checked` attribute set to `true`, the previously checked item becomes unchecked, with its `aria-checked` attribute becoming `false`. The `aria-checked` attribute is set on the associated `radio` roles, not on the `radiogroup` itself.

Some `radiogroup` implementations initialize the set with all buttons in the unchecked state. Once a `radio` in a `radiogroup` is checked, it is generally not possible to return to an all-unchecked state.

The `radiogroup` must have an accessible name either by a visible label referenced by `aria-labelledby` or has a label specified with `aria-label`. If elements provide additional information about the radio group, those elements are referenced by the `radiogroup` element with the `aria-describedby` property.

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

`radio` role

One of a group of checkable buttons, in a `radiogroup`, where no more than one of the buttons can be checked at a time.

`aria-labelledby` / `aria-label`

The `radiogroup` must have an accessible name either by a visible label referenced by `aria-labelledby` or has a label specified with `aria-label`.

`aria-describedby`

Reference to elements providing additional information about the `radiogroup`

`aria-required`

Indicates that one `radio` within the group must have `aria-checked="true"` set before the form may be submitted. The required state is specified on the `radiogroup` element rather than one of the `radio` elements, unlike when using HTML radio buttons where the `required` attribute is set directly on one or more radio `<input>` elements.

`aria-errormessage`

Identifies the element that provides an error message for the `radiogroup`, if there is an error. That message should be hidden while not relevant.

### Keyboard interactions

For `radio` buttons in a `radiogroup` that is NOT in a `toolbar`, the following keyboard interactions must be supported:

`Tab` and `Shift + Tab`

Move focus into and out of the `radiogroup`. When focus moves into a `radiogroup`, if a radio button is checked, focus is set on the checked button. If none of the radio buttons are checked, focus is set on the first radio button in the group.

`Space`

Checks the focused radio button if it is not already checked.

`Right Arrow` and `Down Arrow`

Moves focus to the next radio button in the group, unchecking the previously focused button, and checking the newly focused button. If focus is on the last button, focus moves to the first button.

`Left Arrow` and `Up Arrow`

Moves focus to the previous radio button in the group, unchecking the previously focused button, and checking the newly focused button. If focus is on the first button, focus moves to the last button.

Arrow keys are used to navigate among elements of a toolbar. When a `radiogroup` is nested inside a toolbar, users need to be able to navigate among all toolbar elements, including the radio buttons, without changing which radio button is checked. So, when navigating through a `radiogroup` in a `toolbar` with arrow keys, the button that is checked does not change. Rather, when inside a `toolbar`, the `Space` and `Enter` keys check the focused `radio` button if it is not already checked, with `Tab` moving focus into and out of the `toolbar`.

### Required JavaScript features

User interactions for `radiogroup`s must replicate the user interaction of a user entering into a group of same-named HTML radio buttons. Keyboard events for tabs, space, and arrow keys must be captured. Click events on both the radio elements and their associated labels must also be captured. Additionally, focus must be managed.

While generally moving off an a focused element brings you to the next focusable element in the DOM order, using the arrow keys to navigate through a group of radio button keeps you in the group, moving focus to the first radio button when the `Right Arrow` or `Down Arrow` is released when focus was on the last radio in the group, and moving to the last radio if the `Left Arrow` or `Up Arrow` is released if focus was on the first radio. Managing roving `tabindex` is one method to manage arrow key events.

### Required CSS features

Use the `[aria-checked="true"]` attribute selector to style the checked state of checked radio buttons.

Use CSS `:hover` and `:focus` pseudo-classes for styling visual keyboard focus and hover. The focus and hover effect should encompass both the radio button and label to make it easier to perceive which option is being chosen and to indicate that clicking either the label or button will activate the radio button.

Examples
--------

The basic set up for a `radiogroup` using non-semantic ARIA roles instead of semantic HTML is as follows:

```html
<div role="radiogroup" aria-labelledby="question">
  <div id="question">Which is the best color?</div>
  <div id="radioGroup">
    <p>
      <span
 id="colorOption\_0"
 tabindex="0"
 role="radio"
 aria-checked="false"
 aria-labelledby="purple"></span>
      <span id="purple">Purple</span>
    </p>
    <p>
      <span
 id="colorOption\_1"
 tabindex="-1"
 role="radio"
 aria-checked="false"
 aria-labelledby="aubergine"></span>
      <span id="aubergine">Aubergine</span>
    </p>
    <p>
      <span
 id="colorOption\_2"
 tabindex="-1"
 role="radio"
 aria-checked="false"
 aria-labelledby="magenta"></span>
      <span id="magenta">Magenta</span>
    </p>
    <p>
      <span
 id="colorOption\_3"
 tabindex="-1"
 role="radio"
 aria-checked="false"
 aria-labelledby="all"></span>
      <span id="all">All of the above</span>
    </p>
  </div>
</div>
```

This could have been written using semantic HTML, which requires no CSS or JavaScript:

```html
<fieldset>
  <legend>Which is the best color?</legend>
  <p>
    <input name="colorOption" type="radio" id="purple" />
    <label for="purple">Purple</label>
  </p>
  <p>
    <input name="colorOption" type="radio" id="aubergine" />
    <label for="aubergine">Aubergine</label>
  </p>
  <p>
    <input name="colorOption" type="radio" id="magenta" />
    <label for="magenta">Magenta</label>
  </p>
  <p>
    <input name="colorOption" type="radio" id="all" />
    <label for="all">All of the above</label>
  </p>
</fieldset>
```

In this `<fieldset>` example, while `role="radiogroup"` is not necessary, to have this grouping explicitly announced as `radiogroup`, include the ARIA role.

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

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

See Also
--------

* HTML `<fieldset>` element
* HTML <input type="radio"> radio button element
* ARIA `radio` role
* `aria-errormessage`
* `aria-invalid`
* `aria-readonly`
* `aria-required`


ARIA: search role - Accessibility

ARIA: search role
=================

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

```html
<form role="search">
  <!-- search input -->
</form>
```

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

The `search` role is a landmark role that can be added to the container element that encompasses all of the elements that combined to form the search feature of the document or application, including a descendant (`<input type="search">`). If a document includes more than one search, each should have a unique label, unless they are the same search repeated, then use the same name. There is a `input` of type `search`), though this does not define a search landmark by itself. Using `<search>` is an alternative way to define a search landmark.

Examples
--------

When a `<form>` is a search form, use the `search` role instead of `form` role.

```html
<form id="search" role="search">
  <label for="search-input">Search this site</label>
  <input type="search" id="search-input" name="search" spellcheck="false">
  <input value="Submit" type="submit">
</form>
```

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

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

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

### Prefer HTML

Using the `<form>` element in conjunction with a declaration of `role="search"` will provide the largest amount of support.

### Labeling landmarks

#### Multiple landmarks

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

```html
<form id="site-search" role="search" aria-label="Sitewide">
  <!-- search input -->
</form>

…

<form id="page-search" role="search" aria-label="On this page">
  <!-- search input -->
</form>
```

#### Repeated landmarks

If a `search` landmark role in a document is repeated in a document, and both landmarks have identical content, use the same label for each landmark. An example of this would be repeating the sitewide search at the top and bottom of the page.

```html
<header>
  <form id="site-search-top" role="search" aria-label="Sitewide">
    <!-- search input -->
  </form>
</header>

…

<footer>
  <form id="site-search-bottom" role="search" aria-label="Sitewide">
    <!-- search input -->
  </form>
</footer>
```

#### Redundant descriptions

Screen readers will announce the type of role the landmark is. Because of this, you do not need to describe what the landmark is in its label. For example, a declaration of `role="search"` with an `aria-label="Sitewide search"` may be announced redundantly as, "sitewide search search".

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

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

See also
--------

* The `<form>` element
* The `<input>` element
* The `<search>` element
* `<input type="search">`
* Using HTML sections and outlines


ARIA: input role - Accessibility

ARIA: input role
================

The `input` abstract role is a generic type of widget that allows user input.

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

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

The `input` role is an abstract role. It must not be used by web authors. It is the superclass for input widgets that provide for user input, including `checkbox`, `radio`, and `textbox`. For all three, consider using the `<input>` element of type `checkbox`, `radio` and `text`, respectively.

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

Do not use.

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

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

See Also
--------

* ARIA: `widget` role
* ARIA: `checkbox` role
* ARIA: `combobox` role
* ARIA: `option` role
* ARIA: `radio` role
* ARIA: `slider` role
* ARIA: `spinbutton` role
* ARIA: `textbox` role
* HTML: the `input` element


ARIA: figure role - Accessibility

ARIA: figure role
=================

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

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

A `figure` is a perceivable section of content that typically contains a graphical document, images, code snippets, or example text. The parts of a figure MAY be user-navigable. Any content that should be grouped together and consumed as a figure (which could include images, video, audio, code snippets, or other content) can be identified as a figure using `role="figure"`.

```html
<div role="figure" aria-labelledby="caption">
  <img src="image.png" alt="put image description here" />
  <p id="caption">Figure 1: The caption</p>
</div>
```

In the above example, we have a figure that consists of two separate content items — an image and a caption. This is wrapped by a `<div>` element that identifies the content as a figure using `role="figure"`.

 For HTML, use the `<figure>` and `<figcaption>` elements. The figcaption will serve as the accessible name for the figure. When not using HTML, or when retrofitting legacy HTML, use the `aria-labelledby` on the figure, pointing to the figure's caption.
 If there is no visible caption, `aria-label` can be used.

```html
<div role="figure" aria-labelledby="figure-1">
  …
  <p id="figure-1">Text that describes the figure.</p>
</div>
```

* Use `aria-labelledby` when the text is a concise label.
* Use `aria-describedby` when the text is a longer description.
* Use `aria-label` when there is no visible figure caption.

This can be done semantically, without ARIA, with HTML's `<figure>` element along with `<figcaption>`.

```html
<figure>
  <img src="image.png" alt="put image description here" />
  <figcaption>Figure 1: The caption</figcaption>
</figure>
```

**Note:** If at all possible in your work, you should use the appropriate semantic HTML elements to mark up a figure and its caption — `<figure>` and `<figcaption>`.

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

`aria-describedby`

The id of an element containing reference text serving as a caption.

`aria-labelledby`

The id of an element containing text serving as a label.

`aria-label`

If there is no element containing text that could serve as a label, you can add the label directly as a value on the `aria-label` on the element with the `figure` role or on the `<figure>` element.

### Keyboard interactions

No role specific keyboard interactions.

### Required JavaScript features

No role specific JavaScript requirements. If you don't have control over the HTML semantics, you can improve the accessibility of HTML by adding these roles and properties with JavaScript.

Examples
--------

We could extend the initial example on the page to also identify a paragraph that provides a descriptive label for the figure by referencing its ID in `aria-labelledby`:

```html
<div role="figure" aria-labelledby="figure-1">
  <img
 src="diagram.png"
 alt="diagram showing the four layers of awesome and their relative priority order —
 music, cats, nature, and ice cream" />
  <pre>
`
        let awesome = ['music', 'cats', 'nature', 'ice cream'];
      `</pre
 >
  <p id="figure-1">Figure 1: The four layers of awesome.</p>
</div>
```

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

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

If at all possible, you should use the appropriate semantic HTML elements to mark up a figure and its caption — `<figure>` and `<figcaption>`. For example, our above example should be rewritten as follows:

```html
<figure>
  <img
 src="diagram.png"
 alt="diagram showing the four layers of awesome and their relative priority order —
 music, cats, nature, and ice cream" />
  <pre>
`
    let awesome = ['music', 'cats', 'nature', 'ice cream'];
  `</pre
 >
  <figcaption>Figure 1: The four layers of awesome.</figcaption>
</figure>
```

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

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

See also
--------

* Accessibility Object Model
* ARIA in HTML
* HTML `<figure>` element
* HTML `<figcaption>` element


ARIA: listitem role - Accessibility

ARIA: listitem role
===================

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

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

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

Any content that consists of an outer container with a list of elements inside it can be identified to assistive technologies using the `list` and `listitem` containers respectively.

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

**Note:** If at all possible in your work, you should use the appropriate semantic HTML elements to mark up a list and its listitems — `<ul>`/`<ol>` and `<li>`. See Best practices for a full example.

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

`list`

A list of items. Elements with role `list` must have one or more elements with the role `listitem` as children, a one or more elements with the role of `group` that have one or more elements with the `listitem` role as children.

`group`

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

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

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

If at all possible, you should use the appropriate semantic HTML elements to mark up a list and listitems — `<ol>`, `<ul>` and `<li>`. For example, our above example should be rewritten as follows:

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

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

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

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

**Note:** Styling a list with `list-style: none;` in CSS removes the list semantics. Adding `role="listitem"` returns the semantics.

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

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

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

See also
--------

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


ARIA: suggestion role - Accessibility

ARIA: suggestion role
=====================

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

Examples
--------

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

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

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

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

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

Browsers tend to provide a default black strikethrough for deletions, and a black underline for insertions, but you'll probably want to use

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

### Prefer HTML

Using the `<ins>` and `<del>` element will automatically communicate a section has a role of `insertion` or `deletion`. If at all possible, prefer using the HTML elements.

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

Will be part of WAI-ARIA 1.3, which is still being drafted.

See also
--------

* ARIA annotations


ARIA: math role - Accessibility

ARIA: math role
===============

The `math` role indicates that the content represents a mathematical expression.

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

Content with the role `math` is intended to be marked up in an accessible format such as MathML, or with another type of textual representation, which can be converted to an accessible format by the browser or a polyfill library.

 Unfortunately, browser support for MathML is not universal. While using an image of a mathematical expression is not optimal, if you do use image, use the `math` role.
 Make sure any images of math are labeled by an `alt` attribute that describes the mathematical expression as it would be spoken.

If the math element has only presentational children and the accessible name is intended to convey the mathematical expression, use `aria-label` to provide a string that represents the expression. If the math element contains navigable content that conveys the mathematical expression and a visible label for the expression is present, use `aria-labelledby`. Otherwise, use `aria-label` to name the expression, e.g., `aria-label="Pythagorean Theorem"`.

Examples
--------

If you use image or non-semantic HTML to create an equation, use the `math` role.

a2 + b2 = c2
The above pythagorean theorem is written accessibly as:

```html
<div role="math" aria-label="a^{2} + b^{2} = c^{2}">
  a<sup>2</sup> + b<sup>2</sup> = c<sup>2</sup>
</div>
```

Had an image been used, the `alt` attribute would be used along with the `math` role:

```html
<img src="pythagorean\_theorem.gif" alt="a^{2} + b^{2} = c^{2}" role="math" />
```

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

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

See Also
--------

* MathML on MDN and the `<math>` element (not HTML)
* The MathML specification


ARIA: menuitemradio role - Accessibility

ARIA: menuitemradio role
========================

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

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

The items in menu and menubars are menu items. There are three types of menu items: `menuitem`, `menuitemcheckbox`, and `menuitemradio`. To limit the number of checked menu items to one within a group, use the `menuitemradio` role on all the elements in the group.

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

The three menu item elements can only be contained in, or owned by, an element with role `menu` or `menubar`, optionally nested within a grouping element with role of `group`. Being nested or otherwise owned (see `aria-owns`) in a `menu` or `menubar` identifies the menu items as being related widgets.

When all items in a submenu are members of the same radio group, the `group` is defined by the menu element; the `group` element is not necessary.

Menu items containing the role of `menuitemradio` must include the `aria-checked` attribute to expose the radio button's state to assistive technology, unless using `<input type="radio">`, in which case the 'checked' attribute should be used.

Similar to the 'checked' attribute of `<input>`s of type `radio`, the `aria-checked` attribute of a `menuitemradio` indicates whether the menu item is checked (`true`), unchecked (`false`). If missing, the value defaults to `false`. There is no `mixed` value like there is for `menuitemcheckbox`.

Only one `menuitemradio` in a group can be checked at the same time. When one item in the group is checked, the `aria-checked` attribute gets set to `true`, while the previously checked `menuitemradio` element in the same group, if there was one, becomes unchecked, by having the `aria-checked` attribute value switched to `false`.

If your want more than one item in a group to be checked, or if you want to enable checking and unchecking an item, consider using `menuitemcheckbox`.

If a `menu` or `menubar` contains more than one group of `menuitemradio` elements, or if the `menu` contains a group of `menuitemradio` elements as well as other, unrelated `menuitem` elements and/or `menuitemcheckbox` elements, contain each set of related `menuitemradio` elements in a `group` element or delimit the group the `menuitemradio` elements from the other menu items with a `separator` element (or an HTML element with an equivalent role such as a `<fieldset>` grouping or a thematic break `<hr>` separator.

An accessible name is required. Ideally, the accessible name should come from an associated `<label>` element if using `<input type="radio">` or visible, descendant content. Realize if the label or descendant content is not sufficient and, preferably, `aria-labelledby` is used referencing non-descendant content or `aria-label` is used, these two ARIA properties will hide other descendant content from assistive technologies.

If all elements in the set are not present in the DOM include the `aria-setsize` and `aria-posinset` properties. When specifying `aria-setsize` and `aria-posinset` on a `menuitemradio`, set the value with respect to the total number of items in the menu, excluding any separators.

The `menuitemradio` element can have phrasing content, but can not have interactive content as descendants and no descendants with a `tabindex` attribute specified.

### 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 `menuitemradio`. To deal with this limitation, browsers, automatically apply role `presentation` to all descendant elements of any `menuitemradio` element as it is a role that does not support semantic children.

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

```html
<div role="menuitemradio"><h6>Name of my radio button</h6></li>
```

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

```html
<div role="menuitemradio"><h6 role="presentation">Name of my radio button</h6></li>
```

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="menuitemradio">Name of my radio button</div>
```

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

`menu` role

Widget that offers a list of common actions or functions the user can invoke.

`menubar` role

Similar to `menu` for a consistent set of frequently used commands remaining visible and usually presented horizontally.

`group` role

Container for a group of `menuitem` elements, including `menuitemradio` elements within a `menu` or `menubar`.

`aria-checked` (Required)

Set to `true`, `false`, or `mixed`, it indicates the current "checked" state of the menuitemradio

### Keyboard interactions

When a `menu` opens, or when a `menubar` receives focus, keyboard focus is placed on the first item. All items in both are focusable, including all `menuitemradio` elements.

If the `menuitemradio` is in a submenu in a `menubar` or a menu opened with a menu button, the following keyboard interactions must be programmed in. :

`Enter`

If not checked, checks the focused `menuitemradio` and unchecks any other checked `menuitemradio` element in the same group. Also, closes the menu.

`Space`

If not checked, checks the focused `menuitemradio` and unchecks any other checked `menuitemradio` element in the same group without closing the menu.

`Escape`

Closes menu. In menubar, moves focus to parent menubar item.

`Right Arrow`

Closes submenu. In menubar, moves focus to next item in the menubar, opening any submenu if there is one.

`Left Arrow`

Closes menu. In menubar, moves focus to previous item in the menubar, opening any submenu if there is one.

`Down Arrow`

Moves focus to the next item in the menu. If focus is on the last item, moves focus to the first item.

`Up Arrow`

Moves focus to previous item in the menu. If focus is on the first item, moves focus to the last item.

`Home`

Moves focus to the first item in the menu.

`End`

Moves focus to the last item in the menu.

`Character`

Moves focus to the next item having a name that starts with the typed character. If none of the items have a name starting with the typed character, focus does not move.

### Required JavaScript

#### Required event handlers

`onclick`

Handle mouse clicks on both the radio button and the associated label that will change the state of the radio button by changing the value of the `aria-checked` attribute and the appearance of the radio button so it appears checked or unchecked to the sighted user

`onKeyDown`

Handle the case where the user presses the `Space` key to change the state of the radio button by changing the value of the `aria-checked` attribute and the appearance of the radio button so it appears checked or unchecked to the sighted user. Also handles all keys listed in the keyboard navigation section above.

Examples
--------

```html
<li role="menuitemradio" tabindex="-1" aria-checked="false">Purple</li>
```

The `tabindex="-1"` makes the `menuitemradio` focusable but not part of the page tab sequence. Had we included `aria-checked="true"` it would have indicated that the `menuitemradio` was checked, and we would have visually styled the selected state to look checked using the attribute selector `[role='menuitemradio'][aria-checked='true']`. Instead, the presence of `aria-checked="false"` indicates to assistive technologies that the `menuitemradio` is checkable but not currently checked. The accessible name "purple" comes from the contents.

The visual appearance of the selected state is a checked radio button which we can create using generated content, making it visible and the same color as the content by synchronizing with the `aria-checked` value using CSS attribute selectors and changing the `background-color`.

```css
[role="menuitemradio"]::before {
  display: inline-block;
  content: "";
  width: 1em;
  height: 1em;
  padding: 0.1em;
  border: 2px solid #333;
  border-radius: 50%;
  box-sizing: border-box;
  background-clip: content-box;
  margin-inline-end: 2px;
}
[role="menuitemradio"][aria-checked="true"]::before {
  background-color: purple;
}
```

Don't use the `background` shorthand property, as that will override the `background-clip` property we used to create the radio button effect.

### Prefer HTML

The first rule of ARIA is: if a native HTML element or attribute has the semantics and behavior you require, use it instead of re-purposing an element and adding an ARIA role, state or property to make it accessible. As such, it is recommended to use the native HTML radio button form control instead of recreating a radio button's functionality with JavaScript and ARIA.

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

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

See Also
--------

* `radio` role
* `<input type="radio">`


ARIA: window role - Accessibility

ARIA: window role
=================

The `window` role defines a browser or app window.

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

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

The `window` role, an abstract role, is a superclass for roles defining a browser or app window. The sub-class roles, currently only the `dialog` role, have a window-like GUI, or graphical user interface, whether it's a full native window or just a section of a document styled to look like a window, where `role="dialog"` would be appropriate.

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

Do not use.

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

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

See Also
--------

* ARIA: `roletype` role
* ARIA: `dialog` role


ARIA: tooltip role - Accessibility

ARIA: tooltip role
==================

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

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

Tooltips provide contextual information about an element when that owning element receives focus or is hovered over, but is otherwise not visible on the page. The tooltip is displayed automatically, after a brief delay; the user does not request it. While a tooltip can be placed on any content, they generally are tips for tools or controls, such as providing additional content for icons that have brief labels (or no labels at all, which is not accessible!).

A tooltip typically becomes visible, after a short delay of generally one to five seconds, in response to a mouse hover, or after the owning element receives keyboard focus. Just as it is opened automatically, without user request, it is closed automatically when the focus is lost or on mouse out. It must stay open when the mouse moves over the tooltip itself, and should also close when the user presses the `Escape` key.

Because the tooltip itself never receives focus and is not in the tabbing order, a tooltip can not contain interactive elements like links, inputs, or buttons.

The tooltip is not the appropriate role for the more information "i" icon, ⓘ. A tooltip is directly associated with the owning element. The ⓘ isn't 'described by' detailed information; the tool or control is.

The use of the ARIA `tooltip` role is a supplement to the normal browser tooltip behavior. An example of a native browser tooltip is the way some browsers display an element's `title` attribute on long mouse hover. One cannot activate this feature through either keyboard focus or through touch interaction, making this feature inaccessible. If the information is important enough to include as a tooltip or title, consider including it in visible text.

Elements with the `tooltip` role should be referenced through the use of `aria-describedby` before or when the tooltip is displayed. The `aria-describedby` attribute is on the owning element, not on the tooltip.

The tooltip is not considered a popup in terms of the `aria-haspopup` property on the owning element, which is why we used "text bubble" in the introductory definition.

Though a tooltip may appear and disappear, as its appearance is automatic and not intentionally controlled by the user, the `aria-expanded` role is not supported.

The accessible name of a tooltip can come from the contents. While, in theory, they could come from an `aria-label` or `aria-labelledby`, in most cases, using ARIA properties to provide a tooltip with an accessible name is not recommended.

Tooltips provide additional information, generally with no direct interaction on the tooltip itself. They are generally associated with the content they're defining via an `aria-describedby` with the `id` of the primary element. Therefore, if the tooltip has an accessible name explicitly set, that name is exposed as the primary element's description rather than the contents of the tooltip, meaning the tooltip contents may never be discovered by a screen reader user.

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

* The element that serves as the tooltip container has `role="tooltip"` set.
* The element that triggers the tooltip references the tooltip element with `aria-describedby`.
### Keyboard interactions

`Escape`

Closes the tooltip

The tooltip should appear on focus or when the element is hovered on, without additional interaction. It should disappear automatically when the focus on the owning element is lost or the mouse is moved outside the owning element and the tooltip. While the tooltip does not receive focus, the `Escape` should close it if it is open.

### Required JavaScript features

* The tooltip is displayed and disappears via keyboard focus and removal of focus and by the mouse events - mousing over and mousing out.
* The tooltip never receives focus. Focus stays on the owning element.
* The tooltip can be hidden with the `Escape` key
* The tooltip stays open when hovered
* The tooltip is only hidden via JavaScript and CSS selectors. If JavaScript is not available the tooltip is shown.
Examples
--------

```html
<label for="password">Password:</label>
<input aria-describedby="passwordrules" id="password" type="password" />
<div role="tooltip" id="passwordrules">
  <p>Password Rules:</p>
  <ul>
    <li>Minimum of 8 characters</li>
    <li>
      Include at least one lowercase letter, one uppercase letter, one number
      and one special character
    </li>
    <li>Unique to this website</li>
  </ul>
</div>
```

The tooltip can be instantiated with CSS. Change the class name with JavaScript to a class that hides the tooltip if the user hits the `Escape` key.

```css
[role="tooltip"],
.hidetooltip.hidetooltip.hidetooltip + [role="tooltip"] {
  visibility: hidden;
  position: absolute;
  top: 2rem;
  left: 2rem;
  background: black;
  color: white;
}
[aria-describedby]:hover,
[aria-describedby]:focus {
  position: relative;
}
[aria-describedby]:hover + [role="tooltip"],
[aria-describedby]:focus + [role="tooltip"] {
  visibility: visible;
}
```

The above hides the tooltip with CSS in the default state or if the hidetooltip class has been added with JavaScript (when the user hit `Escape`), with high specificity to ensure the tooltip doesn't show. When the owning element receives focus, it gets positioned relatively and the tooltip becomes visible.

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

If the information is important enough for a tooltip, isn't it important enough to always be visible?

The tooltip must stay open when hovered, even if that technically means the mouse moves out of the owning element. As content which appears on hover can be difficult or impossible to perceive if a user is required to keep their mouse pointer over the trigger, WCAG 1.4.13 states that content made visible should be persistent, meaning it should not disappear without user action.

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

Instead of using tooltips and hiding important information, consider writing clear, succinct, always visible descriptions. If you have space, don't use tooltips or toggletips. Just provide clear labels and sufficient body text.

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

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

See Also
--------

* The `dialog` role
* CSS: `:focus` pseudoclass
* Tooltips & Toggletips by Heydon Pickering
* Understanding SC 1.4.13:Content on Hover or Focus (WCAG Level AA)


ARIA: menuitem role - Accessibility

ARIA: menuitem role
===================

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

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

A `menuitem` is one of the three types of options in a set of choices contained by a `menu` or `menubar`; the other two being `menuitemcheckbox` and `menuitemradio`. The `menuitem` is only found as a descendant of, or owned by, elements with role `menu` or `menubar`, optionally nested within an element with role `group` that is contained in, or owned by, a menu.

If the `menuitem` is not a descendant of a menu in the DOM, include the `aria-owns` attribute on menu to indicate the relationship. If `aria-owns` is set on the menu container to include elements that are not DOM children of the container, those elements will appear in the reading order in the sequence they are referenced and after any items that are DOM children in supporting technologies. Ensure the visual focus order matches the assistive technology reading order.

Every `menuitem` in a menu is focusable, whether or not it is disabled. Indicate a `menuitem` is disabled by setting `aria-disabled="true"` on the element with the role.

If a `menuitem` has a submenu, program it to display a new sub-level menu when the menu item is activated and include `aria-haspopup="menu"` or with the `true` value to indicate to assistive technologies that the menu item is used to open a submenu.

A common convention for indicating that a `menuitem` launches a dialog box is to append "…" (ellipsis) to the menu item label, e.g., "Save as …".

Every `menuitem` must have an accessible name. This name comes from the element's contents by default. If the contents don't provide for a useful accessible name, `aria-labelledby` can be used to reference visible label. If no visible content is available to provide the accessible name, an accessible name can be provided with `aria-label`.

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

`menu` role

A widget providing a list of choices. Required context role (or `menubar`)

`menubar` role

A presentation of a `menu` that usually remains visible and is usually presented horizontally. Required context role (or `menu`)

`group` role

Can be used to identify a set of related `menuitem`s within or otherwise owned by a `menu` or `menubar`

`aria-disabled`

Indicates the element is perceivable but disabled, so it is not operable

`aria-haspopup`

Indicates the availability and type of interactive popup that can be triggered by the `menuitem`

Keyboard interactions
---------------------

`Enter` and `Space`

If the `menuitem` has a submenu, opens the submenu and places focus on its first item. Otherwise, activates the item and closes the menu.

`Down Arrow`

On a `menuitem` that has a submenu in a `menubar`, opens the submenu and places focus on the first item in the submenu. Otherwise, moves focus to the next item, optionally wrapping from the last to the first.

`Up Arrow`

Moves focus to the previous item, optionally wrapping from the first to the last. Optionally, if the `menuitem` is in a menubar and has a submenu, opens the submenu and places focus on the last item in the submenu.

`Right Arrow`

If in a `menu` opened with a menubutton and not in a `menubar`, if the menuitem does not have a submenu, does nothing. When focus is in a `menubar`, moves focus to the next item, optionally wrapping from the last to the first. When focus is in a `menu` and on a `menuitem` that has a submenu, opens the submenu and places focus on its first item. When focus is in a `menu` and on an item that does not have a submenu, closes the submenu and any parent menus, moves focus to the next item in the `menubar`, and, if focus is now on a `menuitem` with a submenu, either opens the submenu of that `menuitem` without moving focus into the submenu, or opens the submenu of that `menuitem` and places focus on the first item in the submenu.

`Left Arrow`

When focus is in a `menubar`, moves focus to the previous item, optionally wrapping from the first to the last. When focus is in a submenu of an item in a menu, closes the submenu and returns focus to the parent `menuitem`. When focus is in a submenu of an item in a `menubar`, closes the submenu, moves focus to the previous item in the `menubar`, and, if focus is now on a `menuitem` with a submenu, either opens the submenu of that `menuitem` without moving focus into the submenu, or opens the submenu of that `menuitem` and places focus on the first item in the submenu.

`Home`

If arrow key wrapping is not supported, moves focus to the first item in the current `menu` or `menubar`.

`End`

If arrow key wrapping is not supported, moves focus to the last item in the current `menu` or `menubar`.

Any key that corresponds to a printable character (Optional)

Move focus to the next item in the current menu whose label begins with that printable character.

`Escape`

Close the menu that contains focus and return focus to the element or context, e.g., menu button or parent `menuitem`, from which the menu was opened.

`Tab`

Moves focus to the next element in the tab sequence, and if the item that had focus is not in a menubar, closes its menu and all open parent menu containers.

`Shift + Tab`

Moves focus to the previous element in the tab sequence, and if the item that had focus is not in a menubar, closes its menu and all open parent menu containers.

If a menu is opened or a menu bar receives focus as a result of a context action, `Escape` or `Enter` may return focus to the invoking context.

Some implementations of navigation menubars may have menuitem elements that both perform a function and open a submenu. In such implementations, `Enter` and `Space` perform a navigation function while `Down Arrow`, in a horizontal menubar, opens the submenu associated with that same menuitem.

When items in a `menubar` are arranged vertically and items in menu containers are arranged horizontally the `Down Arrow` performs as `Right Arrow` is described above, the `Up Arrow` performs as `Left Arrow` is described above, and vice versa.

Examples
--------

```html
<div>
  <button id="menubutton" aria-haspopup="true" aria-controls="menu">
    <img src="hamburger.svg" alt="Page Sections" />
  </button>
  <ul id="menu" role="menu" aria-labelledby="menubutton">
    <li role="presentation">
      <a role="menuitem" href="#description">Description</a>
    </li>
    <li role="presentation">
      <a
 role="menuitem"
 href="#associated\_wai-aria\_roles\_states\_and\_properties">
        Associated WAI-ARIA roles, states, and properties
      </a>
    </li>
    <li role="presentation">
      <a role="menuitem" href="#keyboard\_interactions">
        Keyboard interactions
      </a>
    </li>
    <li role="presentation">
      <a role="menuitem" href="#examples">Examples</a>
    </li>
    <li role="presentation">
      <a role="menuitem" href="#specifications">Specifications</a>
    </li>
    <li role="presentation">
      <a role="menuitem" href="#see\_also">See Also</a>
    </li>
  </ul>
</div>
```

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

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

See Also
--------

* `menuitemcheckbox` role
* `menuitemradio` role
* `listitem` role
* `option` role


ARIA: treeitem role - Accessibility

ARIA: treeitem role
===================

A `treeitem` is an item in a `tree`.

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

A `tree` is a hierarchical list with parent and child nodes that can expand and collapse. A `treeitem` is a node in a `tree`. The root of the tree is `tree`, but all tree nodes are `treeitem` elements, even if they themselves have nested `treeitem` nodes.

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

In a tree hierarchy, the *root node* has the role `tree`. All other nodes, other than the root node, have the role of `treeitem`, whether or not they have children. A `treeitem` that is a parent is a **parent node**. A `treeitem` that is not a parent is an *end node*.

Tree items that have children can be expanded or collapsed, showing and hiding their children. A parent node that is expanded so its child nodes are visible is an **open node**. A parent node that is collapsed so the child nodes are not visible is a **closed node**.

Each parent node contains or owns an element with role `group`. A parent node is an expandable collection of `treeitem` elements. These child nodes are not direct descendants of the parent node: rather, they should be enclosed in an element with the `group` role.

Each parent node should include the `aria-expanded` attribute. It is set to `false` when closed `true` when open. End nodes should not have the `aria-expanded` attribute included as the presence of the attribute indicates to assistive technologies that the node is a parent.

**Note:** ARIA tree views use navigation more similar to native applications than to web applications and 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, consider alternative options to address the functionality you need before creating a tree view.

Any element with a `treeitem` role must be nested in, or owned by, an element with role `tree`. Tree items can be a child of `tree`, `treeitem`, or an element with role `group` that is contained in, or owned by, an element with role `tree` or `treeitem`. If a `treeitem` is not nested within a `tree`, or nested in a `group` that is owned by a `tree`, include the `id` of the `treeitem` in the `aria-owns` attribute value on the owning `tree`, `treeitem` or `group` element.

Trees can be "single-select", allowing users to choose just one `treeitem` for an action, or "multi-select", where users are able to select more than one `treeitem` nodes for an action. In both cases, to be keyboard accessible, focus must be managed for all tree descendants.

In single-select trees, only one treeitem can have `aria-selected` (or `aria-checked`) set to `true`. When a single-select tree receives focus, if no `treeitem` is selected before the tree receives focus, focus is set on the first `treeitem`. If a `treeitem` is selected before the tree receives focus, focus is set on the single `treeitem` that has `aria-selected="true"` set.

All nodes that are selectable but not selected have either `aria-selected` or `aria-checked` set to `false`. If the tree contains nodes that are not selectable, do not include either `aria-selected` or `aria-checked`, as the presence of either attribute indicates to assistive technologies the node is selectable.

No more than one node can be selected at a time unless the `tree` node has `aria-multiselectable="true"` set.

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 `treeitem`. If one or more tree items are selected before the tree receives focus, focus is set on the first selected `treeitem`.

In multi-select trees, all selected tree items have either `aria-selected="true"` (or `aria-checked="true"`) set. All tree item nodes that are selectable but not currently selected should have `aria-selected="false"` (or `aria-checked="false"`) set.

Either `aria-selected` or `aria-checked` can be used to indicate selection for `treeitem` elements. Some user interfaces indicate selection with `aria-selected` in single-select trees and with `aria-checked` in multi-select trees.

Using both `aria-selected` and `aria-checked` in the same `tree` is strongly discouraged. Don't use both `aria-selected` and `aria-checked` on treeitems in a single tree unless the meaning and purpose of `aria-selected` is different from the meaning and purpose of `aria-checked`, the meaning and purpose of each state apparent, and the user interface provides a separate method for controlling each state.

In multi-select trees, the selected state should be 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.

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

A `treeitem` is required to have an accessible name. Generally, that name comes from the `treeitem`'s contents. The accessible name can also be set via `aria-label` or `aria-labelledby`.

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

`tree` role

The root node for the hierarchical list of parent and child `treeitem` nodes that can expand and collapse

`group` role

Identifies a set of `treeitem` child nodes.

`aria-expanded`

Set on the root `tree` and on `group` nodes that are parents of `treeitem` nodes, to indicate whether the tree view is expanded (`true`) or collapsed (`false`).

`aria-selected`

Set to `true` or `false`, indicates a `treeitem` is selectable, and whether or not it is currently selected.

`aria-checked`

Set to `true` or `false`, indicates the `treeitem` can be checked, and whether or not it is currently checked.

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

Examples
--------

The following is how one might mark up a directory listing of web development courses as a tree view:

```html
<div>
  <h3 id="treeLabel">Developer Learning Path</h3>
  <ul role="tree" aria-labelledby="treeLabel">
    <li role="treeitem" aria-expanded="true">
      <span>Web</span>
      <ul role="group">
        <li role="treeitem" aria-expanded="false">
          <span>Languages</span>
          <ul role="group">
            <li role="treeitem" aria-expanded="false">
              <span>HTML</span>
              <ul role="group">
                <li role="treeitem">Document structure</li>
                <li role="treeitem">Head elements</li>
                <li role="treeitem">Semantic elements</li>
                <li role="treeitem">Attributes</li>
                <li role="treeitem">Web forms</li>
              </ul>
            </li>
            <li role="treeitem">CSS</li>
            <li role="treeitem">JavaScript</li>
          </ul>
        </li>
        <li role="treeitem" aria-expanded="false">
          <span>Accessibility</span>
          <ul role="group">
            <li role="treeitem" aria-label="accessibility object model">AOM</li>
            <li role="treeitem">WCAG</li>
            <li role="treeitem">ARIA</li>
          </ul>
        </li>
        <li role="treeitem" aria-expanded="false">
          <span>Web Performance</span>
          <ul role="group">
            <li role="treeitem">Load time</li>
          </ul>
        </li>
        <li role="treeitem">APIs</li>
      </ul>
    </li>
  </ul>
</div>
```

The above provides the semantics for a tree view, but does not provide any of the interactivity. That must be added in with JavaScript.

If the tree items aren't by default focusable, JavaScript can be used `tabIndex="-1"` to all the treeitems except the one that should receive focus when the user tabs into the tree which should be set to `tabIndex="0"`.

All the keyboard functionality in Keyboard interactions and all pointer events need to be programmed, including focus management, going up and down the tree, expanding and collapsing parent nodes, and selection management.

If the tree has more than 7 tree items, including type ahead functionality is recommended.

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

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

See Also
--------


ARIA: term role - Accessibility

ARIA: term role
===============

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

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

The `term` role can be used for a word or phrase with an optional corresponding `definition`. It is equivalent in semantics to the HTML `<dfn>` element and the definition term (`<dt>`) element within a definition list (`<dl>` ).

The `term` role is used to explicitly identify a word or phrase for which a definition has been provided by the author or is expected to be provided by the user. If there is an existing definition, or a form or form control to enter a definition, authors SHOULD set `aria-details` to point to the related element.

Don't use the `role="term"` on interactive elements like links because it can interfere with assistive technology users ability to interact with the element. Also, the term itself is the accessible name, so do not use `aria-label` or `aria-labelledby`.

**Warning:** The accessible name should be the term itself, so DO NOT use `aria-label` or `aria-labelledby`.

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

None.

### Keyboard interactions

None.

### Required JavaScript features

None.

Examples
--------

```html
<p>
  <span role="term">Mansplaining</span>,
  <span role="definition"
 >a portmanteau of "man" and "explain", is the patronizing act of explaining
    without being asked to do so, to someone already learned on the topic, often
    after someone has already explained it</span
 >.
</p>
```

Including better semantics, the above could also be written:

```html
<p>
  <dfn role="term">Mansplaining</dfn>,
  <span role="definition"
 >a portmanteau of "man" and "explain", is the patronizing act of explaining
    without being asked to do so, to someone already learned on the topic, often
    after someone has already explained it</span
 >.
</p>
```

or without any ARIA (but possibly not how you want it presented)

```html
<dl>
  <dt>Mansplaining</dt>
  <dd>
    A portmanteau of "man" and "explain", is the patronizing act of explaining
    without being asked to do so, to someone already learned on the topic, often
    after someone has already explained it.
  </dd>
</dl>
```

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

Don't use the `role="term"` on interactive elements such as links as it can interfere with the assistive technology user's ability to interact with the element.

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

Allow the term itself to define the accessible name. Do not use `aria-label` or `aria-labelledby`.

### Prefer HTML

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

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

See Also
--------

* ARIA: `definition` role.
* The HTML `<dfn>` element


ARIA: checkbox role - Accessibility

ARIA: checkbox role
===================

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

```html
<span
 role="checkbox"
 aria-checked="false"
 tabindex="0"
 aria-labelledby="chk1-label"></span>
<label id="chk1-label">Remember my preferences</label>
```

**Note:** The first rule of ARIA is if a native HTML element or attribute has the semantics and behavior you require, use it instead of re-purposing an element and adding ARIA. Instead use the native HTML checkbox of `<input type="checkbox">` (with an associated `<label>`), which natively provides all the functionality required:

```html
<input type="checkbox" id="chk1-label" name="RememberPreferences" />
<label for="chk1-label">Remember my preferences</label>
```

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

The native HTML checkbox (`<input type="checkbox">`) form control had two states ("checked" or "not checked"), with an `indeterminate` state settable via JavaScript. Similarly, an element with `role="checkbox"` can expose three states through the `aria-checked` attribute: `true`, `false`, or `mixed`.

Since a checkbox 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 activating a checkbox is the `Space` key.

The developer is required to change the value of the `aria-checked` attribute dynamically when the checkbox is activated.

### 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 `checkbox`. To deal with this limitation, browsers, automatically apply role `presentation` to all descendant elements of any `checkbox` element as it is a role that does not support semantic children.

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

```html
<div role="checkbox"><h6>Name of my checkbox</h6></div>
```

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

```html
<div role="checkbox"><h6 role="presentation">Name of my checkbox</h6></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="checkbox">Name of my checkbox</div>
```

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

`aria-checked`

The value of `aria-checked` defines the state of a checkbox. This attribute has one of three possible values:

`true`

The checkbox is checked.

`false`

The checkbox is not checked.

`mixed`

The checkbox is partially checked, or indeterminate.

`tabindex="0"`

Used to make it focusable so the assistive technology user can tab to it and start reading right away.

### Keyboard interactions

| Key | Function |
| --- | --- |
| `Space` | Activates the checkbox |

### Required JavaScript

#### Required event handlers

`onclick`

Handle mouse clicks on both the checkbox and the associated label that will change the state of the checkbox by changing the value of the `aria-checked` attribute and the appearance of the checkbox so it appears checked or unchecked to the sighted user

`onKeyDown`

Handle the case where the user presses the `Space` key to change the state of the checkbox by changing the value of the `aria-checked` attribute and the appearance of the checkbox so it appears checked or unchecked to the sighted user

Examples
--------

The following example creates an otherwise non-semantic checkbox element using CSS and JavaScript to handle the checked or unchecked status of the element.

### HTML

```html
<span
 role="checkbox"
 id="chkPref"
 aria-checked="false"
 onclick="changeCheckbox()"
 onKeyDown="changeCheckbox(event.keyCode)"
 tabindex="0"
 aria-labelledby="chk1-label"></span>
<label
 id="chk1-label"
 onclick="changeCheckbox()"
 onKeyDown="changeCheckbox(event.keyCode)"
 >Remember my preferences</label
>
```

### CSS

```css
[role="checkbox"] {
  padding: 5px;
}

[role="checkbox"]:focus {
  border: 2px solid #0198e1;
}

[aria-checked="true"]::before {
  content: "[x]";
}

[aria-checked="false"]::before {
  content: "[ ]";
}
```

### JavaScript

```js
function changeCheckbox(keyCode) {
  const spacebarKeyCode = 32;
  const item = document.getElementById("chkPref");
  const checked = item.getAttribute("aria-checked");

  if (keyCode && keyCode !== spacebarKeyCode) {
    return;
  } else if (checked === "true") {
    item.setAttribute("aria-checked", "false");
  } else {
    item.setAttribute("aria-checked", "true");
  }
}
```

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

When the `checkbox` role is added to an element, the user agent should do the following:

* Expose the element as having a `checkbox` role in the operating system's accessibility API.
* When the `aria-checked` value changes, send an accessible state changed event.

Assistive technology products should do the following:

* Screen readers should announce the element as a checkbox, and optionally provide instructions on how to activate it.

People implementing checkboxes should do the following:

* Ensure that the checkbox can be reached and interacted with by both keyboard controls and clicks
* Keep the `aria-checked` attribute up to date following user interactions
* Provide styles that indicate when the checkbox has focus

**Note:** Opinions may differ on how assistive technology should handle this technique. The information provided above is one of those opinions and may change.

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

The first rule of ARIA is: if a native HTML element or attribute has the semantics and behavior you require, use it instead of re-purposing an element and adding an ARIA role, state or property to make it accessible. As such, it is recommended to use the native HTML checkbox using form control instead of recreating a checkbox's functionality with JavaScript and ARIA.

See also
--------

* `<input type="checkbox">`
* ARIA: `radio` role
* ARIA: `menuitem` role
* ARIA: `menuitemcheckbox` role
* ARIA: `menuitemradio` role
* ARIA: `switch` role
* ARIA: `option` role


ARIA: command role - Accessibility

ARIA: command role
==================

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

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

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

A command is form of widget that performs an action but does not receive input data. It is a superclass for the widget roles `button`, `link`, and `menuitem`

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

Do not use.

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

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

See Also
--------

* ARIA: `widget` role
* ARIA: `button` role
* ARIA: `link` role
* ARIA: `menuitem` role


ARIA: alert role - Accessibility

ARIA: alert role
================

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

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

The `alert` role is used to communicate an important and usually time-sensitive message to the user. When this role is added to an element, the browser will send out an accessible alert event to assistive technology products which can then notify the user.

The alert role should only be used for information that requires the user's immediate attention, for example:

* An invalid value was entered into a form field
* The user's login session is about to expire
* The connection to the server was lost so local changes will not be saved

The `alert` role should only be used for text content, not interactive elements such as links or buttons. The element with the `alert` role does not have to be able to receive focus, as screen readers (speech or braille) will automatically announce the updated content regardless of where keyboard focus when the role is added.

The `alert` role is added to the node containing an alert message, **not** the element causing the alert to be triggered. Alerts are assertive live regions. Setting `role="alert"` is equivalent to setting `aria-live="assertive"` and `aria-atomic="true"`. As they don't receive focus, focus does not need to be managed and no user interaction should be required.

**Warning:** Because of its intrusive nature, the `alert` role must be used sparingly and only in situations where the user's immediate attention is required.

The `alert` role is of the five live region roles. Dynamic changes that are less urgent should use a less aggressive method, such as including `aria-live="polite"` or using an other live region role like `status`. If the user is expected to close the alert, then the `alertdialog` role should be used instead.

The most important thing to know about the `alert` role is that it's for content that is dynamically displayed, not for content that appears on page load. It is perfect for situations such as when a user fills out a form and JavaScript is used to add an error message - the alert would immediately read out the message. It should not be used on HTML that the user hasn't interacted with. For example, if a page loads with multiple visible alerts scattered throughout, the alert role should not be used, as the messages were not dynamically triggered.

As with all other live regions, alerts will only be announced when the content of the element with `role="alert"` is *updated*. Make sure that the element with the role is present in the page's markup first - this will "prime" the browser and screen reader to keep watching the element for changes. After this, any changes to the content will be announced. Do not try to dynamically add/generate an element with `role="alert"` that is already populated with the alert message you want announced - this generally does *not* lead to an announcement, as it is not a content change.

As the `alert` role reads out any content that has changed, it should be used with caution. Alerts, by definition, are disruptive. Several alerts at once, and unnecessary alerts, create bad user experiences.

Examples
--------

The following are common examples of alerts and how to implement them:

### Example 1: Making ready-made content inside an element with an alert role visible

If the content *inside* the element with `role="alert"` is initially hidden using CSS, making it visible will cause the alert to fire. This means that an existing alert container element can be "reused" multiple times.

```css
.hidden {
  display: none;
}
```

```html
<div id="expirationWarning" role="alert">
  <span class="hidden">Your log in session will expire in 2 minutes</span>
</div>
```

```js
// removing the 'hidden' class makes the content inside the element visible, which will make the screen reader announce the alert:
document
  .getElementById("expirationWarning")
  .firstChild.classList.remove("hidden");
```

### Example 2: Dynamically changing the content inside an element with an alert role

Using JavaScript, you can dynamically change the content *inside* the element with `role="alert"`. Note that if you need to fire the same alert multiple times (i.e. the content you're dynamically inserting is the same as before), this generally won't be seen as a change and will *not* lead to an announcement. For this reason, it's usually best to briefly "clear" the contents of the alert container before then injecting the alert message.

```html
<div id="alertContainer" role="alert"></div>
```

```js
// clear the contents of the container
document.getElementById("alertContainer").innerHTML = "";
// inject the new alert message
document.getElementById("alertContainer").innerHTML =
  "Your session will expire in " + expiration + " minutes";
```

### Example 3: Visually hidden alert container for screen reader notifications

It's possible to visually hide the alert container itself, and use it to provide updates/notifications explicitly for screen readers. This can be useful in situations where important content on the page has been updated, but where the change would not be immediately obvious to a screen-reader user.

However, make sure that the container is not hidden using `display:none`, as this will hide it even from assistive technologies, meaning that they won't be notified of any changes. Instead, use something like the `.visually-hidden` styles.

```html
<div id="hiddenAlertContainer" role="alert" class="visually-hidden"></div>
```

```css
.visually-hidden {
  clip: rect(0 0 0 0);
  clip-path: inset(50%);
  height: 1px;
  overflow: hidden;
  position: absolute;
  white-space: nowrap;
  width: 1px;
}
```

```js
// clear the contents of the container
document.getElementById("hiddenAlertContainer").innerHTML = "";
// inject the new alert message
document.getElementById("hiddenAlertContainer").innerHTML =
  "All items were removed from your inventory.";
```

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

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

See also
--------

* `aria-live`
* `aria-atomic`
* ARIA: `log` role
* ARIA: `marquee` role
* ARIA: `status` role
* ARIA: `timer` role
* ARIA: `alertdialog` role
* ARIA: live regions
* ARIA alert support - The Paciello Group
* ARIA Practices alert example