ARIA: document structural roles - Accessibility

ARIA: document structural roles
===============================

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

Structural ARIA roles were originally created as a bridge to inform assistive technologies of HTML5 elements that were not yet fully supported in browsers. Some roles, like `presentation`, `toolbar` and `tooltip`, provide information on the document structure to assistive technologies in cases where equivalent native HTML elements don't exist. Other roles, including those listed in the table below, are not needed, as there are semantic HTML elements with the same meanings. In many cases, these equivalent HTML elements have always been supported.

**Note:** These structural roles all have semantic HTML equivalents. They are included here for completeness of documentation. Preferably, they should not be used by web authors.

Some structural roles, like `suggestion`, don't have HTML equivalents, and therefore have separate documentation. Some structural roles with HTML equivalents, like `heading`, have ARIA-attribute requirements. They are listed below with links to their individual role documentation.

Most of the following roles were never needed but were added to ARIA for completeness. We've included them here for completeness as well.

Structural roles with HTML equivalents
--------------------------------------

The structure roles with HTML equivalents are listed below:

| ARIA role & description | HTML Equivalent |
| --- | --- |
| **`associationlist`**Contains only `associationlistitemkey` children and their sibling `associationlistitemvalue`. | `<dl>` |
| **`associationlistitemkey`**Must be contained in an `associationlist`. | `<dt>` |
| **`associationlistitemvalue`**Always a sibling following an `associationlistitemkey`. | `<dd>` |
| **`blockquote`**A section of content that is quoted from another source. | `<blockquote>` |
| **`caption`**Visible content that names, and may also describe, a `figure`, `table`, `grid`, or `treegrid`.Only found in those 4 roles. A caption's `id` is generally referenced by a `figure`, `grid`, `table`, or `treegrid`'s `aria-labelledby` attribute.Prohibited attributes: `aria-label` and `aria-labelledby`. | `<caption>``<figcaption>` |
| **`code`**A section representing a fragment of computer code.Prohibited attributes: `aria-label` and `aria-labelledby`. | `<code>` |
| **`deletion`**Content that is marked as removed or suggested for removal.Prohibited attributes: `aria-label` and `aria-labelledby`. | `<del>` |
| **`emphasis`**Used to stress or emphasize content, but not to suggest importance.Prohibited attributes: `aria-label` and `aria-labelledby`. | `<em>` |
| `figure`Container for a graphical document, images, code snippets, or example text. | `<figure>` |
| `heading`A heading for a section of the page.The `aria-level` attribute is required to indicate the nesting level.See the `heading` role for more information. | h1, h2, h3, h4, h5, and h6 |
| **`image`**Container for a collection of elements that form an image. Synonym for `img` role. | `<img>` |
| `img`Container for a collection of elements that form an image.Accessible name is required.See the `img` role for more information. | `<img>` |
| **`insertion`**Content that is marked as added or content that is being suggested for addition.Prohibited attributes: `aria-label` and `aria-labelledby`. | `<ins>` |
| `list`A section containing `listitem` elements.See `list` role for more information | `<ol>``<ul>` |
| `listitem`A single item in a `list` or `directory`.Must be contained in a `list` (like `<li>`).See `listitem` role for more information. | `<li>` |
| `mark`Marked or highlighted for reference or notation purposes.See `mark` role for more information. | `<mark>` |
| `meter`A scalar measurement within a known range, or a fractional value.Accessible name required. `aria-valuenow` required.See `meter` role for more information. | `<meter>` |
| **`paragraph`**A paragraph of content.Prohibited attributes: `aria-label` and `aria-labelledby`. | `<p>` |
| **`strong`**Important, serious, or urgent content.Prohibited attributes: `aria-label` and `aria-labelledby`. | `<strong>` |
| **`subscript`**One or more subscripted characters.Only use if absence of role would change the content's meaning.Prohibited attributes: `aria-label` and `aria-labelledby`. | `<sub>` |
| **`superscript`**One or more superscripted characters.Only use if absence of role would change the content's meaning.Prohibited attributes: `aria-label` and `aria-labelledby`. | `<sup>` |
| `term`Word or phrase with an optional corresponding definition.Prohibited attributes: `aria-label` and `aria-labelledby`.See `term` role for more information. | `<dfn>` |
| **`time`**A valid date or time string format list a specific point in time.Prohibited attributes: `aria-label` and `aria-labelledby`. | `<time>` |

**Note:** The `aria-label` and `aria-labelledby` attributes are prohibited on `code`, `caption`, `deletion`, `emphasis`, `generic`, `insertion`, `mark`, `paragraph`, `presentation`, `none`, `strong`, `subscript`, `superscript`, `suggestion`, `term`, and `time`, and should only be used on interactive content.

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

Do not use structural roles. Opt for HTML semantic elements instead.

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

| Specification |
| --- |
| Accessible Rich Internet Applications (WAI-ARIA) # document\_structure\_roles |

See Also
--------


ARIA: menuitemcheckbox role - Accessibility

ARIA: menuitemcheckbox role
===========================

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

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

The items in menu and menubars are menu items. There are three types of menu items: `menuitem`, `menuitemradio`, and `menuitemcheckbox`.

These three 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.

Menu items, including `menuitemcheckbox` elements, may be grouped within `group` elements or separated by elements with the `separator` role or other equivalent native role such as `<fieldset>` and `<hr>`.

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

Similar to the 'checked' attribute of `<input>`s of type `checkbox`, the `aria-checked` attribute of a `menuitemcheckbox` indicates whether the menu item is checked (`true`), unchecked (`false`), or represents a sub-level menu of other menu items that have a mixture of checked and unchecked values (`mixed`). The `mixed` value is similar to the checkbox's `indeterminate` attribute, which gives the appearance of a third, neither checked nor unchecked, state. If missing, the value defaults to `false`.

An accessible name is required. Ideally, the accessible name should come from an associated `<label>` element if using `<input type="checkbox">` 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 `menuitemcheckbox`, set the value with respect to the total number of items in the menu, excluding any separators.

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

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

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

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

```html
<div role="menuitemcheckbox"><h6 role="presentation">Name of my checkbox</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="menuitemcheckbox">Name of my checkbox</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 `menuitemcheckbox` elements within a `menu` or `menubar`.

`aria-checked` (Required)

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

### 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 `menuitemcheckbox` elements.

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

`Enter`

Toggles the `aria-checked` state of the `menuitemcheckbox` and closes the menu.

`Space`

Toggles the `aria-checked` state of the `menuitemcheckbox`. Does not close 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 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. Also handles all keys listed in the keyboard navigation section above.

Examples
--------

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

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

The visual appearance of the selected state is a checked checkbox 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 inheriting the color.

```css
[role="menuitemcheckbox"]::before {
  display: inline-block;
  content: "";
  color: transparent;
  width: 1em;
  text-align: center;
  outline: 1px solid;
  margin-inline-end: 2px;
  font-family: sans-serif;
}
[role="menuitemcheckbox"][aria-checked="true"]::before {
  color: inherit;
  content: "X";
}
```

### 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 checkbox form control instead of recreating a checkbox's functionality with JavaScript and ARIA.

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

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

See Also
--------

* `menuitemradio` role
* `checkbox` role
* `<input type="checkbox">`


ARIA: timer role - Accessibility

ARIA: timer role
================

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

```html
<div role="timer" id="eggtimer">0</div>
```

This defines this `div` element as a timer with no remaining time.

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

The `timer` role indicates to assistive technologies that this part of the web content is a live region containing a timer listing the time remaining or elapsed time. A timer's inner text should be an updating current time measurement. While the value does not necessarily need to be machine parsable, it should continuously update at regular intervals unless the timer is paused or reaches its end-point.

Along with `alert`, `log`, `marquee`, and `status` the `timer` role is a live region and can be modified by live region attributes.

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

`aria-label` or `aria-labelledby`

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

`aria-live`

Elements with the role `timer` have an implicit aria-live value of `off`.

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

If a time limit needs to be in place, for example, for security reasons, the user should have the option to turn it off or extend it. This restriction does not apply if the time limit is due to a live event, such as an auction or a game, or if the time to complete the form is essential for a valid submission.

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

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

See also
--------

* ARIA: `alert` role
* ARIA: `log` role
* ARIA: `marquee` role
* ARIA: `status` role
* ARIA live regions
* `timer` example on Codepen by Heydon Pickering


ARIA: combobox role - Accessibility

ARIA: combobox role
===================

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

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

A `combobox` is a composite widget that combines a named input field with a popup providing possible values for that input field. The purpose of this widget is to improve user experience by helping the user select a value without having to type in the complete value and, optionally depending whether supported values are limited, preventing the user from entering invalid or otherwise unsupported values.

The `combobox` role is set on input that controls another element, such as a listbox or grid, that can dynamically pop up to help the user set the value of the input.

The `combobox` input field can either be a single-line text field that supports editing and typing, similar to a HTML `<input>` with a `<datalist>`, or an element that only displays the current value of the combobox.

A WAI-ARIA combobox only has one attribute that is required that authors specify: `aria-expanded`. However, it also has several other attributes which will be necessary to specify, depending on the combobox's implementation. These include `aria-haspopup`, `aria-controls`, `aria-activedescendant`, and `aria-autocomplete`.

Typically, the initial state of a combobox is collapsed, with `aria-expanded="false"` set. In the collapsed state, only the combobox element and, optionally a sibling button to invoke the popup, are visible. The `aria-expanded`, with the value set to `false`, is required when collapsed, because it indicates to assistive technologies that the widget is expandable.

The combobox is in the expanded state when both the combobox element showing its current value and its associated popup element are visible. When expanded, `aria-expanded="true"` must be set.

The popup element associated with a `combobox` can be either a `listbox`, `tree`, `grid`, or `dialog` element.

Comboboxes have an implicit `aria-haspopup` value of `listbox`, so including this attribute is optional if the popup is a `listbox`. If the combobox popup element is a `tree`, `grid`, or `dialog` (anything other than a `listbox`), the `aria-haspopup` attribute is required. The value of `aria-haspopup` must be either the `tree`, `grid`, `dialog`, or `listbox` role. Note that for this property, `true` means `menu`, so make sure that the value corresponds to the role of the popup, not a Boolean value.

When a combobox's popup is displayed, ensure the `aria-controls` attribute on the combobox element is set to the `id` of the popup `listbox`, `tree`, `grid`, or `dialog` element. This is how the relationship between the element with the `combobox` role and the popup it controls is indicated. (Note: In older ARIA specs, this was `aria-owns` rather than `aria-controls`, so you may see `aria-owns` in older combobox implementations. The `aria-owns` in the code should be updated to `aria-controls`!)

If the combobox UI includes a visible control, such as an icon, that allows the visibility of the popup to be controlled via pointer and touch events, that control should be a `<button>`, `<input>` of type `button`, or a `button` role element with a `tabindex` of `-1`. Doing so will allow the button to be focusable but not included in keyboard tab sequence. It must not be a descendant of the element with role `combobox`.

To be keyboard accessible, keyboard support for moving focus between the `combobox` input field element and elements contained in the popup `listbox`, `tree`, `grid`, or `dialog`, must be programmed in. One common convention is that `Down Arrow` moves focus from the input to the first focusable descendant of the popup element.

The `aria-activedescendant` property can be used to identify the currently active element of the combobox popup, for instance an `option` within a popup `listbox`, for implementations where DOM focus remains on the combobox. If DOM focus does not remain on the combobox when its popup is invoked, but rather DOM focus moves into the popup, such as a dialog, then `aria-activedescendant` may not be necessary.

If the combobox element is an `<input>` element, the value of the combobox is the input's value. Otherwise, the value of the combobox comes from its descendant elements.

If the `combobox` supports text input and provides autocompletion behavior, set `aria-autocomplete` on the combobox element to the value that corresponds to the provided behavior: `inline`, `list`, or `both`. The `aria-autocomplete` attribute indicates that inputting text will trigger display of one or more predictions of the user's intended value for the combobox and specifies how the predictions will be presented when made.

Every `combobox` must have an accessible name. If using an `<input>` element, the accessible name should come from the associated `<label>`. If not, if an appropriate label is visible in the content, provide the name via `aria-labelledby`. In other words, if there is an element in the user interface that serves as a label for the `combobox` input field, include `aria-labelledby` as an attribute on the element with the role of `combobox`, and set the value of the attribute to the `id` of the labelling element or elements. If no visible label is present, use `aria-label` instead. Not both.

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

`aria-expanded`

Required. Identifies whether the combobox is open (`true`) or closed (`false`).

`aria-haspopup`

Implied. If omitted, defaults to `listbox`. Also supports `tree`, `grid`, or `dialog`. Identifies the combobox has having a popout, and indicates the type.

### Keyboard interactions

`Down Arrow`

Moves focus to the next option, or to the first option if none was selected.

`Alt` + `Down Arrow` (Optional)

If the popup is available but not displayed, displays the popup without moving focus.

`Up Arrow`

Moves focus to the previous option. Moving focus to the first option if focus was originally on the last option.

`Alt` + `Up Arrow` (Optional)

If the popup has focus, returns focus to the combobox, otherwise it closes the popup.

`Enter`

If the combobox is editable and an autocomplete suggestion is selected in the popup, accepts the suggestion either by placing the input cursor at the end of the accepted value in the combobox or by performing a default action on the value. For example, in a messaging application, the default action may be to add the accepted value to a list of message recipients and then clear the combobox so the user can add another recipient.

Examples
--------

```html
<label for="jokes">Pick what type of jokes you like</label>
<div class="combo-wrap">
  <input
 type="text"
 id="jokes"
 role="combobox"
 aria-controls="joketypes"
 aria-autocomplete="list"
 aria-expanded="false"
 data-active-option="item1"
 aria-activedescendant="" />
  <span aria-hidden="true" data-trigger="multiselect"></span>
  <ul id="joketypes" role="listbox" aria-label="Jokes">
    <li class="active" role="option" id="item1">Puns</li>
    <li class="option" role="option" id="item2">Riddles</li>
    <li class="option" role="option" id="item3">Observations</li>
    <li class="option" role="option" id="item4">Knock-knock</li>
    <li class="option" role="option" id="item5">One liners</li>
  </ul>
</div>
```

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

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

See also
--------

* HTML `<label>` element
* HTML `<select>` element
* HTML `<option>` element
* HTML `<input>` element
* ARIA: `listbox` role
* ARIA: `option` role
* ARIA: `list` role
* ARIA: `listitem` role
* ARIA Best Practices – Combobox
* ARIA Role Model – Combobox
* Accessible combobox module examples by Deque


ARIA: complementary role - Accessibility

ARIA: complementary role
========================

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

```html
<div role="complementary">
  <h2>Our partners</h2>
  <!-- complementary section content -->
</div>
```

This is a sidebar containing links to project sponsors.

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

The `complementary` role is a landmark role. Landmarks can be used by assistive technology to quickly identify and navigate to large sections of the document. Content listed within a container with the `complementary` landmark role should make sense if separated from the main content of the document.

**Note:** Using the `<aside>` element will automatically communicate a section has a role of `complementary`. Developers should always prefer using the correct semantic HTML element over using ARIA.

Examples
--------

```html
<div role="complementary">
  <h2>Trending articles</h2>
  <ul>
    <li><a href="#">18 tweets that will make you feel all the feels</a></li>
    <li>
      <a href="#">Stop searching! I've found the perfect lunch containers.</a>
    </li>
    <li>
      <a href="#">The time has come to decide how to call these foods</a>
    </li>
    <li><a href="#">17 really good posts we saw on Tumblr this week</a></li>
    <li><a href="#">10 parent hacks we know work because we tried them</a></li>
  </ul>
</div>
```

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 `<aside>` element will automatically communicate a section has a role of `complementary`. If at all possible, prefer using it instead.

### Labeling landmarks

#### Multiple landmarks

If there is more than one `complementary` landmark role or `<aside>` element in a document, provide a label for each landmark using the `aria-label` attribute, or, if the aside has an appropriately descriptive title, point to it with the `aria-labelledby` attribute. This label will allow an assistive technology user to be able to quickly understand the purpose of each landmark.

```html
<aside aria-label="Note about usage">
  <!-- content -->
</aside>

…

<aside id="sidebar" aria-label="Sponsors">
  <!-- content -->
</aside>
```

#### 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="complementary"` with an of `aria-label="Sidebar"` may be announced redundantly as, "complementary sidebar".

### Added benefits

Certain technologies such as browser extensions can generate lists of all landmark roles present on a page, allowing non-screen reader users to also quickly identify and navigate to large sections of the document.

* Landmarks browser extension
Specifications
--------------

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

See also
--------

* <aside>: The Aside element
* complementary (role): Accessible Rich Internet Applications (WAI-ARIA) 1.1
* Using HTML sections and outlines
* Landmark roles: Using ARIA: Roles, States, and Properties
* Using WAI-ARIA Landmarks – 2013 | The Paciello Group
* Accessible Landmarks | scottohara.me
* Aside Revisited | HTML5 Doctor


ARIA: button role - Accessibility

ARIA: button role
=================

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

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

The button role identifies an element as a button to assistive technology such as screen readers. A button is a widget used to perform actions such as submitting a form, opening a dialog, canceling an action, or performing a command such as inserting a new record or displaying information. Adding `role="button"` tells assistive technology that the element is a button but provides no button functionality. Use `<button>` or `<input>` with `type="button"` instead.

This `button` role can be used in combination with the `aria-pressed` attribute to create toggle buttons.

```html
<div id="saveChanges" tabindex="0" role="button" aria-pressed="false">Save</div>
```

The above example creates a focusable button, but requires JavaScript and CSS to include button appearance and functionality. These are features provided by default when using the `<button>` and `<input>` with `type="button"` elements:

```html
<button type="button" id="saveChanges">Save</button>
```

**Note:** If using `role="button"` instead of the semantic `<button>` or `<input type="button">` elements, you will need to make the element focusable and define event handlers for `click` and `keydown` events. This includes handling the `Enter` and `Space` keypresses in order to process all forms of user input. See the official WAI-ARIA example code.

In addition to the ordinary button widget, `role="button"` should be included when creating a toggle button or menu button using a non-button element.

A toggle button is a two-state button that can be either off (not pressed) or on (pressed). The `aria-pressed` attribute values of `true` or `false` identify a button as a toggle button.

A menu button is a button that controls a menu and has an `aria-haspopup` property attribute set to either `menu` or `true`.

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

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

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

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

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

### Associated ARIA roles, states, and properties

`aria-pressed`

The `aria-pressed` attribute defines the button as a toggle button. The value describes the state of the button. The values include `aria-pressed="false"` when a button is not currently pressed, `aria-pressed="true"` to indicate a button is currently pressed, and `aria-pressed="mixed"` if the button is considered to be partially pressed. If the attribute is omitted or set to its default value of `aria-pressed="undefined"`, the element does not support being pressed.

`aria-expanded`

If the button controls a grouping of other elements, the `aria-expanded` state indicates whether the controlled grouping is currently expanded or collapsed. If the button has `aria-expanded="false"` set, the grouping is not currently expanded; If the button has `aria-expanded="true"` set, it is currently expanded; if the button has `aria-expanded="undefined"` set or the attribute is omitted, it is not expandable.

### Basic buttons

Buttons should always have an accessible name. For most buttons, this name will be the same as the text inside the button, between the opening and closing tags. In some cases, for example buttons represented by icons, the accessible name may be provided from the `aria-label` or `aria-labelledby` attributes.

### Toggle buttons

A toggle button typically has two states: pressed and not pressed. A third mixed state is available for toggle buttons that control other elements, such as other toggle buttons or checkboxes, which do not all share the same value. Whether an element is a toggle button or not can be indicated with the `aria-pressed` attribute in addition to the `button` role (if the element is not already a native button element):

* If `aria-pressed` is not used, or is set to the "undefined" state, the button is not a toggle button.
* If `aria-pressed="false"` is used the button is a toggle button that is currently not pressed.
* If `aria-pressed="true"` is used the button is a toggle button that is currently pressed.
* if `aria-pressed="mixed"` is used, the button is considered to be partially pressed.

As an example, the mute button on an audio player labeled "mute" could indicate that sound is muted by setting the `aria-pressed` state true. The label of a toggle button should not change when its state changes. In our example the label remains "Mute" with a screen reader reading "Mute toggle button pressed" or "Mute toggle button not pressed" depending on the value of `aria-pressed`. If the design were to call for the button label to change from "Mute" to "Unmute," a toggle button would not be appropriate, so the `aria-pressed` attribute would be omitted.

### Keyboard interactions

| Key | Function |
| --- | --- |
| `Enter` | Activates the button. |
| `Space` | Activates the button |

Following button activation, focus is set depending on the type of action the button performs. For example, if clicking the button opens a dialog, the focus should move to the dialog. If the button closes a dialog, focus should return to the button that opened the dialog unless the function performed in the dialog context logically leads to a different element. If the button alters the current context, such as muting and unmuting an audio file, then focus typically remains on the button.

### Required JavaScript Features

#### Required event handlers

Buttons can be operated by mouse, touch, and keyboard users. For native HTML `<button>` elements, the button's `onclick` event fires for mouse clicks and when the user presses `Space` or `Enter` while the button has focus. But if another tag is used to create a button, the `onclick` event only fires when clicked by the mouse cursor, even if `role="button"` is used. Because of this, separate key event handlers must be added to the element so that the button is be triggered when the `Space` or `Enter` key is pressed.

`onclick`

Handles the event raised when the button is activated using a mouse click or touch event.

`onKeyDown`

Handles the event raised when the button is activated using the Enter or Space key on the keyboard. (Note not the deprecated onKeyPress)

Examples
--------

### Basic button example

In this example, a span element has been given the `button` role. Because a `<span>` element is used, the `tabindex` attribute is required to make the button focusable and part of the page's tab order. The included CSS style is provided to make the `<span>` element look like a button, and to provide visual cues when the button has focus.

The `handleBtnClick` and `handleBtnKeyDown` event handlers perform the button's action when activated using a mouse click or the `Space` or `Enter` key. In this case, the action is to add a new name to the list of names.

Try the example by adding a name to the text box. The button will cause the name to be added to a list.

#### HTML

```html
<h1>ARIA Button Example</h1>
<ul id="nameList"></ul>
<label for="newName">Enter your Name: </label>
<input type="text" id="newName" />
<span
 role="button"
 tabindex="0"
 onclick="handleCommand(event)"
 onKeyDown="handleCommand(event)"
 >Add Name</span
>
```

#### CSS

```css
[role="button"] {
  padding: 2px;
  background-color: navy;
  color: white;
  cursor: default;
}
[role="button"]:hover,
[role="button"]:focus,
[role="button"]:active {
  background-color: white;
  color: navy;
}
ul {
  list-style: none;
}
```

#### JavaScript

```js
function handleCommand(event) {
  // Handles both mouse clicks and keyboard
  // activate with Enter or Space

  // Keypresses other then Enter and Space should not trigger a command
  if (
    event instanceof KeyboardEvent &&
    event.key !== "Enter" &&
    event.key !== " "
  ) {
    return;
  }

  // Get the new name value from the input element
  const newNameInput = document.getElementById("newName");
  const name = newNameInput.value;
  newNameInput.value = ""; // clear the text field
  newNameInput.focus(); // give the text field focus to enable entering and additional name.

  // Don't add blank entries to the list.
  if (name.length > 0) {
    const listItem = document.createElement("li");
    listItem.appendChild(document.createTextNode(name));

    // Add the new name to the list.
    const list = document.getElementById("nameList");
    list.appendChild(listItem);
  }
}
```

### Toggle button example

In this snippet a `<span>` element is converted to a toggle button using the `button` role and the `aria-pressed` attribute. When the button is activated, the `aria-pressed` value switches states; changing from `true` to `false` and back again.

#### HTML

```html
<button
 type="button"
 onclick="handleBtnClick(event)"
 onKeyDown="handleBtnKeyDown(event)">
  Mute Audio
</button>

<span
 role="button"
 tabindex="0"
 aria-pressed="false"
 onclick="handleBtnClick(event)"
 onKeyDown="handleBtnKeyDown(event)">
  Mute Audio
</span>

<audio
 id="audio"
 src="https://soundbible.com/mp3/Tyrannosaurus%20Rex%20Roar-SoundBible.com-807702404.mp3">
  Your browser does not support the `audio` element.
</audio>
```

#### CSS

```css
button,
[role="button"] {
  padding: 3px;
  border: 2px solid transparent;
}

button:active,
button:focus,
[role="button"][aria-pressed="true"] {
  border: 2px solid #000;
}
```

#### JavaScript

```js
function handleBtnClick(event) {
  toggleButton(event.target);
}

function handleBtnKeyDown(event) {
  // Check to see if space or enter were pressed
  // "Spacebar" for IE11 support
  if (event.key === " " || event.key === "Enter" || event.key === "Spacebar") {
    // Prevent the default action to stop scrolling when space is pressed
    event.preventDefault();
    toggleButton(event.target);
  }
}

function toggleButton(element) {
  const audio = document.getElementById("audio");

  // Check to see if the button is pressed
  const pressed = element.getAttribute("aria-pressed") === "true";

  // Change aria-pressed to the opposite state
  element.setAttribute("aria-pressed", !pressed);

  // Toggle the play state of the audio file
  if (pressed) {
    audio.pause();
  } else {
    audio.play();
  }
}
```

#### Result

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

Buttons are interactive controls and thus focusable. If the `button` role is added to an element that is not focusable by itself (such as `<span>`, `<div>` or `<p>`) then, the `tabindex` attribute has to be used to make the button focusable.

**Warning:** Be careful when marking up links with the button role. Buttons are expected to be triggered using the `Space` or `Enter` key, while links are expected to be triggered using the `Enter` key. In other words, when links are used to behave like buttons, adding `role="button"` alone is not sufficient. It will also be necessary to add a key event handler that listens for the `Space` key in order to be consistent with native buttons.

When the `button` role is used, screen readers announce the element as a button, generally saying "click" followed by the button's accessible name. The accessible name is either the content of the element or the value of an `aria-label` or element referenced by an `aria-labelledby` attribute, or description, if included.

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

If a link performs the action of a button, giving the element `role="button"` helps assistive technology users understand the function of the element. However, a better solution is to adjust the visual design so it matches the function and ARIA role. Where possible, it is recommended to use native HTML buttons (`<button>`, `<input type="button">`, `<input type="submit">`, `<input type="reset">` and `<input type="image">`) rather than the `button` role, as native HTML buttons are supported by all user agents and assistive technology and provide keyboard and focus requirements by default, without need for additional customization.

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

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

See also
--------

* The `<button>` element
* The `<input>` element
* `<input type="button">`
* `<input type="submit">`
* `<input type="reset">`
* `aria-pressed`
* `aria-expanded`
* `aria-haspopup`
* Strong native semantics in HTML5
* Notes on Using ARIA in HTML
* Official WAI-ARIA example code


ARIA: mark role - Accessibility

ARIA: mark role
===============

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

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

The `mark` role semantically denotes HTML elements containing text that is marked/highlighted for reference purposes. This is semantically equivalent to the HTML `<mark>` element. If possible, you should use this element instead.

Example uses for `mark` are the exact same as the `<mark>` element. They include highlighting text in a quotation which is of special interest but is not marked in the original source material, comparable to using a highlighter pen to mark passages of a print article and indicating portions of the content that are relevant to the user's current activity, such as highlighting text matches found by a search feature.

Don't use `mark` for purely decorative styling such as syntax highlighting.

The `mark` element should not be given an accessible name; both `aria-label` and `aria-labelledby` attributes are prohibited on `mark`.

Examples
--------

In the following example we have a document section that has been commented. The commented section is marked up using `<span role="mark">`.

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

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

The related comment is marked up using an HTML structure wrapped with a `<div>` containing `role="comment"`.

To associate the comment with the text being commented, we need to wrap the commented text with an element containing the `aria-details` attribute, the value of which should be the ID of the comment.

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

### Prefer HTML

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

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

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

See also
--------

* HTML `<mark>` element
* ARIA annotations


ARIA: textbox role - Accessibility

ARIA: textbox role
==================

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

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

When an element has the `textbox` role, the browser sends an accessible textbox event to assistive technologies, which can then notify the user about it.

The default is a single line input, in which `Return` or `Enter` submits the form; in this case, it is preferable to use an HTML `<input>` with `type="text"`. To create a multi-line text box which supports line breaks, as in an HTML `<textarea>`, set `aria-multiline="true"`. Including the HTML `contenteditable` attribute ensures the text node is editable.

```html
<!-- Simple text input field -->
<div id="txtboxLabel">Enter your five-digit zipcode</div>
<div
 role="textbox"
 contenteditable="true"
 aria-placeholder="5-digit zipcode"
 aria-labelledby="txtboxLabel"></div>

<!-- Multi-line text area -->
<div id="txtboxMultilineLabel">Enter the tags for the article</div>
<div
 role="textbox"
 contenteditable="true"
 aria-multiline="true"
 aria-labelledby="txtboxMultilineLabel"
 aria-required="true"></div>
```

Semantic elements are more concise and require no JavaScript to support textbox features.

```html
<label for="txtbox">Enter your five-digit zipcode</label>
<input type="text" placeholder="5-digit zipcode" id="txtbox" />

<!-- Multi-line text area -->
<label for="txtboxMultiline">Enter the tags for the article</label>
<textarea id="txtboxMultiline" required></textarea>
```

Where a text field is read-only, indicated this by setting `aria-readonly="true"` on the element.

### Associated ARIA properties

`aria-activedescendant` attribute

Taking as it's value the ID of is either a descendant of the element with DOM focus or is a logical descendant as indicated by the `aria-owns` attribute, it indicates when that element has focus, when it is part of a composite widget such as a `combobox`. For example, in a combobox, focus may remain on the textbox while the value of `aria-activedescendant` on the textbox element refers to a descendant of a popup listbox that is controlled by the textbox. This attribute must be updated programmatically as the focus changes.

`aria-autocomplete` attribute

Indicates whether and how the user's input into the field could trigger display of a prediction of the intended value. It supports the following values:

* `inline`: Predicted text is inserted after the caret.
* `list`: Predicted text is presented as a collection of values.
* `both`: Predicted text is presented as a collection of values, with the text needed to complete one value inserted after the caret.
* `none` (default): Predicted text is not offered.

If list or both is set, the `aria-controls` and `aria-haspopup` attributes should also be included. The value of `aria-controls` is the ID of the element that contains the list of suggested values. Additionally, either the textbox or a containing element with role `combobox` has a value for `aria-haspopup` that matches the role of the element that contains the list of suggested values.

`aria-multiline` attribute

If `aria-multiline="true`" is set, the AT informs the user that the textbox supports multi-line input, with the expectation that

`Enter`

or

`Return`

will create a line break rather than submitting the form. ARIA does not alter the behavior of the element; rather this feature must be controlled by the developer. If false is set, or the attribute is omitted and defaults to false, the user expectation is that the control is a single line text box, and

`Enter`

or

`Return`

submits the form.

`aria-placeholder` attribute

Represents a hint (word or phrase) to the user about what to enter into the text field. The hint should be a sample value or a brief description of the expected format. This information should not be used as a substitute for a label: a label is focusable, permanent, indicates what kind of information is expected, and increases the hit area for setting focus on the control, whereas placeholder text is only temporary hint about the expected value, which if implemented incorrectly can decrease accessibility. The placeholder should be visible when the control's value is the empty string such as when the control first receives focus and when users remove a previously-entered value. Instead of using `aria-placeholder`, use the semantic `<input type="text">` or `<textarea>` with a `placeholder` attribute.

`aria-readonly` attribute

Indicates that the user cannot modify the value of the text field. Instead of using `aria-readonly`, use the semantic `<input type="text">` or `<textarea>` with a `readonly` attribute.

`aria-required` attribute

Indicates that a value must be provided for the field before it is submitted. Instead of using `aria-required`, use the semantic `<input type="text">` or `<textarea>` with a `required` attribute.

### Keyboard interactions

In a single-line use (when `aria-multiline` is `false` or not used), the Return or Enter key submits the form. In a multi-line use (when `aria-multiline` is `true`), Return or Enter key inserts a line break.

### JavaScript features

All features associated with any and all properties and states must be maintained, and forms submission on enter or return on a single line textbox needs to be handled.

Focus event handler and aria-activedescendant attribute

If you are implementing a composite widget, such as a combobox composed of a text box and a listbox, you need to manage the `aria-activedescendant` attribute using a handler. Before using this technique, ensure that the browsers you need to target currently support it. See the specification of aria-descendant for further information.

>
> \*\*Note:\*\*It is a better practice to use an `<input>` element with type="text", or a `<textarea>` element instead of the ARIA textbox role. When using either semantic element, the ARIA textbox role is not necessary. See Notes on Using ARIA in HTML.
>
>
>

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

When the `textbox` role is added to an element, or such an element becomes visible, the user agent should do the following:

* Expose the element as having a textbox role in the operating system's accessibility API.
* Fire an accessible textbox event using the operating system's accessibility API if it supports it.

Assistive technology products should listen for such an event and notify the user accordingly:

* Screen readers should announce its label and role when focus first lands on a textbox. If it also contains content, this should be announced as with a regular textbox.
* Screen magnifiers may enlarge the textbox.

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

Examples
--------

### Example 1: Adding the role in the HTML code for single line input

The snippet below shows how the textbox role is added directly into the HTML source code.

```html
<div role="textbox" contenteditable="true"></div>
```

### Example 2: Adding the role in the HTML code for multi-line input

The snippet below shows how the textbox role is added directly into the HTML source code.

```html
<div role="textbox" contenteditable="true" aria-multiline="true"></div>
```

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

* Be sure to add the `contenteditable="true"` attribute to the HTML element to which this role is applied. Do so even if you set `aria-readonly` to `true`; in this way, you communicate that the content would be editable if it were not read-only.
See also
--------

* ARIA: search role


ARIA: comment role - Accessibility

ARIA: comment role
==================

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

**Note:** The comment role is proposed in WAI-ARIA 1.3 (Most recent ARIA draft), which is still being drafted.

Examples
--------

In the following example we have a document section that has been commented. The commented section is marked up using `<span role="mark">`.

The related comment is marked up using an HTML structure wrapped with a `<div>` containing `role="comment"`.

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

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

To associate the comment with the text being commented, we need to wrap the commented text with an element containing the `aria-details` attribute, the value of which should be the ID of the comment.

### Multiple comments

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

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

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

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

### Nested comments

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

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

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

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

None

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

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

See also
--------

* ARIA annotations


ARIA: presentation role - Accessibility

ARIA: presentation role
=======================

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

The content of the element will still be available to assistive technologies; it is only the semantics of the container — and in some instance, required associated descendants — which will no longer expose their mappings to the accessibility API.

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

While ARIA is primarily used to express semantics, there are some situations where hiding an element's semantics from assistive technologies is helpful. This is done with the `presentation` role or its synonym role `none`, which declare that an element is being used only for presentation and therefore does not have any accessibility semantics.

Writing `<h2 role="presentation">Democracy Dies in Darkness</h2>` removes the heading semantics of the h2 element, making it the equivalent of `<div>Democracy Dies in Darkness</div>`. The heading role semantics are removed, but the content itself is still available.

When an element has required descendants, such as the various `<table>`, elements and `<li>`s children of a `<ul>` or `<ol>`, the `presentation` or `none` role on the table or list removes the default semantics of the element on which it was applied and their required descendant elements.

If `presentation` or `none` is applied to a `<table>` element, the descendant `<caption>`, `<thead>`, `<tbody>`, `<tfoot>`, `<tr>`, `<th>`, and `<td>` elements inherit the role and are thus not exposed to assistive technologies. But, elements inside of the `<th>` and `<td>` elements, including nested tables, are exposed to assistive technologies.

```html
<ul role="presentation">
  <li>
    <a href="#">Link 1</a>
  </li>
  <li>
    <a href="#">Link 2</a>
  </li>
  <li>
    <a href="#">Link 3</a>
  </li>
</ul>
```

Because the `presentation` role was applied to the `<ul>` element, every child `<li>` element inherits the `presentation` role. This is because ARIA requires the `listitem` elements to have a parent `list` element. While the `<li>` elements, in this case, are not exposed to assistive technologies, descendants of those required elements are exposed. If we had nested a list within one of those `<li>`'s, they would be visible to assistive technologies. For elements with no required children, any elements nested inside the element with `role="presentation"` or `role="none"` preserve their semantics. In this case, the `<a>` elements contained inside of those `<li>` elements are exposed.

The `<a>` is a special case. Its role would have been exposed even if it had the `presentation` or `none` role directly applied to it. Browsers ignore `role="presentation"` and `role="none"`on focusable elements, including link and inputs, or anything with a tabindex attribute set. Browsers also ignore the inclusion of the role if any of the element contains any global ARIA states and properties, such as `aria-describedby`.

**Note:** The element with `role="presentation"` is not part of the accessibility tree and should not have an accessible name. Do **not** use `aria-labelledby` or `aria-label`.

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

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

Examples
--------

```html
<hr role="none" />
```

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

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

See Also
--------

* `aria-hidden` versus `role="presentation/none"` - by Scott O'Hara


ARIA: composite role - Accessibility

ARIA: composite role
====================

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

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

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

`Composite` is an abstract role used for the ontology. Don't use this role in content. Instead, use the composite subclasses of `grid`, `select`, `spinbutton`, and `tablist`

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

Do not use.

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

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

See Also
--------

* ARIA: `widget` role
* ARIA: `grid` role
* ARIA: `select` role
* ARIA: `spinbutton` role
* ARIA: `tablist` role


ARIA: note role - Accessibility

ARIA: note role
===============

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

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

The `note` role can be added to parenthetic or ancillary content if no other native element or other role fits the purpose.

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

`aria-label` or `aria-labelledby` (optional)

Naming a note is optional, but can help screen reader users understand its context and purpose. The name can be provided using `aria-labelledby` if a visible label is present, otherwise with `aria-label`.

Examples
--------

```html
<h1>Madam C. J. Walker</h1>
<p>
  Madam C.J. Walker was an African American entrepreneur, philanthropist, and
  political and social activist.
</p>
<h2>Early Life</h2>
…
<h2>Career</h2>
…
<p role="note" class="hilitebox">
  At the height of the depression, Madam C. J. Walker trained 20,000 women to
  sell hair pomade door-to-door
</p>
<h2>Activism and Philanthropy</h2>
…
```

In the above Wikipedia style entry for Madam C.J. Walker, the `hilitebox` with role `note` could have been a `<blockquote>` if it contained a quote or `<figcaption>` in a `<figure>` if there was an associated image. In this case, as neither of those made sense, the `note` role was added to add semantics to the parenthetic content.

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

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

See Also
--------

* Document structure roles


ARIA: img role - Accessibility

ARIA: img role
==============

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

```html
<div role="img" aria-label="Description of the overall image">
  <img src="graphic1.png" alt="" />
  <img src="graphic2.png" />
</div>
```

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

Any set of content that should be consumed as a single image (which could include images, video, audio, code snippets, emojis, or other content) can be identified using `role="img"`.

You shouldn't count on the alt text of individual images for conveying context to assistive technologies; most screen readers will consider the element with `role="img"` set on it to be like a black box, and not access the individual elements inside it. Therefore, provide a comprehensive overall descriptive alt text for image, either in the surrounding text, or by using an `aria-label` attribute, with `alt` attributes for search engines or sighted users to be written to the page should an image fail:

```html
<div role="img" aria-label="Description of the overall image">
  <img src="graphic1.png" alt="alternative text" />
  <img src="graphic2.png" alt="in case the images don't load" />
</div>
```

If you wish to add a caption or label to your image that is visible on the page, you can do using:

* `aria-labelledby` when the text is a concise label.
* `aria-describedby` when the text is a longer description.

For example:

```html
<div role="img" aria-labelledby="image-1">
  …
  <p id="image-1">Text that describes the group of images.</p>
</div>
```

If an image is purely presentational, consider using the `presentation` role.

### SVG and role="img"

If you are using embedded SVG images in your page, it is a good idea to set `role="img"` on the outer `<svg>` element and give it a label. This will cause screen readers to just consider it as a single entity and describe it using the label, rather than trying to read out all the child nodes:

```html
<svg role="img" aria-label="Description of your SVG image">
  <!-- contents of the SVG image -->
</svg>
```

### Using role="img" to confer meaning that is obscured or implied

In certain cases, assistive technology users won't be able to get the meaning of content expressed in certain ways, through certain media, or implied in certain ways. This is obvious to fix in the case of images (you can use the `alt` attribute), but in the case of mixed or other certain types of content it is not so obvious, and `role="img"` can come into play.

For example, if you use emojis in your text, the meaning might be obvious to a sighted user, but someone using a screen reader might get confused because the emojis might have either no text representation at all, or the alternative text might be confusing and not match the context it is being used in. For example, take the following code:

```html
<div role="img" aria-label="That cat is so cute">
  <p>🐈 😂</p>
</div>
```

`🐈 😂`, 🐈 and 😂, are entity references for emojis read out as "Cat" and "Face with tears of joy", but this doesn't necessarily make sense — the implied meaning is possibly more like "That cat is so cute", so we include that in an `aria-label` along with `role="img"`.

This seems to work OK across some browser/screen reader combinations, but some of them end up reading the label out twice. Use with caution and test thoroughly.

Another example where this might be suitable is when using ASCII emoji combinations, like the legendary "Table flip":

```html
<div role="img" aria-label="Table flip">
  <p>(╯°□°）╯︵ ┻━┻</p>
</div>
```

If `aria-labelledby` were used, the screen reader would read it. In this case, only the contents of the `aria-label` are announced to screen reader users, hiding the gibberish of the characters without the need for descendant ARIA to hide things, but also hiding potential content that may be part of the image.

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

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

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

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

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

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

`aria-label` or `aria-labelledby`

An accessible name is required. For the HTML `<img>` element, use the `alt` attribute. For all other elements with the `img` role, use `aria-labelledby` if a visible label is present, otherwise use `aria-label`.

Examples
--------

```html
<span role="img" aria-label="Rating: 4 out of 5 stars">
  <span>★</span>
  <span>★</span>
  <span>★</span>
  <span>★</span>
  <span>☆</span>
</span>
```

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

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

See also
--------

* The `<img>` element
* The `<svg>` element
* The `<picture>` element
* The `<audio>` element
* The `<video>` element
* ARIA: `presentation` role
* Accessibility Object Model
* ARIA in HTML


ARIA: link role - Accessibility

ARIA: link role
===============

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

**Note:** Where possible, it is recommended that you use a native `<a>` element rather than the `link` role, as native elements are more widely supported by user agents and assistive technology. Native `<a>` elements also support keyboard and focus requirements by default, without need for additional customization.

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

The `link` role is used to identify an element that creates a hyperlink to a resource that is in the application or external.

When not using semantic HTML for its intended purpose, interactive features must be re-implemented. For example, when `role="link"` is added to an element, the `tab` key should enable giving focus to the link and the `enter` key should execute the link when focused.

Use the `tabindex` attribute with a value of `0` to ensure the link is in the correct tab focus order.

**Warning:** Applying the `link` role to an element will not cause browsers to enhance the element with standard link appearance or behaviors, such as underlining, focus rings, navigation to the link target, or context menu actions. That's the developer's responsibility.

Examples
--------

To recreate an accessible link using the `link` role on an element that is not an `<a>`, you need to ensure the link receives focus in the correct tab order, that the element looks like a link, and that the "link" behaves like a link.

```html
<span data-href="https://mozilla.org" tabindex="0" role="link">
  Fake accessible link created using a span
</span>
```

### CSS

```css
span[role="link"] {
  color: blue;
  text-decoration: underline;
  cursor: pointer;
}
span[role="link"]:hover,
span[role="link"]:active,
span[role="link"]:focus {
  color: purple;
}

span[role="link"]:focus {
  background-color: palegoldenrod;
  outline: 1px dotted;
}
```

### JavaScript

```js
const fakeLinks = document.querySelectorAll('[role="link"]');

for (let i = 0; i < fakeLinks.length; i++) {
  fakeLinks[i].addEventListener("click", navigateLink);
  fakeLinks[i].addEventListener("keydown", navigateLink);
}

//handles clicks and keydowns on the link
function navigateLink(e) {
  if (e.type === "click" || e.key === "Enter") {
    const ref = e.target ?? e.srcElement;
    if (ref) {
      window.open(ref.getAttribute("data-href"), "\_blank");
    }
  }
}
```

If the element with `role="link"` receives an `Enter` key event, this executes the link, going to the linked page or moving focus to the in page target.

Optionally, `Shift` + `F10` opens a context menu for the link.

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

The various widget roles are used to define common interactive patterns. Similar to the document-structure roles, some of these roles, including the `link` role, duplicate the semantics of native HTML elements that are well supported, and should not be used.

Avoid using `link`, which we've included for completeness. The `<a>` semantic equivalent with accessible interactivity is available and supported.

### Prefer HTML

Using the `<a>` instead.

**Note:** There is no need to include `role="link"` on an HTML link as the `<a>`, by default, has that role already.

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

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

See also
--------

* The `<a>` element
* The `<button>` element
* `aria-label`
* ARIA practices `link` role examples


ARIA: contentinfo role - Accessibility

ARIA: contentinfo role
======================

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

```html
<div role="contentinfo">
  <h2>Footer</h2>
  <!-- footer content -->
</div>
```

This is a website footer. Using the `<footer>` element instead is recommended:

```html
<footer>
  <h2>Footer</h2>
  <!-- footer content -->
</footer>
```

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

The `contentinfo` role is a landmark used to identify a page footer. Landmarks can be used by assistive technology to quickly identify and navigate to large sections of the document. Pages should only include one top-level `contentinfo` landmark role per page.

Each page should only include one `contentinfo` landmark, created by either using the `<footer>` element or by declaring `role="contentinfo"`. `contentinfo` landmarks present in content embedded via `<iframe>` do not count towards this limit.

**Note:** Using the `<footer>` element will automatically communicate a section has a role of `contentinfo`. Developers should always prefer using the correct semantic HTML element over using ARIA, making sure to test for known issues in VoiceOver.

Examples
--------

```html
<body>
  <!-- other page content -->

  <div role="contentinfo">
    <h2>MDN Web Docs</h2>
    <ul>
      <li><a href="#">Web Technologies</a></li>
      <li><a href="#">Learn Web Development</a></li>
      <li><a href="#">About MDN</a></li>
      <li><a href="#">Feedback</a></li>
    </ul>
    <p>
      © 2005-2012 Mozilla and individual contributors. Content is available
      under <a href="#">these licenses</a>.
    </p>
  </div>
</body>
```

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.

### One `contentinfo` landmark per page

#### The `<body>` element

There should be only one `contentinfo` landmark per document, used as the immediate descendant of the `<body>` element.

#### Mega-footers

Do not nest additional `<footer>` elements or `contentinfo` landmarks inside the document's footer. Use other content sectioning elements instead.

### Labeling landmarks

#### Multiple landmarks

If there is more than one `contentinfo` landmark role or `<footer>` element in a document, provide a label with the `aria-label` attribute for each landmark. This label will allow assistive technology users to quickly understand the purpose of each landmark.

```html
<body>
  …

  <article>
    <h2>Everyday Pad Thai</h2>
    <!-- article content -->
    <footer aria-label="Everyday Pad Thai metadata">
      <p>
        Posted on <time datetime="2021-09-23 12:17">September 23</time> by
        <a href="#">Lisa</a>.
      </p>
    </footer>
  </article>

  …

  <footer aria-label="Footer">
    <!-- footer content -->
  </footer>
</body>
```

#### 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="contentinfo"` with an of `aria-label="Footer"` may be announced redundantly as, "contentinfo footer".

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

### Prefer HTML

When it is an immediate descendant of the `<body>` using the `<footer>` element will automatically communicate a section has a role of `contentinfo` (save for a known issue in VoiceOver). If at all possible, prefer using `<footer>` instead. Note that a `footer` element nested within an `article`, `aside`, `main`, `nav`, or `section` is not considered `contentinfo`.

### Added benefits

Certain technologies such as browser extensions can generate lists of all landmark roles present on a page, allowing non-screen reader users to also quickly identify and navigate to large sections of the document.

* Landmarks browser extension
Specifications
--------------

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

See also
--------

* The `<footer>` element
* contentinfo (role): Accessible Rich Internet Applications (WAI-ARIA) 1.1
* Using HTML sections and outlines
* Using WAI-ARIA Landmarks – 2013 | The Paciello Group
* Accessible Landmarks | scottohara.me
* The Footer Element Update | HTML5 Doctor


ARIA: structure role - Accessibility

ARIA: structure role
====================

The `structure` role is for document structural elements.

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

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

`Structure` is a superclass abstract role for document structures, like as `document`,
 `rowgroup`, and `sectionhead`, that support the accessibility of dynamic web content by helping assistive technologies determine active content versus static document content. Some subclass roles, like
 `section` role, are in turn superclasses of other roles.

The `structure` role is the superclass for all document structure roles, which are used to provide a structural description for a section of content. Most structure roles should no longer be used as browsers now support semantic HTML element with the same meaning. The structure roles without HTML equivalents, such as the `presentation` role which means content is presentational only, provide information on the document structure to assistive technologies such as screen readers as equivalent native HTML tags are not available.

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

Do not use `role="structure"`. Do use HTML and subclass structure roles.

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

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

See Also
--------

* ARIA: `roletype` role
* ARIA: `generic` role
* ARIA: `presentation` role
* ARIA: `range` role
* ARIA: `section` role
* ARIA: `sectionhead` role


ARIA: none role - Accessibility

ARIA: none role
===============

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

See the `presentation` role for more information.


ARIA: marquee role - Accessibility

ARIA: marquee role
==================

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

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

The `marquee` role defines an area as a type of live region that presents non-essential information that changes frequently. Examples of marquees include stock tickers and ad banners; information that is not necessarily sought out by the user that may be presented in any order. The main difference between a `marquee` and a `log` is that log information is presented in a meaningful order such as a by date.

Elements with the role marquee have an implicit aria-live value of `off`.

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

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

`aria-live`

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

`aria-label` or `aria-labelledby`

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

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

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

See Also
--------

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


ARIA: option role - Accessibility

ARIA: option role
=================

The `option` role is used for selectable items in a `listbox`.

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

The `option` role is used to identify selections a user can make in a `listbox`. These options are similar to the `<option>` elements in a `<select>` element, but they can contain images.

All selectable options should have `aria-selected` match their state, `true` when selected and `false` when not. If an option is not selectable, `aria-selected` can be omitted. A disabled option can have `aria-disabled="true"` and `aria-selected="false"` to communicate to the user that the option is present, albeit disabled.

The `option` role is for identifying selectable choices of a `listbox`. Options must be provided an accessible name. Generally, the accessible name for an option should come from the element's descendant content.

Authors can also explicitly provide an accessible name by specifying `aria-label` or `aria-labelledby` to the element with the `option` role. If using `aria-label` or `aria-labelledby`, and the option also displays a visible text label, authors must ensure they adhere to WCAG Success Criterion 2.5.3 Label in Name.

It is highly recommended to use a `<select>` element or an `<input>` element with the `checkbox` or `radio` type instead, when possible. These native HTML elements provide keyboard interactivity to manage focus for all the descendants for you automatically.

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

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

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

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

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

### Associated ARIA roles, states, and properties

#### Associated Roles

`listbox`

An `option` *must* be contained in or owned by a `listbox`

#### States and Properties

`aria-selected`

Used to describe the selection state of the option. Required.

`aria-checked`

Used to describe the checked state when options are used in a multiple selection fashion. Supports `true`, `false` and `mixed`. Optional.

`aria-posinset`

Used to describe the position in the set of options when it does not match the DOM, such as virtual scrolling where only some options are present at a time. Optional.

`aria-setsize`

Used in conjunction with `aria-posinset` to declare the total number of options. Optional.

`aria-disabled`

Used to indicate that the option is present but not editable. Optional.

`aria-hidden`

Used to hide the option from accessibility tools. It should only be used to hide non-visible content or visible content if it improves the experience of assistive technology, such as redundant content. Optional.

`aria-invalid`

Used to indicate that the value of the option is considered invalid by the application. Optional.

`aria-busy`

Used to indicate that an element is being modified, such as while it is loading. Optional.

`aria-labelledby`

Used to indicate which element labels the option. The content of the option should be used instead where appropriate. Optional.

`aria-label`

Used to label the option. If the label is present in the DOM, `aria-labelledby` should be used instead. Optional.

(For further details and a full list of ARIA states and properties see the ARIA `option` (role) documentation.)

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

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

See also
--------

* HTML `<select>` element
* HTML `<label>` element
* HTML `<option>` element
* ARIA: `combobox` role
* ARIA: `list` role
* ARIA: `listbox` role


ARIA: scrollbar role - Accessibility

ARIA: scrollbar role
====================

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

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

A `scrollbar` is a range that controls what part of a viewport's content is currently visible in the viewport's frame; whether the viewport is a full browser size, an iframe, or any element's block formatting context.

### What is scroll bar

Many applications provide native scroll bars when the content area is larger than the application window. Scrollbars generally appear on the right or bottom of the viewing area. Native scroll bars appear as thin rectangular track areas the length of the viewport it controls with a piece of UI called a thumb or scroller that can be dragged along a track to move the associated content within the viewport. Some scrollbars have arrows at each end of the track that allow scrolling the viewport a short set distance when activated.

Take this document as an example: if the viewport is the full browser window and the content is taller than the viewport, in most browsers the scroll bar on the right edge of the window represents the overall length of the page and the scroll thumb represents the portion of the page content that is currently in the viewport.

Scroll bars may also appear on viewports that are sub-sections of the full browser window. Continuing with this content as our example, if this content is embedded in an `<iframe>` or `<object>`, the native vertical scroll bar will be the height of the frame. A scroll bar generally is the length of the viewport, but isn't required to be.

If you aren't currently seeing a scroll bar, it may be because your browser only displays the scroll bar when scrolling or only when an element's content is too big to fit in its block formatting context. Depending on the browser and operating system, scroll bars can be made to be visible even when the content fits in the viewport when no scrolling is necessary or even possible.

### ARIA `scrollbar`

It is always best to use native scroll bars. You can use the CSS `overflow` property to ensure the appearance of native scroll bars. A CSS scrollbar specification is being developed. Some browsers allow styling scroll bars via prefixed pseudo-elements.

Because native scroll bar styling has historically been limited, you may come across a scrollbar implemented in JavaScript that you need to support and make fully accessible. For this, you can use the `scrollbar` role to inform assistive technologies that a UI control is an interactive scrollbar.

An element with the `scrollbar` role is a graphical object that controls the scrolling of content within a viewing area; it is the ARIA role which indicates an element is a scroll bar. The HTML element that is most similar is the `range` `<input>` type, `<input type="range">`.

The `scrollbar` element has two required attributes: `aria-controls` and `aria-valuenow`. The `aria-controls` attribute references the `id` of the scrollable area it controls. The `aria-valuenow` property defines the current value of the scrollbar.

While the `aria-valuenow` is always required, the `aria-valuemin` and `aria-valuemax` properties only need to be set for the scrollbar role when the `scrollbar`'s minimum value is not 0 or the maximum value is not 100. The value of `aria-valuenow` must always be between the minimum and maximum inclusive values, or between `0` and `100` inclusive if the minimum and maximum values default to `0` and `100` respectively. `aria-valuenow` communicates how close the viewport is to the bottom of the document. Think of it like a progress bar, where the start of the document is the minimum value and the end of the document is the maximum value.

A `scrollbar` represents the current value and range of possible values via the size of the scrollbar and position of the thumb with respect to the visible range of the orientation (horizontal or vertical) it controls. In other words, the `scrollbar` length (height or width) represents all the content within a viewport. The `aria-valuemin` value represents the beginning of the content and the scrollbar, the `aria-valuemax` value represents the end of the content and the end of the scrollbar. The `aria-valuenow` represents the content that is currently visible in the viewport and the current position, or value, of the movable thumb. The `aria-valuenow` value will generally be exposed as a percentage between `aria-valuemin` and `aria-valuemax` calculated by assistive technologies.

**Note:** Assistive technologies generally render the value of `aria-valuenow` as a percent of a range between the value of `aria-valuemin` and `aria-valuemax`, unless `aria-valuetext` is set. It is recommended to set the values for `aria-valuemin`, `aria-valuemax`, and `aria-valuenow` in a manner that is appropriate for this calculation.

Like a native scroll bar, users interact with `scrollbar` elements directly or indirectly using mouse, touchpad, keyboard, and voice input. `scrollbar` role implementations must also accommodate all these interaction methods.

When using a mouse, the user must be able to activate the `scrollbar` by clicking the scroll arrows at either end of the scroll bar, if present, clicking an empty portion of the scroll track, as well as clicking and dragging the scroll thumb.

Keyboard scrolling must also be supported. When focus is within the viewport controlled by a `scrollbar`, the `Up Arrow` and `Down Arrow` (or `Left Arrow` and `Right Arrow` for a horizontal scroll bar) should move the scroll bar thumb proportionally. Additionally, the `Page Up`, `Page Down`, `Space`, and `Shift + Space` keys must move the content and the scroll thumb the height (or width) of the viewport for each key press until the bottom or top (or left or right) of the content is in view.

JavaScript must be used to translate the `scrollbar` action into scrolling commands, providing the user with feedback by:

1. Visually updating the `scrollbar` element,
2. Scrolling the viewport's content, and
3. Updating the `aria-valuenow` property value.

The default orientation of the `scrollbar` role is vertical. Including `aria-orientation="vertical"`, in this case, is optional. The orientation represents the orientation of the scrollbar and the scrolling effect on the viewing area controlled by the scrollbar. If the scrolling is left to right or right to left and not top to bottom, include `aria-orientation="horizontal"` on the element with the `scrollbar` role.

**Note:** An accessible name is **required**. If the `scrollbar` role is applied to an HTML `<input>` element (or `<meter>` or `<progress>` element), the accessible name can come from the associated `<label>`. Otherwise use `aria-labelledby` if a visible label is present or `aria-label` if a visible label is not present.

### All descendants are presentational

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

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

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

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

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

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

`aria-controls` (Required)

Identifies the viewport, via the `id`, whose contents controlled by the scrollbar.

`aria-valuenow` (Required)

Set to a decimal value between `0`, or `aria-valuemin` if present, and `aria-valuemax` indicating the current value of the scrollbar.

`aria-valuetext`

Assistive technologies often present the value of `aria-valuenow` as a percentage. If this would not be helpful, use this property to make the scrollbar value more understandable to users.

`aria-valuemin`

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

`aria-valuemax`

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

`aria-labelledby`

When not using a native form control and therefore not able to associate the scrollbar with a `<label>`, if visible text is available that can provide the required accessible name, set to the `id` of an element containing text serving as a label. Otherwise, use `aria-label`.

`aria-label`

If no `<label>` can be used, and no visible text is present that can be referenced by `aria-labelledby`, provides the string value that labels the `scrollbar` element providing the required accessible name.

`aria-orientation`

By default, the orientation is `vertical`. The property can be included and set to `horizontal`, `undefined` (the default for all roles unless otherwise specified), or `vertical`.

### Keyboard interactions

`Up Arrow`

The content in the viewport moves up one line with the thumb moving up the scroll bar slider proportionally, until the top of the content and scrollbar are reached.

`Down Arrow`

The content in the viewport moves down one line with the thumb moving down the scroll bar slider proportionally, until the bottom of the content and scrollbar are reached.

`Left Arrow`

With horizontal scrolling, the content in the viewport moves left the width of one character with the thumb moving left across the scroll bar slider proportionally, until the left edge of the content abuts the left end of the viewport and the thumb is aligned on the left end of the scrollbar.

`Right Arrow`

With horizontal scrolling, the content in the viewport moves right the width of one character with the thumb moving right across the scroll bar slider proportionally, until the right edge of the content abuts the right end of the viewport and the thumb is aligned on the right end of the scrollbar.

`Page Up` and `Shift + Space`

The content in the viewport moves up the height of one viewport with the thumb moving up the scroll bar slider proportionally, until the top of the content and scrollbar are reached.

`Page Down` and `Space`

The content in the viewport moves down the height of one viewport with the thumb moving down the scroll bar slider proportionally, until the bottom of the content and scrollbar are reached.the bottom or top of the content is in view.

Examples
--------

The following is an example of a word likely being too long for a parent container.

```html
<span id="pi-label">Pi</div>
<div id="pi">
3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986280348253421170679
</div>
<div
 role="scrollbar"
 aria-labelledby="pi-label"
 aria-controls="pi"
 aria-orientation="horizontal"
 aria-valuenow="0"
 aria-valuemin="0"
 aria-valuemax="100">
  <div id="thumb"></div>
</div>
```

When using the ARIA roles instead of native UI features, CSS must be used to style the scrollbar and thumb and JavaScript must be used to handle all keyboard and pointer events.

CSS could have been used to ensure the overflowing value of PI had a native scrollbar:

```html
<h3 id="PI">Pi</h3>
<p class="pi" tabindex="0" aria-labelledby="PI">
  3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986280348253421170679
</p>
```

```css
.pi {
  overflow: auto;
  max-width: 100%;
}
```

The above CSS means a native scroll bar will appear when the user interacts with the paragraph's viewport if the length of the longest word in the paragraph is wider than the paragraphs containing box. The `tabindex` attribute was added to allow people using a keyboard to navigate to, and scroll around the overflowed content.

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

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

See Also
--------

* `<input type="range">`,
* HTML `<progress>` element
* HTML `<meter>` element
* Other range widgets include:
    + `meter`
    + `slider`
    + `separator` (if focusable)
    + `progressbar`
    + `spinbutton`
* Document `scroll` event