ARIA: menu role - Accessibility

ARIA: menu role
===============

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

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

A `menu` generally represents a grouping of common actions or functions that the user can invoke. The `menu` role is appropriate when a list of menu items is presented in a manner similar to a menu on a desktop application. Submenus, also known as pop-up menus, also have the role `menu`.

While the term "menu" is a generically used term to describe site navigation, the `menu` role is for a list of actions or functions that require complex functionality, such as composite widget focus management and first-character navigation

A menu can be a permanently visible list of controls or a widget that can be made to open and close. A closed `menu` widget is usually opened, or made visible, by activating a menu button, choosing an item in a menu that opens a submenu, or by invoking a command, such as `Shift + F10` in Windows which opens a context specific menu.

When a user activates a choice in a menu that has been opened, the menu usually closes. If the menu choice action invokes a submenu, the menu will remain open and the submenu is displayed.

When a menu opens, keyboard focus is placed on the first menu item. To be keyboard accessible, you need to manage focus for all descendants: all menu items within the `menu` are focusable. The menu button which opens the menu and the menu items, rather than the menu itself, are the focusable elements.

Menu items include `menuitem`, `menuitemcheckbox`, and `menuitemradio`. Disabled menu items are focusable but cannot be activated.

Menu items can be grouped in elements with the `group` role, and separated by elements with role `separator`. Neither `group` nor `separator` receive focus or are interactive.

If a `menu` is opened as a result of a context action, `Escape` or `Enter` may return focus to the invoking context. If focus was on the menu button, `Enter` opens the menu, giving focus to the first menu item. If focus is on the menu itself, `Escape` closes the menu and returns focus to the menu button or parent menubar item (or the context action that opened the menu).

Elements with the role `menu` have an implicit `aria-orientation` value of `vertical`. For horizontally oriented menu, use `aria-orientation="horizontal"`.

If the menu is visually persistent, consider the `menubar` role instead.

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

`menuitem`, `menuitemcheckbox`, and `menuitemradio` roles

Roles of items contained in a containing `menu` or `menubar`, known collectively as "menu items". These must be able to receive focus.

`group` role

Menu items can be nested in a `group`

`separator` role

A divider that separates and distinguishes sections of content or groups of menu items within the menu

`tabindex` attribute

The `menu` container has `tabindex` set to `-1` or `0` and each item in the menu has `tabindex` set to `-1`.

`aria-activedescendant`

Set to the ID of the focused item, if there is one.

`aria-orientation`

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

`aria-label` or `aria-labelledby`

The `menu` is required to have an accessible name. Use `aria-labelledby` if a visible label is present, otherwise use `aria-label`. Either include the `aria-labelledby` set to a the `id` to the `menuitem` or `button` that controls its display or use `aria-label` to define the label.

`aria-owns`

Only set on the menu container to include elements that are not DOM children of the container. If set, those elements will appear in the reading order in the sequence they are referenced and after any items that are DOM children. When managing focus, ensure the visual focus order matches this assistive technology reading order.

### Keyboard interactions

`Space` / `Enter`

If the item is a parent menu item, it opens the submenu and moves focus to the first item in the submenu. Otherwise, activates the menu item, which loads new content and places focus on the heading that titles the content.

`Escape`

When in a submenu, it closes the submenu and moves focus to the parent menu or menubar item.

`Right Arrow`

In a menubar, moves focus to the next item in the menubar. If focus is on the last item, it moves focus to the first item. If in a submenu, if focus is on an item that does not have a submenu, it closes the submenu and moves focus to the next item in the menubar. Otherwise, it opens the submenu of the newly focused menubar item, keeping focus on that parent menubar item. If not in a menubar or submenu and not on a `menuitem` with a submenu, if focus is not the last focusable element in the menu, it optionally moves focus to the next focusable element.

`Left Arrow`

Moves focus to the previous item in the menubar. If focus is on the first item, it moves focus to the last item. If in a submenu, it closes the submenu and moves focus to the parent menu item. If not in a menubar or submenu, if focus is not the first focusable element in the menu, it optionally moves focus to the last focusable element.

`Down Arrow`

Opens submenu and moves focus to the first item in the submenu.

`Up Arrow`

Opens submenu and moves focus to the last item in the submenu.

`Home`

Moves focus to the first item in the menubar.

`End`

Moves focus to the last item in the menubar.

Any character key

Moves focus to the next item in the menubar 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.

Examples
--------

Below are two example menu implementations.

### Example 1: navigation menu

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

To progressively enhance this navigation widget that is by default accessible, the class to hide the `menu` and the inclusion of `tabindex="-1"` on the interactive menuitem content should be added with JavaScript on load.

When including a "menu" for site navigation, do not use the `menu` role. Rather, for the main site navigation use the native HTML `<nav>` element or simply a list of links. The `menu` role should be reserved for composite widgets requiring focus management. See ARIA practices for disclosure navigation for an explanation and additional examples.

### Example 2: menubar submenu option picker

The following snippet of code is a popup menu nested in a menubar. It is displayed when the menu button is activated. It is a menu to select the text color from a list of color options:

```html
<div>
  <button
 type="button"
 aria-haspopup="menu"
 aria-controls="colormenu"
 tabindex="0"
 aria-label="Text Color: purple">
    Purple
    <span></span>
  </button>
  <ul role="menu" id="colormenu" aria-label="Color Options" tabindex="-1">
    <li
 role="menuitemradio"
 aria-checked="true"
 style="color: purple"
 tabindex="-1">
      Purple
    </li>
    <li
 role="menuitemradio"
 aria-checked="false"
 style="color: magenta"
 tabindex="-1">
      Magenta
    </li>
    <li
 role="menuitemradio"
 aria-checked="false"
 style="color: black;"
 tabindex="-1">
      Black
    </li>
  </ul>
</div>
```

The button that opens the menu has `aria-haspopup="menu"` set, explicitly indicating that the popup it controls is a `menu`.

For a menu to open, the user generally interacts with a menu button as the opener. The menu button must be focusable and respond to both click and keyboard events. When focused, selecting `Enter`, `Space`, `Down Arrow`, or the `Up Arrow` should open the menu and place focus on a menu item.

The opening and closing of the menu toggles the `aria-expanded="true"` attribute on the button. It is added when the menu is open. Removed or set to `false` when the menu is closed. The `true` value indicates that the menu is displayed and that activating the menu button closes the menu.

When the menu is open, the button itself generally does not receive focus as users arrow through the menu items. Rather, `Escape` and optionally `Shift + Tab` closes the menu and returns focus to the menu button.

The `menu` role was set on the `<ul>`, identifying the `<ul>` element as a menu.

The showing and hiding of the menu can be done with CSS. For example, in these code examples we can use the attribute and next-sibling selectors to toggle the visibility of the menu:

```css
[role="menu"] {
  display: none;
}
[aria-expanded="true"] + [role="menu"] {
  display: block;
}
```

The navigation example has a static button. The submenu example has a button that gets updated when the user selects a new value. In this case, the `aria-label="Text Color: purple"` is set on the `menu` element. It defines the accessible name for the menu as "Text color: purple"; identifying the purpose of the menu (selecting a text color) and the current value (purple). When a new color is selected, the value of the `aria-label` property should be updated as well.

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

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

See Also
--------

* `menubar`
* `menuitem`
* `menuitemcheckbox`
* `menuitemradio`
* `aria-haspopup`


ARIA: tablist role - Accessibility

ARIA: tablist role
==================

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

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

You may be interacting with a tabbed interface as you read this! Browser tabs allow a user have multiple web pages open in a single window. Clicking on a tab in the tablist at the top of the browser window enables the user to display the associated content in the main content area, the tabpanel, one site at a time. This is called a "tab design pattern".

When implementing a tab design pattern, the `tab`, `tablist` and `tabpanel` roles are used.

Tabs are a set of layered sections of content, known as tab panels, that display one panel of content at a time. Each tab panel has an associated `tab` element, that, when activated, displays the panel. The list of tab elements is arranged along one edge of the currently displayed panel, most commonly the top edge, nested in a `tablist` element.

Each `tab` in a `tablist` serves as a label for one `tabpanel` and can be activated to display that panel. The `tablist` is the containing element for the set of tab elements contained.

When a tabbed interface is initialized, one tab panel is displayed and its associated tab is styled to indicate that it is active. When the user activates one of the other tab elements, the previously displayed tab panel is hidden, the tab panel associated with the activated tab becomes visible, and the tab is considered "active".

For a single-selectable tablist, the non-active tabpanel elements should be hidden from the user until the user selects the tab associated with that tabpanel.

When creating a multi-selectable tablist, include `aria-multiselectable="true"` on the `tablist element`.

The `tab` elements not the `tablist`, have the `aria-selected` attribute. Set to `aria-selected="true"` for the tabs associated with each visible tabpanel. The tabs associated with hidden tabpanel elements have their `aria-selected` attributes set to `false`.

If the tab list has a visible label, set `aria-labelledby` to the `id` of the labelling element. If not, use `aria-label` to provide a label.

To be keyboard accessible, focus must be managed for the descendants of this role.

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

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

`tab` role

Required Owned Elements. Every tablist must have one or more `tab` children.

`aria-multiselectable`

When set to `true`, indicates the user may select more than one `tab` from the `tablist` descendants.

`aria-orientation`

If the tablist element is vertically oriented, set `aria-orientation="vertical"`. The default is `horizontal`.

### Keyboard interactions

For the tab list:

`Tab`

When focus moves into the tab list, places focus on the active `tab` element.

When the tab list contains the focus, moves focus to the next element in the page tab sequence outside the tablist, which is the tabpanel unless the first element containing meaningful content inside the tabpanel is focusable.

When focus is on a tab element in a horizontal tab list:

`Left Arrow`

moves focus to the previous tab. If focus is on the first tab, moves focus to the last tab. Optionally, activates the newly focused tab

`Right Arrow`

Moves focus to the next tab. If focus is on the last tab element, moves focus to the first tab. Optionally, activates the newly focused tab

When focus is on a tab element in a vertical tab list:

`Up Arrow`

moves focus to the previous tab. If focus is on the first tab, moves focus to the last tab. Optionally, activates the newly focused tab

`Down Arrow`

Moves focus to the next tab. If focus is on the last tab element, moves focus to the first tab. Optionally, activates the newly focused tab

If the tab list is horizontal, it does not listen for `Down Arrow` or `Up Arrow` so those keys can provide their normal browser scrolling functions even when focus is inside the tab list.

When focus is on a tab in a tablist with either horizontal or vertical orientation:

`Space` or `Enter`

Activates the tab if it was not activated automatically on focus.

`Home` (Optional)

Moves focus to the first tab. Optionally, activates the newly focused tab

`End` (Optional)

Moves focus to the last tab. Optionally, activates the newly focused tab

`Shift + F10`

If the tab has an associated popup menu, opens the menu.

`Delete` (Optional)

If deletion is allowed, deletes (closes) the current tab element and its associated tab panel, sets focus on the tab following the tab that was closed, and optionally activates the newly focused tab. If there is not a tab that followed the tab that was deleted, e.g., the deleted tab was the right-most tab in a left-to-right horizontal tab list, sets focus on and optionally activates the tab that preceded the deleted tab. If the application allows all tabs to be deleted, and the user deletes the last remaining tab in the tab list, the application moves focus to another element that provides a logical work flow. As an alternative to Delete, or in addition to supporting Delete, the delete function is available in a context menu.

Examples
--------

See the `tabpanel`, `tab`, and `tablist` example in the `tab` role definition.

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

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

See Also
--------

* `tab` role
* `tabpanel` role


ARIA: article role - Accessibility

ARIA: article role
==================

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

```html
<div role="article">
  <h2>Heading of the segment</h2>
  <p>Paragraph for the segment.</p>
  <p>Another paragraph.</p>
  Controls to interact with the article, share it, etc.
</div>
<div role="article">…</div>
```

This example shows two articles side by side on one page that could be structured similarly and are related.

**Note:** Instead of a `<div>` with an `article` role, use the `<article>` element. **Always use native element if available**

Don't use `role="article"`. Instead use the `<article>` element.

```html
<article>
  <h2>Heading of the segment</h2>
  <p>Paragraph for the segment.</p>
  <p>Another paragraph.</p>
  Controls to interact with the article, share it, etc.
</article>
<article>…</article>
```

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

The `article` document structure role denotes a section of a document, page, or site that, if it were standing on its own, could be viewed as a complete document, page or site. The aim of a set of article sections is to indicate their relationship to one another.

Articles are not considered a navigational landmark, but many assistive technologies that support landmarks also support a means to navigate among articles. They may also support indication of nesting relationships within articles.

Articles can be nested, indicating that a nested article directly relates to the one it is nested in, but not necessarily to the ones outside the nesting hierarchy. Reference the examples for specific use cases.

If an article is part of a feed, it can have the `aria-posinset` and `aria-setsize` attributes set to indicate which position within the feed this particular article represents.

Inside an `application` or other widget that causes screen readers and other assistive technologies to be in pass-through mode, an article can be used to indicate that these should switch back to treating the enclosed content as regular web content.

Instead of including the `article` role on a non-semantic element, the `<article>` element should be used. User agents translate this to the appropriate accessibility information just like the `article` role. Using the `<article>` element also helps search engines better discover the structure of a page. Examples of appropriate uses of the `role="article"`, or preferably `<article>`, include blog posts, forum posts, a comment to a forum or blog post, any an item in a social media feed.

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

`aria-posinset`

In the context of a feed, indicates the position of this particular article within that feed, based on a count starting at 1.

`aria-setsize`

In the context of a feed, indicates how many article items there are within that feed.

### Keyboard interactions

This role does not support any specific keyboard interaction.

### Required JavaScript features

Event handlers

This role does not require any event handlers to be present.

Changing attribute values

When constructing a feed, set the `aria-posinset` and `aria-setsize` attributes on each article role to the appropriate values, bearing in mind that `aria-posinset` is 1-based.

**Note:** **Always use native element if available.** Instead of a `<div>` with the `article` role, the `<article>` element should be used.

Examples
--------

* The restaurant recommendations feed display along with its separate documentation from the WAI-ARIA 1.1 authoring practices feed design pattern
Specifications
--------------

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

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

This role corresponds to the `<article>` element in HTML, and that element should be used instead, if possible. This role does not require any specific roles to be present among its children. It is the only role allowed as a direct child of an element with the `feed` role.

See also
--------

* `feed` role
* `section` role
* The `<article>` element
* RSS glossary definition


ARIA: tabpanel role - Accessibility

ARIA: tabpanel role
===================

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

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

The `tabpanel` role indicates the element is a container for the resources associated with a `tab` role, where each `tab` is contained in a `tablist`.

A `tabpanel` is part of a tab interface, a common user experience pattern in which a group of visual tabs allow for quickly switching between multiple layered views. Each tab is defined as such with the `tab` role, and these tabs are contained within an element with the `tablist` role. The `tablist` is often visually positioned above or to the side of a content area, containing the associated tabpanels. The `tabpanel` is the role of the container for each pane of content that is associated with a corresponding `tab` in the tab interface's `tablist`.

In many tab interfaces, only a single `tabpanel` will be visible at a time. However, some interfaces may require multiple tab panels to be displayed at once. In these cases the `tablist` would be provided the `aria-multiselectable` attribute, and the `tab` elements would then use the `aria-expanded` attribute to indicate whether its associated `tabpanel` was visible or not. The tab's selected state would instead be used to indicate which tabpanel is the currently 'active' panel. For example, this could indicate which tabpanel keyboard focus would move to if someone were to press the `tab` key when focused on an tab within the multi-select `tablist`.

In single-select tab interfaces, only the `tabpanel` associated with the currently selected tab is displayed. All other `tabpanel` elements associated with the unselected tabs must be hidden from users. So when tab selection changes, the displayed tabpanel would also, while the previously-displayed tabpanel would then become hidden.

In multi-select tab interfaces, multiple `tabpanel` elements may be displayed, matching the expanded state of their associated `tab` elements.

Tabs do not act as anchor links to individual panels — and upon activation, keyboard focus should remain on the current `tab` element and not automatically move to the newly displayed `tabpanel`. While a tab interface may be progressively enhanced based off an underlying markup pattern of in-page hyperlinks pointing to their associated sections of content, when JavaScript is used to modify these elements into a tabbed interface, the hyperlinks' default behavior should be prevented. Ideally, this could be done by removing or modifying the `href` attribute, as this would have the added benefit of removing the hyperlink-specific menu items from the element's browser context menu.

When keyboard focus is on a `tablist`, or a `tab` within the `tablist`, the `Tab` key should be programmed to move from the focused tab — which may or may not be the selected tab — to the `tabpanel` which represents the currently selected tab.

Each `tab` in a `tablist` can serve as the label for its corresponding `tabpanel`. Include the `id` of each `tab` as the value for each `tabpanel`'s `aria-labelledby` attribute.

You can also optionally associate each `tabpanel` with its associated `tab` by including the `id` of the `tabpanel` as the value of the `tab`'s `aria-controls` attribute.

When a tabbed interface is initialized, one `tabpanel` is displayed and its associated `tab` is styled to indicate that it is active, reflecting its programmatic state. All inactive `tabpanel` elements must be hidden to all users. This is most commonly achieved by use of CSS's `display: none`.

See the ARIA `tab` role article for more information specific to the use of this role.

Include `tabindex="-1"` to allow a `tabpanel` to receive focus without including the `tabpanel` in the page's keyboard focus order.

Make sure to define styles for a `tabpanel` for when it receives focus, optimally using the CSS `:focus` pseudo-class, so keyboard users know there was a change in focus and are aware of what content currently has focus.

Carousels can be created using this tab pattern: A slide picker controls can be marked up as `tabs` in a `tablist` with the slide represented by a `tabpanel` element.

### Associated Roles and Attributes

`tab` role

Controls the visibility of the associated `tabpanel`

`tablist` role

Group of `tab` elements.

`aria-labelledby`

Provides an accessible name. References the `tab` element that controls the panel

`aria-expanded`

Should be used on the necessary `tab` elements if a multi-selectable `tablist` is used.

### Keyboard interaction

See the `tablist` keyboard interactions in the `tablist` role definition.

Example
-------

See the `tabpanel`, `tab`, and `tablist` example in the `tab` role definition.

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

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

See Also
--------

* ARIA `tab` role
* ARIA `tablist` role
* Example: Tabs with Automatic Activation - W3C
* Example: Tabs with Manual Activation -W3C


ARIA: navigation role - Accessibility

ARIA: navigation role
=====================

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

```html
<div role="navigation" aria-label="Main">
  <!-- list of links to main website locations -->
</div>
```

This is a website's main navigation.

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

The `navigation` role is a landmark role. Landmark roles provide a way to identify the organization and structure of a web page. By classifying and labeling sections of a page, structural information conveyed visually through layout is represented programmatically. Screen readers use landmark roles to provide keyboard navigation to important sections of a page. Like the HTML `<nav>` element, navigation landmarks provide a way to identify groups (e.g. lists) of links that are intended to be used for website or page content navigation. If a page includes more than one navigation landmark, each should have a unique label. If two or more navigational landmark on a page have the same set of links, use the same label for each.

It is preferable to use the HTML5 `<nav>` element to define a navigation landmark. If the HTML5 nav element technique is not being used, use a `role="navigation"` attribute to define a navigation landmark.

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

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

`aria-label`

A brief description of the purpose of the navigation, omitting the term "navigation", as the screen reader will read both the role and the contents of the label.

### Keyboard Interactions

None.

### Required JavaScript features

None.

Examples
--------

```html
<div role="navigation" aria-label="Customer service">
  <ul>
    <li><a href="#">Help</a></li>
    <li><a href="#">Order tracking</a></li>
    <li><a href="#">Shipping & Delivery</a></li>
    <li><a href="#">Returns</a></li>
    <li><a href="#">Contact us</a></li>
    <li><a href="#">Find a store</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 `<nav>` element will automatically communicate a section has a role of `navigation`. If at all possible, prefer using it instead.

### Labeling landmarks

#### Multiple landmarks

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

```html
<div id="main-nav" role="navigation" aria-label="Main">
  <!-- content -->
</div>

…

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

#### Repeated landmarks

If a `navigation` landmark role or `<nav>` element in a document is repeated in a document, and both landmarks have identical content, use the same label for each landmark. An example of this would be repeating the main navigation at the top and bottom of the page.

```html
<header>
  <nav id="main-nav" aria-label="Main">
    <!-- list of links to main website locations -->
  </nav>
</header>

…

<footer>
  <nav id="footer-nav" aria-label="Main">
    <!-- list of links to main website locations -->
  </nav>
</footer>
```

#### Redundant descriptions

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

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

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

See also
--------

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


ARIA: group role - Accessibility

ARIA: group role
================

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

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

Most closely related to HTML's `<fieldset>` element, the `group` document structure role is used to identify a set of user interface objects which, as compared to `region`, is not intended to be included in the page's summary or table of contents.

The `group` role should be used to form a logical collection of items with related functionality, such as children in a `tree` widget forming a collection of siblings in a hierarchy, or a collection of items having the same container in a `directory`.

When a `group` is used in the context of `list`, limit the children of the `group` to `listitem` elements. In this case, it is recommended to use multiple ordered or unordered lists, `<ol>` or `<ul>`, with nested `<li>` children.

When used in the context of a `listbox`, the only children allowed are `<option>` elements. In this case, it is recommended to use `<select>`, `<option>` and `<optgroup>` instead.

`Group` elements may be nested.

The `group` role should not be used for major perceivable sections of a page. If a section is significant enough that it should be included in the page's table of contents, use the `region` role or a standard landmark role.

When the role is added to an element, the browser will send out an accessible group event to assistive technology products, which can then notify the user about it.

Examples
--------

The HTML code example below uses the `group` role with a `tree` view:

```html
<div id="tree1" role="tree" tabindex="-1">
  <div
 id="animals"
 class="groupHeader"
 role="presentation"
 aria-owns="animalGroup"
 aria-expanded="true">
    <img role="presentation" tabindex="-1" src="images/treeExpanded.gif" />
    <span role="treeitem" tabindex="0">Animals</span>
  </div>
  <div id="animalGroup" role="group">
    <div id="birds" role="treeitem">
      <span tabindex="-1">Birds</span>
    </div>
    <div
 id="cats"
 class="groupHeader"
 role="presentation"
 aria-owns="catGroup"
 aria-expanded="false">
      <img role="presentation" tabindex="-1" src="images/treeContracted.gif" />
      <span role="treeitem" tabindex="0">Cats</span>
    </div>
    <div id="catGroup" role="group">
      <div id="siamese" role="treeitem">
        <span tabindex="-1">Siamese</span>
      </div>
      <div id="tabby" role="treeitem">
        <span tabindex="-1">Tabby</span>
      </div>
    </div>
  </div>
</div>
```

The following example uses the `group` role with a drop-down `menu` containing `menuitem`s:

```html
<div role="menu">
  <ul role="group">
    <li role="menuitem">Inbox</li>
    <li role="menuitem">Archive</li>
    <li role="menuitem">Trash</li>
  </ul>
  <ul role="group">
    <li role="menuitem">Custom Folder 1</li>
    <li role="menuitem">Custom Folder 2</li>
    <li role="menuitem">Custom Folder 3</li>
  </ul>
  <ul role="group">
    <li role="menuitem">New Folder</li>
  </ul>
</div>
```

This menu could be constructed using `<select>` and `<option>` elements. In this case, the `group` role would be most similar to the `<optgroup>` element.

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

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

See Also
--------

* The `<fieldset>` Element
* ARIA: `section` role
* ARIA: `row` role
* ARIA: `select` role
* ARIA: `toolbar` role


ARIA: radio role - Accessibility

ARIA: radio role
================

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

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

A radio button is a checkable input that when associated with other radio buttons, only one of which can be checked at a time. The radio buttons must be grouped together in a `radiogroup` to indicate which ones affect the same value.

```html
<div role="radiogroup" aria-labelledby="legend25" id="radiogroup25">
  <p id="legend25">Ipsum and lorem?</p>
  <div>
    <span
 role="radio"
 aria-checked="false"
 tabindex="0"
 aria-labelledby="q25\_radio1-label"
 data-value="True"></span>
    <label id="q25\_radio1-label">True</label>
  </div>
  <div>
    <span
 role="radio"
 aria-checked="false"
 tabindex="0"
 aria-labelledby="q25\_radio2-label"
 data-value="False"></span>
    <label id="q25\_radio2-label">False</label>
  </div>
  <div>
    <span
 role="radio"
 aria-checked="true"
 tabindex="0"
 aria-labelledby="q25\_radio3-label"
 data-value="huh?"></span>
    <label id="q25\_radio3-label">What is the question?</label>
  </div>
</div>
```

The `role` attribute only adds semantics; all of the functionality that comes natively with the HTML radio needs to be added with JavaScript and the HTML `tabindex` attribute.

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

```html
<fieldset>
  <legend>Ipsum and lorem?</legend>
  <div>
    <input type="radio" value="True" id="q25\_radio1" name="q25" />
    <label for="q25\_radio1">True</label>
  </div>
  <div>
    <input type="radio" value="False" id="q25\_radio2" name="q25" />
    <label for="q25\_radio2">False</label>
  </div>
  <div>
    <input type="radio" value="huh?" id="q25\_radio3" name="q25" checked />
    <label for="q25\_radio3">What is the question?</label>
  </div>
</fieldset>
```

The native HTML radio form control (`<input type="radio">`) has two states ("checked" or "not checked"). Similarly, an element with `role="radio"` can expose two states through the `aria-checked` attribute: `true` representing the checked state, and `false` representing the unchecked state. The `aria-checked` value of `mixed` is not valid to use for a radio button.

If a radio button is checked, the radio element has `aria-checked` set to `true`. If it is not checked, it has `aria-checked` set to `false`.

Each radio button element has role `radio`. The radio role should always be nested with other associated radios in a `radiogroup`. If it is not possible to nest the radio button within a radio group, use the `id` of the non-grouped radio in a space separated list of values as the value of the `aria-owns` attribute on the `radiogroup` element to indicate the relationship of the `radiogroup` to its radio members.

Each radio element is labelled by its content, has a visible label referenced by `aria-labelledby`, or has a label specified with `aria-label`. The containing `radiogroup` element should either have a visible label referenced by `aria-labelledby` or a label specified with `aria-label`. If elements providing additional information about either the radio group or each radio button are present, those elements should be referenced by the `radiogroup` element or radio elements with the `aria-describedby` property.

As `radio` is an interactive control; it must be focusable and keyboard accessible. If the role is applied to a non-focusable element, use the `tabindex` attribute to change this. The expected keyboard shortcut for activating a radio is the `Space` key. Use JavaScript to toggle the `aria-checked` attribute to `true` when a radio becomes checked while ensuing that all the other radio roles in the group are set to `aria-checked="false"`.

To programmatically indicate that a radio button must be chosen from a radio group the `aria-required` attribute, with a value of `true`, must be specified on the `radiogroup` element. It is not expected to use the `aria-required` attribute on individual ARIA radio buttons.

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

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

```html
<div role="radio"><h6>name of my radio</h6></div>
```

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

```html
<div role="radio"><h6 role="presentation">name of my radio</h6></div>
```

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

```html
<div role="radio">name of my radio</div>
```

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

`radiogroup` role

The radio buttons are contained in or owned by an element with role `radiogroup`. If unable to be nested within a `radiogroup` within the markup, the `aria-owns` attribute of the `radiogroup` contains the `id` values of the non-nested radio buttons in the group.

`aria-checked`

The value of `aria-checked` defines the state of a radio. When used with radio elements, the attribute has one of two possible values:

`true`

The radio is checked.

`false`

The radio is not checked.

**Note:** use the `tabindex` attribute if the `role="radio"` is used on an element that does not natively accept keyboard focus. E.g., a `<div>` or `<span>`.

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

`Tab` + `Shift`

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

`Space`

Checks the radio if not already checked. Unchecks a previously checked radio button in the radio group.

`Right Arrow` and `Down Arrow`

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

`Left Arrow` and `Up Arrow`

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

### Radios in a toolbar

Because arrow keys are used to navigate among elements of a toolbar and the `Tab` key moves focus in and out of a toolbar, when a radio group is nested inside a toolbar, the keyboard interaction of the radio group is slightly different from that of a radio group that is not inside of a toolbar. See `radiogroup` keyboard interactions for more information

Required JavaScript
-------------------

`onClick`

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

`onKeyPress`

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

Examples
--------

The following example uses ARIA to modify otherwise generic elements to be exposed as radio buttons. CSS and JavaScript are used to visually and programmatically modify the checked or unchecked state of the element.

### HTML

```html
<div role="radiogroup" aria-labelledby="legend" id="radiogroup">
  <p id="legend">
    Should you be using the <code>radio</code> role or
    <code><input type="radio"></code>?
  </p>
  <div>
    <span
 role="radio"
 aria-checked="true"
 tabindex="0"
 aria-labelledby="ariaLabel"
 data-value="True"></span>
    <label id="ariaLabel">ARIA role</label>
  </div>
  <div>
    <span
 role="radio"
 aria-checked="false"
 tabindex="0"
 aria-labelledby="htmllabel"
 data-value="False"></span>
    <label id="htmllabel">HTML <code><input type="radio"></code></label>
  </div>
</div>
```

### CSS

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

[role="radio"][aria-checked="true"]::before {
  content: "(x)";
  font-family: monospace;
}

[role="radio"][aria-checked="false"]::before {
  content: "( )";
  font-family: monospace;
}
```

### JavaScript

A lot of JavaScript is required to make radio buttons out of non-semantic HTML.

```js
// initialize all the radio role elements

const radioGroups = document.querySelectorAll('[role="radiogroup"]');

for (let i = 0, groups = radioGroups.length; i < groups; i++) {
  const radios = radioGroups[i].querySelectorAll("[role=radio]");
  for (let j = 0, radiobuttons = radios.length; j < radios; j++) {
    radios[j].addEventListener("keydown", function () {
      handleKeydown();
    });
    radios[j].addEventListener("click", function () {
      handleClick();
    });
  }
}

// handle mouse and touch events
let handleClick = function (event) {
  setChecked(this);
  event.stopPropagation();
  event.preventDefault();
};

// handle key presses
let handleKeydown = function (event) {
  switch (event.keyCode) {
    case 32: // space
    case 12: // return
      currentChecked();
      break;

    case 38: // up
    case 37: // left
      previousRadioChecked();
      break;

    case 40: // down
    case 39: // right
      nextItemChecked();
      break;

    default:
      break;
  }
  event.stopPropagation();
  event.preventDefault();
};

// when a radio is selected, give it focus, set checked to true;
// ensure all other radios in radio group are not checked

setChecked = function () {
  // uncheck all the radios in group
  // iterated through all the radios in radio group
  // eachRadio.tabIndex = -1;
  // eachRadio.setAttribute('aria-checked', 'false');
  // set the selected radio to checked
  // thisRadio.setAttribute('aria-checked', 'true');
  // thisRadio.tabIndex = 0;
  // thisRadio.focus();
  // set the value of the radioGroup to the value of the currently selected radio
};
```

No JavaScript (or even CSS) would be needed had we used semantic HTML element with the name of each radio button in a group of radio buttons being the same:

```html
<fieldset>
  <legend>
    Should you be using the <code>radio</code> role or
    <code><input type="radio"></code>?
  </legend>
  <div>
    <input type="radio" name="bestPractices" id="ariaLabel" value="True" />
    <label for="ariaLabel">ARIA role</label>
  </div>
  <div>
    <input type="radio" name="bestPractices" id="htmllabel" value="False" />
    <label for="htmllabel">HTML <code><input type="radio"></code></label>
  </div>
</fieldset>
```

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

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

See also
--------

* HTML `<input type="radio">` radio button
* HTML `tabindex` attribute
* ARIA: `radiogroup` role
* ARIA: `checkbox` role
* ARIA: `menuitem` role
* ARIA: `menuitemradio` role
* ARIA: `menuitemradio` role
* ARIA: `option` role


ARIA: sectionhead role - Accessibility

ARIA: sectionhead role
======================

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

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

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

The structural `sectionhead` role is an abstract role for the subclass roles that identify the labels or summaries of the sections they label. The role must not be used. The four subclasses — `columnheader`, `heading`, `rowheader`, and `tab`. There are HTML element equivalents, like, `<th scope="col">` for `columnheader`, `<th scope="row">` for rowheader, and any of the HTML headings, h1 through h6 for `heading`. The `tab` role does not currently have an HTML equivalent.

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

Do not use.

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

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

See Also
--------

* ARIA: `structure` role
* ARIA: `columnheader` role
* ARIA: `heading` role
* ARIA: `rowheader` role
* ARIA: `tab` role


ARIA: spinbutton role - Accessibility

ARIA: spinbutton role
=====================

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

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

The `spinbutton` role indicates that the element is an input widget that restricts its value to a set or range of discrete values. The role also comes with increment and decrement functionality. For example, in a widget that enables users to choose an amount to bet in a game of Texas Holdem, the `spinbutton` role can allow users to select a number between the minimum and maximum bets in increments, as allowed by the current game rules.

The spinbutton represents the range of possible values. The value of the spinbutton input represents the current value.

Spinbuttons often have three components, including a text field that displays the current value, an increment button, and a decrement button. The text field is usually the only focusable component because the increment and decrement functions are keyboard accessible via arrow keys. Typically, the text field also allows users to directly edit the value.

In addition to including the `tabindex` attribute to enable spinbutton focus, keyboard and pointer device support must be implemented. Directional keys such as the arrow keys must be supported for keyboard users. Changing the value when increment and decrement buttons are clicked must be supported for pointing devices. See keyboard interactions below.

**Note:** It is recommended to use `<input type="number">` element, or other input types for dates and time that also implicitly have the `role="spinbutton"` semantic, rather than the `spinbutton` role. User agents provide stylized widget for the these input elements which provide default increment, decrement, and native range limiting functionality. When using non-semantic elements, all features of the native semantic element need to be recreated with ARIA attributes, JavaScript, and CSS.

### ARIA range widget options

ARIA provides developers with six different range widget roles, including progressbars, meters, sliders and spinbuttons.

The `progressbar` role, similar to HTML's `<progress>` element, is a read-only range. It indicates the portion of completion of a task, progressing in a single direction, such as a file upload's loading progress bar that eventually reaches 100% when fully loaded.

The `meter` role, similar to HTML's `<meter>` element, is a read-only gauge. It indicates the amount of something within a known range, such as a computer's battery indicator or a car's gas gauge.

The `slider` role, similar to HTML's `input` of type `range`, `<input type="range">`, is a read-write input range. Sliders allow users to select a value between the predefined minimum and maximum values. The user selects a value by moving a slider thumb along a horizontal or vertical slider to select a value.

While all three of these ranges have the same ARIA states and properties, the `spinbutton` role is the only read-write range: it is the only one whose value changes via user interaction. As such, it must be able to receive focus. In addition, keyboard interaction, mouse clicks, and touch interaction must be supported.

**Warning:** To change the spinbutton value, touch-based assistive technologies need to respond to user gestures for increasing and decreasing the value by synthesizing key events.
 Fully test spinbutton widgets using assistive technologies on devices where touch is a primary input mechanism before using the `spinbutton` role (and all range widgets).

#### Common attributes

The `aria-valuemin` attribute sets the minimum value. If omitted or not a number, it defaults to `0` (zero).

The `aria-valuemax` attribute defines the maximum value. If it is missing or not a number, it defaults to `100`.

The `aria-valuenow` attribute value must be between the minimum and maximum values, both inclusive. This attribute is required for `spinbutton` and `meter`, and optional for `progressbar`.

For `spinbutton`, unless using semantic HTML elements like `<input type="number">`, if the value is updated, the `aria-valuenow` value must also be updated programmatically.

The optional `aria-valuetext` attribute is included when the `aria-valuenow` numeric value doesn't reflect the intended value of the spinbutton. The optional minimum, maximum, and current values should be numeric. When the values these numbers represent are not numeric, the `aria-valuetext` attribute should be included with a string value defining the numeric value. For example, if using a spinbutton for t-shirt sizes, the `aria-valuetext` attribute should shift from `XX-Small` through `XX-Large` as the `aria-valuenow` increases.

The `aria-valuetext` value must be updated as the value or `aria-valuenow` is updated. ARIA attributes are supported on semantic HTML elements. While there is no equivalent HTML attribute for `<input>`, you can include `aria-valuetext` on any `<input>` type. When `aria-valuetext` is an important feature for a spinbutton, consider using `<select>` with `<option>` elements instead.

An accessible name is **required**. If the `spinbutton` role is applied to an HTML `<input>` 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.

When not using the HTML `<input>` element to create your spinbutton, include the `tabindex` attribute to make the spinbutton focusable. The `spinbutton` role is user-interactive, and therefore, requires being able to receive focus. Focus should be placed on the spinbutton input and not on the associated buttons that increment and decrement the spinbutton value.

### Descendants limited to buttons or text

There are some types of user interface components that, when represented in a platform accessibility API, can only contain specific content. The children or owned elements of `spinbutton` are limited to a textbox and two buttons. Alternatively, the `spinbutton` role can be applied to a `text` input and sibling buttons can be used to support the increment and decrement functions.

Associated roles, states, and properties
----------------------------------------

`aria-valuenow` (required)

Set to a decimal value between `aria-valuemin` and `aria-valuemax`, indicating the current value of the spinbutton. If not present, there is no default value.

`aria-valuetext`

Assistive technologies often present the value of `aria-valuenow` as a number. If `aria-valuenow` cannot be accurate, use `aria-valuetext` to provide the spinbutton with a more understandable value.

`aria-valuemin`

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

`aria-valuemax`

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

`aria-labelledby`

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

`aria-label`

Defines a string value that labels the spinbutton element. This provides an accessible name to the element when no visible label is available to provide the required accessible name via `<label>` or `aria-labelledby`.

Examples
--------

In the example below, a `spinbutton` role has been defined to allow users to select a day of the month.

```html
<p id="day">Enter the day of the month</p>
<button type="button" tabindex="-1" aria-label="previous day">˱</button>
<div
 role="spinbutton"
 tabindex="0"
 aria-valuenow="1"
 aria-valuetext="first"
 aria-valuemin="1"
 aria-valuemax="31"
 aria-labelledby="day">
  1
</div>
<button type="button" tabindex="-1" aria-label="next day">˲</button>
```

In this example, we included a negative `tabindex` to remove the buttons from the default tabbing order. We also added `tabindex` to a normally non-interactive `<div>` to add the `spinbutton` itself to the tabbing order. This example requires JavaScript to handle keyboard actions when the spinbutton has focus and when a mouse user clicks on the buttons.

### With semantic HTML

This could have also been written using semantic HTML, removing the need for any CSS or JavaScript and also removing the need to include and provide functionality for extraneous incrementing and decrementing buttons. The code snippet below shows the previous example without the `spinbutton` role and using semantic HTML.

```html
<label for="day">Enter the day of the month</label>
<input
 type="number"
 value="1"
 aria-valuetext="first"
 min="1"
 max="31"
 id="day" />
```

In this case, the only JavaScript needed would be to update the `aria-valuetext` when the input value changes, which really is an optional feature in this case.

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

| Key(s) | Action |
| --- | --- |
| Right and Up arrows | Increase the selected value by one step |
| Left and Down arrows | Decrease the selected value by one step |
| Page Up | (Optional) Increase the value by a set amount greater than or equal to one step |
| Page Down | (Optional) Decrease the value by a set amount greater than or equal to one step |
| Home | Set the spinbutton to the minimum value |
| End | Set the spinbutton to the maximum value |

For the optional `Page Up` and `Page Down` keys, the change in spinbutton value should preferably be by an amount larger than the step changes made by Up and Down arrow keys.

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

HTML's `<input type="number">` implicitly has the `role` of `spinbutton`. HTML's `<input type="date">` has 3 nested spin buttons, one each for month, day, and year. When using semantic HTML form elements for their intended purposes, do not use `aria-valuemax` or `aria-valuemin` attributes; use `min` and `max` instead. Otherwise, any global `aria-*` attributes and any other `aria-*` attributes are applicable to the `spinbutton` role.

### Prefer semantic HTML

It is recommended to use the native `<input>` element of type `number`, `<input type="number">`, rather than the `spinbutton` role.

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

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

See also
--------

* `<input type="number">`
* `<input type="date">`
* `<input type="time">`
* Other range widgets include:
    + `meter`
    + `scrollbar`
    + `separator` (if focusable)
    + `progressbar`
    + `slider`
* Working examples:
    + Date picker spin button example
    + Toolbar example: font-size picker


ARIA: rowheader role - Accessibility

ARIA: rowheader role
====================

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

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

`Rowheader` is the header `cell` for a row, establishing a relationship between it and the other cells in the same `row`.

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

It is a structural equivalent to the `<th>` element with a scope of `row`, `<th scope="row">`. Using the native `<th>` HTML element is strongly encouraged.

To create an ARIA row header, add `role="rowheader"` to the element. That row header must be nested within a `row`, which, in turn, is nested within a `rowgroup`, or directly within a `grid`, `table` or `treegrid`.

**Note:** Using the native table elements whenever possible, is strongly encouraged.

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

#### Context roles

role="row"

The only context in which you will find a row. It encompasses a cell or group of cells row, of which only one should be of rowheader type. Similar to the native `<tr>` HTML element.

### Keyboard interactions

None

### Required JavaScript features

None.

**Note:** The first rule of ARIA use is if you can use a native feature with the semantics and behavior you require already built in, instead of re-purposing an element and **adding** an ARIA role, state or property to make it accessible, then do so. Employ the HTML `<table>`, `<tr>`, `<th>`, `<td>`, and other table elements instead of the ARIA table roles whenever possible.

Examples
--------

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

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

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

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

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

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

### Added benefits

none

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

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

See also
--------

* The HTML `<table>` element
* The HTML `<th>` element
* HTML table tutorial
* ARIA `cell` role
* ARIA `row` role
* ARIA `gridcell` role


ARIA: section role - Accessibility

ARIA: section role
==================

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

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

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

 The structural `section` role is an abstract role for categorizing all the section subclass roles. The role must not be used. Some subclasses, like `alert`,
 `note`, and `tooltip` are useful, and can be used to add semantics when no semantic HTML elements quite fit the purpose of a component. Others, like `code`, `figure`, and `subscript`, aren't necessary, as there are HTML element equivalents. In this case, `<code>` `<figure>` and `<sub>`, respectively.

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

Do not use.

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

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

See Also
--------

* ARIA: `structure` role
* ARIA: `alert` role
* ARIA: `associationlist` role
* ARIA: `associationlistitemkey` role
* ARIA: `associationlistitemvalue` role
* ARIA: `blockquote` role
* ARIA: `caption` role
* ARIA: `cell` role
* ARIA: `code` role
* ARIA: `definition` role
* ARIA: `deletion` role
* ARIA: `emphasis` role
* ARIA: `figure` role
* ARIA: `group` role
* ARIA: `img` role
* ARIA: `insertion` role
* ARIA: `landmark` role
* ARIA: `list` role
* ARIA: `listitem` role
* ARIA: `log` role
* ARIA: `mark` role
* ARIA: `marquee` role
* ARIA: `math` role
* ARIA: `note` role
* ARIA: `paragraph` role
* ARIA: `status` role
* ARIA: `strong` role
* ARIA: `subscript` role
* ARIA: `suggestion` role
* ARIA: `superscript` role
* ARIA: `table` role
* ARIA: `tabpanel` role
* ARIA: `term` role
* ARIA: `time` role
* ARIA: `tooltip` role


aria-rowindextext - Accessibility

aria-rowindextext
=================

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

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

When you have a very long table or when you purposefully want to display just a section of a table, not all rows may be present in the DOM. When this happens, we use the `aria-rowcount` with an integer value to define how many rows the table (or grid) would have if all the rows were present and add the `aria-rowindex` property on each row and spanning cell to provide information on the row index within that larger table. When the value of `aria-rowindex` is not meaningful or does not reflect the displayed index, we can also add the `aria-rowindextext` to provide a human-readable text alternative to the `aria-rowindex` integer value.

The `aria-rowindextext` should only be included **in addition to**, not as a replacement of, the `aria-rowindex`. Some assistive technologies use the numeric row index for the purpose of keeping track of the user's position or providing alternative table navigation. The `aria-rowindextext` is useful if that integer value isn't meaningful or does not reflect the displayed index, such as a game of Chess or Battleship.

The `aria-rowindextext` is added to each `<tr>` or to elements with the `row` role. It can also be addition to cells or owned elements of each row.

Values
------

* `<string>`
    + The human-readable text alternative of the numeric `aria-rowindex`
Associated interfaces
---------------------

`Element.ariaRowIndexText`

The `ariaRowIndexText` property, part of the `Element` interface, reflects the value of the `aria-rowindextext` attribute.

`ElementInternals.ariaRowIndexText`

The `ariaRowIndexText` property, part of the `ElementInternals` interface, reflects the value of the `aria-rowindextext` attribute.

Associated roles
----------------

Used in roles:

* `cell`
* `row`

Inherited into roles:

* `columnheader`
* `gridcell`
* `rowheader`
Specifications
--------------

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

See Also
--------

* `aria-rowindex`
* `aria-rowcount`
* `aria-rowspan`
* `aria-colindextext`
* `aria-colindex`


aria-checked - Accessibility

aria-checked
============

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

**Note:** Where possible use an HTML `<input>` element with `type="checkbox"` and `type="radio"` as these have built in semantics and do not require ARIA attributes.

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

The `aria-checked` attribute indicates whether the element is checked (`true`), unchecked (`false)`, or if the checked status is indeterminate (`mixed`), meaning it is neither checked nor unchecked. The `mixed` value is supported by the tri-state input roles of `checkbox` and `menuitemcheckbox`.

The `mixed` value is not supported on `radio`, `menuitemradio`, or `switch` and elements that inherits from these. The value will be false if `mixed` is set when not supported.

```html
<span
 role="checkbox"
 id="checkBoxInput"
 aria-checked="false"
 tabindex="0"
 aria-labelledby="chk15-label"></span>
<label id="chk15-label">Subscribe to the newsletter</label>
```

**Note:** Where possible use an HTML `<input>` element with `type="checkbox"` as this element has built in semantics and does not require ARIA attributes.

The `tabindex` attribute is required to enable focus. JavaScript is required to toggle the `aria-checked` state. And, if this checkbox is part of a submittable form, more JavaScript is required to set a name and a value.

The above could have been written as:

```html
<input type="checkbox" id="chk15-label" name="Subscribe" />
<label for="chk15-label">Subscribe to the newsletter</label>
```

By using the `<input>` element with `type="checkbox"` instead of ARIA, there is no need for any JavaScript.

Values
------

false

The element supports being checked but is not currently checked.

true

The element is checked.

mixed

for `checkbox` and `menuitemcheckbox` only, equivalent to `indeterminate`, indicating a mixed mode value of neither checked nor unchecked.

undefined (default)

The element does not support being checked.

Associated roles
----------------

Used in roles:

* `checkbox`
* `menuitemcheckbox`
* `menuitemradio`
* `option`
* `radio`
* `switch`
Associated interfaces
---------------------

`Element.ariaChecked`

The `ariaChecked` property, part of the `Element` interface, reflects the value of the `aria-checked` attribute.

`ElementInternals.ariaChecked`

The `ariaChecked` property, part of the `ElementInternals` interface, reflects the value of the `aria-checked` attribute.

```js
myHTMLElement.ariaChecked = true;
```

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

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

See Also
--------

* `<input type="checkbox">`
* `<input type="radio">`
* `aria-pressed`
* `aria-selected`
* Two state checkbox example - w3.org
* Mix-state checkbox example - w3.org


aria-valuenow - Accessibility

aria-valuenow
=============

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

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

The `aria-valuenow` attribute defines the current value for range widgets. It is similar to the `value` attribute of `<progress>`, `<meter>`, and `<input>` of type `range`, `number` and all the date-time types.

When creating a range type role, including `meter`, `scrollbar`, `slider`, and `spinbutton` on a non-semantic element, the `aria-valuenow` enables defining a current numeric value between the minimum and maximum values. The minimum and maximum values are defined with `aria-valuemin` and `aria-valuemax`.

**Warning:** The `range` role itself should **NOT** be used as it is an "abstract". The `aria-valuenow` attribute is used on all of the range roles subtypes.

```html
<p id="birthyearLabel">What year were you born?</p>
<div
 role="spinbutton"
 tabindex="-1"
 aria-valuenow="1984"
 aria-valuemin="1900"
 aria-valuemax="2021"
 aria-labelledby="birthyearLabel">
  <span class="value"> 1984 </span>
  <span role="button">
    <span aria-hidden="true">+</span>
    Increment year by 1
  </span>
  <span role="button">
    <span aria-hidden="true">-</span>
    Decrement year by 1
  </span>
</div>
```

Use semantic HTML elements when you can:

```html
<label for="birthyear">What year were you born?</label>
<input type="number" id="birthyear" value="1984" min="1900" max="2021" />
```

If there is no known value, like when a progress bar is in an indeterminate state, don't set an `aria-valuenow` attribute.

When there is no `aria-valuenow` set, no information is implied about a current value.

When used with sliders and spinbuttons, assistive technologies announce the actual value to users.

When used with progressbar and scrollbar, assistive technologies announce the value to users as a percent. When `aria-valuemin` and `aria-valuemax` are both defined, the percent value is calculated as a position on the range. Otherwise, the actual value is announced as a percent.

When the value to be announced, either the actual value or the value as a percent, may not be clear to users, the `aria-valuetext` attribute should be used to provide a user-friendly representation of the value. When set, the valuetext string is announced instead of the valuenow numeric value. For example, if a slider represents the days of the week, so the day of the week's `aria-valuenow` is a number, the `aria-valuetext` property should be set to a string that makes the slider value understandable, such as "Monday".

Examples
--------

```html
<p id="temperatureLabel">Oven Temperature</p>
<div
 role="meter"
 id="temperature"
 aria-valuenow="205"
 aria-valuemin="70"
 aria-valuemax="250"
 aria-labelledby="temperatureLabel">
  <div class="meter-color" aria-hidden="true"></div>
</div>
```

The first rule of ARIA use is "if you can use a native feature with the semantics and behavior you require already built in, instead of repurposing an element and **adding** an ARIA role, state or property to make it accessible, then do so."

```html
<label for="temperature">
  Oven Temperature
</p>
<input type="range" id="temperature"
 value="205" min="70" max="250" step="5"/>
</meter>
```

If we employ native HTML semantics with `<input>` we get styles and semantics for free.

Values
------

`<number>`

A decimal number, between the minimum and maximum values.

Associated interfaces
---------------------

`Element.ariaValueNow`

The `ariaValueNow` property, part of the `Element` interface, reflects the value of the `aria-valuenow` attribute.

`ElementInternals.ariaValueNow`

The `ariaValueNow` property, part of the `ElementInternals` interface, reflects the value of the `aria-valuenow` attribute.

Associated roles
----------------

Used in roles:

* `meter`
* `scrollbar`
* `separator`
* `slider`
* `spinbutton`

Inherited into roles:

* `meter`
* `progressbar`
* `scrollbar`
* `slider`
* `spinbutton`
Specifications
--------------

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

See Also
--------

* `range` role
* `<input type="range>` element `value` attribute
* `aria-valuetext`
* `aria-valuemax`
* `aria-valuemin`.


aria-haspopup - Accessibility

aria-haspopup
=============

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

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

In ARIA, interactive menus, listboxes, trees, grids, and dialogs that appear on top of other content when triggered to appear are considered "popups". These popups are triggered by one or more interactive elements on the page. The availability and type of popup the interactive element will trigger should be identified with the `aria-haspopup` state.

The presence of the `aria-haspopup`, with one of six enumerated values - `menu`, `listbox`, `tree`, `grid`, `dialog`, or `true` - indicates the element can trigger a popup and what kind of popup will be displayed. In turn, the element that pops up must be of the role indicated. The value `true` is the same as `menu`. Any other value, including an empty string or other role, is treated as if `false` were set.

A `tooltip` is not considered to be a popup in this context, as it is not interactive.

**Note:** Make sure the role of the element that serves as the container for the popup content is a `menu`, `listbox`, `tree`, `grid` or `dialog` and that the value of `aria-haspopup` matches the role of the popup container.

The `aria-haspopup` state informs assistive technology users that there is a popup and the type of popup it is, but provides no interactivity. For the popup to be keyboard accessible, make sure the element with `aria-haspopup` is focusable and can trigger the popup, that there is a keyboard mechanism for opening the popup, and that the popup element manages focus of all its descendants.

**Note:** ARIA does not enable accessible functionality. ARIA only conveys the intended behavior of your functionality.

When creating a `menubar`, a parent `menuitem` should have `aria-haspopup="menu"` (or `true`) set. Any button that open a menu should have a role of `button` or, preferably, be a `<button>`, and also have `aria-haspopup="menu"` (or `true`) set. `Tab` elements with popup menus should also have `aria-haspopup="menu"` set. Note that `menubar`s should not be used to create website navigation.

**Note:** Elements with role `combobox` have an implicit `aria-haspopup` value of `listbox`.

Values
------

`false` (default)

The element does not have a popup.

`true`

The popup is a menu.

`menu`

The popup is a menu.

`listbox`

The popup is a listbox.

`tree`

The popup is a tree.

`grid`

The popup is a grid.

`dialog`

The popup is a dialog.

Associated interfaces
---------------------

`Element.ariaHasPopup`

The `ariaHasPopup` property, part of the `Element` interface, reflects the value of the `aria-haspopup` attribute, which indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element.

`ElementInternals.ariaHasPopup`

The `ariaHasPopup` property of the `ElementInternals` interface reflects the value of the `aria-haspopup` attribute.

Associated roles
----------------

Used in roles:

* `application`
* `button`
* `combobox`
* `gridcell`
* `link`
* `menuitem`
* `slider`
* `tab`
* `textbox`
* `treeitem`

Inherited into roles:

* `columnheader`
* `menuitemcheckbox`
* `menuitemradio`
* `rowheader`
* `searchbox`
Specifications
--------------

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

See Also
--------

* `aria-controls`
* `menu`
* `listbox`
* `tree`
* `grid`
* `dialog`
* Toolbar example - W3C WAI ARIA practices


aria-invalid - Accessibility

aria-invalid
============

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

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

The `aria-invalid` attribute is used to indicate that the value entered into an input field is not in a format or a value the application will accept. This may include formats such as email addresses or telephone numbers. `aria-invalid` can also be used to indicate that a required field is empty.

The `aria-invalid` attribute can be used with any typical HTML form element, and is not limited to elements that have an ARIA role assigned.

The attribute should be set with JavaScript as a result of a validation process. If a value is determined to be invalid or out-of-range, set `aria-invalid="true"` **and** tell the user there is an error. For better user experience, provide suggestions for how the error can be corrected. Do not set `aria-invalid="true"` on empty required elements until after the user attempts to submit the form. They may still be working on filling it out.

**Note:** When `aria-invalid` is used in conjunction with the `aria-required` attribute, `aria-invalid` should not be set to true before the form is submitted - only in response to validation.

There are currently four values: in addition to `true` and `false` we have `grammar` which can be used when a grammatical error is detected and `spelling` for spelling errors. If the attribute is not present, or its value is false, or its value is an empty string, the default value of false applies. Any other value is treated as if `true` were set.

### Native HTML validation

HTML has native form validation. When a user submits a form with a control containing errors, the first form control with an invalid value displays an error message, natively.

If there is a `required` attribute on a form control that isn't filled out, the form will not submit, and an error message appears reading "Please fill out this field" or something similar. The messaging for native validation varies depending on the browser, and cannot be styled.

```html
<input type="number" step="2" min="0" max="100" required />
```

If the user had entered a value in the preceding input example above the maximum, below the minimum, or that doesn't match the step value, an error message would appear. If the user had entered "3", the native error message would be similar to "Please enter a valid value."

If you are creating your own form validation scripts, make sure to include `aria-invalid` on invalid form controls, along with styling (use the `[aria-invalid="true"]` attribute selector) and messaging (with `aria-errormessage`) to help users understand where the mistake is and how they can fix it.

Values
------

`grammar`

A grammatical error was detected.

`false` (default)

There are no detected errors in the value.

`spelling`

A spelling error was detected.

`true`

The value entered by the user has failed validation.

Any value not in this list will be treated as `true`.

Example
-------

The following snippet shows a simplified version of two form fields with a validation function attached to the blur event. Note that since the default value for `aria-invalid` is `false`, it is not strictly necessary to add the attribute to input.

```html
<ul>
  <li>
    <label for="name">Full Name</label>
    <input
 type="text"
 name="name"
 id="name"
 aria-required="true"
 aria-invalid="false"
 onblur="checkValidity('name', ' ', 'Invalid name entered (requires both first and last name)');" />
  </li>
  <li>
    <label for="email">Email Address</label>
    <input
 type="email"
 name="email"
 id="email"
 aria-required="true"
 aria-invalid="false"
 onblur="checkValidity('email', '@', 'Invalid email address');" />
  </li>
</ul>
```

Note that it is not necessary to validate the fields immediately on blur; the application could wait until the form is submitted (though this is not necessarily recommended).

The snippet below shows a very simple validation function, which only checks for the presence of a particular character (in the real world, validation will likely be more sophisticated):

```js
function checkValidity(id, searchTerm, msg) {
  const elem = document.getElementById(id);
  if (elem.value.includes(searchTerm)) {
    elem.setAttribute("aria-invalid", "false");
    updateAlert();
  } else {
    elem.setAttribute("aria-invalid", "true");
    updateAlert(msg);
  }
}
```

The snippet below shows the alert functions, which add (or remove) the error message:

```js
function updateAlert(msg) {
  const oldAlert = document.getElementById("alert");
  if (oldAlert) {
    oldAlert.remove();
  }

  if (msg) {
    const newAlert = document.createElement("div");
    newAlert.setAttribute("role", "alert");
    newAlert.setAttribute("id", "alert");
    const content = document.createTextNode(msg);
    newAlert.appendChild(content);
    document.body.appendChild(newAlert);
  }
}
```

Note that the alert has the ARIA role attribute set to `alert`.

Associated roles
----------------

Used in roles:

* `application`
* `checkbox`
* `combobox`
* `gridcell`
* `listbox`
* `radiogroup`
* `slider`
* `spinbutton`
* `textbox`
* `tree`

Inherited into role:

* `columnheader`
* `rowheader`
* `searchbox`
* `switch`
* `treegrid`
Specifications
--------------

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

See Also
--------

* `aria-errormessage`
* CSS `:valid` pseudoclass
* CSS `:invalid` pseudoclass
* Form Validation tutorial


aria-rowindex - Accessibility

aria-rowindex
=============

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

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

Some tables have many, many rows. Loading only a subsection of rows may be done as a design requirement, to improve performance, or to improve user experience.

When only a subset of rows are loaded, you do need to let all users know which subsets of rows are being displayed. The `aria-rowindex` attribute is used to define the cell or row's row index or position with respect to the total number of rows within a table, grid, or treegrid.

Included on the `<tr>` element or on an element with a role of `row`, or directly on the `<td>`, `<th>`, or element with role of `cell` or `gridcell`, the value is the row's position with respect to the full table.

The value for `aria-rowindex` is an integer greater than or equal to `1`, greater than the `aria-rowindex` value of any previous rows, and less than or equal to the number of rows in the full table.

If all of the rows are loaded and in the DOM, you don't need to include `aria-rowindex` as browsers automatically calculate the index of each row. However, when only a subset of the rows are present in the DOM, `aria-rowindex` is needed to indicate each row's position with respect to the full table. If only a subset of rows are loaded, you also need to include `aria-rowcount` on the table ancestor, even if you don't know the total rowcount.

If the table with only a subset of rows has a cell that spans more than one row, both the row and cell need to have the `aria-rowspan` set. If a cell spans more than one row－when a cell role includes the `aria-rowspan` attribute or HTML cell has a `rowspan` attribute set to a value greater than 1－include the row's `aria-rowindex` value on the spanning cell in addition to the appropriate row spanning attribute. The value should be the row index of the row where the span starts.

**Note:** The `aria-rowindex` must be added to each row, but is optional on the cells, except for cells that span rows: the `aria-rowindex` attribute is required on all spanning cells.

Examples
--------

The following example shows a grid with 24 rows, of which the first row and rows 7 through 10 are displayed to the user. The last "position" cell spans column 9 and 10.

```html
<div role="grid" aria-rowcount="24">
  <div role="rowgroup">
    <div role="row" aria-rowindex="1">
      <span role="columnheader">First Name</span>
      <span role="columnheader">Last Name</span>
      <span role="columnheader">Position</span>
    </div>
  </div>
  <div role="rowgroup">
    <div role="row" aria-rowindex="7">
      <span role="gridcell">Morgan</span>
      <span role="gridcell">Brian</span>
      <span role="gridcell">Midfielder</span>
    </div>
    <div role="row" aria-rowindex="8">
      <span role="gridcell">Abby</span>
      <span role="gridcell">Dahlkemper</span>
      <span role="gridcell">Defender</span>
    </div>
    <div role="row" aria-rowindex="9">
      <span role="gridcell">Ashlyn</span>
      <span role="gridcell">Harris</span>
      <span role="gridcell" aria-rowspan="2" aria-rowindex="9">Goalkeeper</span>
    </div>
    <div role="row" aria-rowindex="10">
      <span role="gridcell">Alyssa</span>
      <span role="gridcell">Naeher</span>
    </div>
  </div>
</div>
```

Note both `aria-rowspan` and `aria-rowindex` are present on the Goalkeeper cell, which spans two rows.

Values
------

`<integer>`

An integer greater than or equal to 1, greater than the `aria-rowindex` of the previous row, if any, and less than or equal to the value of `aria-rowcount`.

Associated interfaces
---------------------

`Element.ariaRowIndex`

The `ariaRowIndex` property, part of the `Element` interface, reflects the value of the `aria-rowindex` attribute.

`ElementInternals.ariaRowIndex`

The `ariaRowIndex` property, part of the `ElementInternals` interface, reflects the value of the `aria-rowindex` attribute.

Associated roles
----------------

Used in roles:

* `cell`
* `row`

Inherited into roles:

* `columnheader`
* `gridcell`
* `rowheader`
Specifications
--------------

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

See Also
--------

* `aria-rowindextext`
* `aria-rowcount`
* `aria-rowspan`
* `aria-colindex`
* The `rowspan` attribute on `<td>`


aria-valuemin - Accessibility

aria-valuemin
=============

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

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

The `aria-valuemin` attribute defines the minimum value allowed for range widgets. It is similar to the `min` attribute of `<progress>`, `<meter>`, and `<input>` of type `range`, `number` and all the date-time types.

When creating a range type role, including `meter`, `scrollbar`, `slider`, and `spinbutton` on a non-semantic element, the `aria-valuemin` enables defining a minimum that is less than the maximum value and is a required attribute of `slider`, `scrollbar` and `spinbutton`.

Declaring the minimum and maximum values allows assistive technologies to convey the size of the range to users.

The maximum value is defined with `aria-valuemax`.

**Warning:** The `range` role itself should **NOT** be used as it is an "abstract". The `aria-valuemin` attribute is used on all of the range roles subtypes.

Values
------

`<number>`

A decimal number, below the maximum value.

Associated interfaces
---------------------

`Element.ariaValueMin`

The `ariaValueMin` property, part of the `Element` interface, reflects the value of the `aria-valuemin` attribute.

`ElementInternals.ariaValueMin`

The `ariaValueMin` property, part of the `ElementInternals` interface, reflects the value of the `aria-valuemin` attribute.

Associated roles
----------------

Used in roles:

* `meter`
* `scrollbar`
* `separator`
* `slider`
* `spinbutton`

Inherited into roles:

* `meter`
* `progressbar`
* `scrollbar`
* `slider`
* `spinbutton`
Specifications
--------------

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

See Also
--------

* `range` role
* `<input type="range>` element `min` attribute
* `aria-valuemax`
* `aria-aria-valuenow`.


aria-valuemax - Accessibility

aria-valuemax
=============

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

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

The `aria-valuemax` attribute defines the maximum value allowed for range widgets. It is similar to the `max` attribute of `<progress>`, `<meter>`, and `<input>` of type `range`, `number` and all the date-time types.

When creating a range type role, including `meter`, `scrollbar`, `slider`, and `spinbutton` on a non-semantic element, the `aria-valuemax` enables defining a maximum that is more than the minimum value and is a required attribute of `slider`, `scrollbar` and `spinbutton`.

Declaring the minimum and maximum values allows assistive technologies to convey the size of the range to users. The minimum value is defined with `aria-valuemin`.

**Warning:** The `range` role itself should **NOT** be used as it is an "abstract". The `aria-valuemax` attribute is used on all of the range roles subtypes.

Example
-------

The code below shows a simple slider with a maximum value of 9.

```html
<div id="dimesLabel">Dimes</div>
<div
 role="slider"
 aria-valuenow="0"
 aria-valuemin="0"
 aria-valuemax="9"
 aria-labelledby="dimesLabel"
 id="dimes"></div>
```

Values
------

`<number>`

An integer or decimal number that is greater than the minimum value.

Associated interfaces
---------------------

`Element.ariaValueMax`

The `ariaValueMax` property, part of the `Element` interface, reflects the value of the `aria-valuemax` attribute.

`ElementInternals.ariaValueMax`

The `ariaValueMax` property, part of the `ElementInternals` interface, reflects the value of the `aria-valuemax` attribute.

Associated roles
----------------

Used in roles:

* `meter`
* `scrollbar` (required)
* `separator`
* `slider` (required)
* `spinbutton` (required)

Inherited into roles:

* `meter`
* `progressbar`
* `scrollbar`
* `slider`
* `spinbutton`
Specifications
--------------

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

See Also
--------

* `range` role
* `<input type="range>` element `max` attribute
* `aria-valuemin`
* `aria-valuenow`


aria-colindextext - Accessibility

aria-colindextext
=================

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

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

When you have a very large table or when you purposefully want to display just a section of a table, not all columns may be present in the DOM. When this happens, we use the `aria-colcount` with an integer value to define how many columns the table (or grid) would have if all the columns were present and add the `aria-colindex` property on each column to provide information on the column index within that larger table.

In the following HTML snippet, our table has 8 columns, but we are only displaying 4. The "city" column is the fifth column of our larger table, as defined by `aria-colindex="5"`.

```html
<table aria-colcount="8">
  <thead>
    <tr>
      <th aria-colindex="1" scope="col">First name</th>
      <th aria-colindex="2" scope="col">Last name</th>
      <th aria-colindex="5" scope="col">City</th>
      <th aria-colindex="7" scope="col">Zip</th>
    </tr>
  </thead>
  …
</table>
```

This table is not very complex. Had this been a 100+ column spreadsheet or a grid without column headers, such as a chess board, the provided or calculated value of `aria-colindex` might not be meaningful or may not reflect the displayed index. When this is the case, `aria-colindextext` can be included. The value is a string that is a human-readable text alternative to the numeric `aria-colindex`.

```html
<table aria-colcount="128">
  <thead>
    <tr>
      <th aria-colindex="1" aria-colindextext="NYSE stock symbol" scope="col">
        NYSE
      </th>
      <th
 aria-colindex="110"
 aria-colindextext="Value at start of 2021"
 scope="col">
        01/21
      </th>
      <th
 aria-colindex="122"
 aria-colindextext="Value at start of 2022"
 scope="col">
        01/22
      </th>
      <th aria-colindex="124" scope="col">Recommendation</th>
    </tr>
  </thead>
  …
</table>
```

In the above example, the table has 128 columns of which only 4 columns are shown. The `aria-colindextext` is used in three columns to provide human-readable text alternatives. By including `aria-colindextext="Value at start of 2021"`, assistive technologies can announce "Value at start of 2021" instead of "Column 110".

Only use `aria-colindextext` when the provided or calculated value of `aria-colindex` is not meaningful or does not reflect the displayed index. Whenever you include `aria-colindextext`, also keep the `aria-colindex` as some assistive technologies rely on the numeric column index for the purpose of keeping track of the user's position and in providing alternative table navigation.

**Note:** While `aria-colindex` can be added to a row when all the columns present are contiguous as sequential values can be deduced, `aria-colindextext` is NOT a supported property of `row`.

See related `aria-rowindextext`.

Values
------

* `<string>`
    + The human-readable text alternative of the numeric `aria-colindex`
Associated interfaces
---------------------

`Element.ariaColIndexText`

The `ariaColIndexText` property, part of the `Element` interface, reflects the value of the `aria-colindextext` attribute.

`ElementInternals.ariaColIndexText`

The `ariaColIndexText` property, part of the `ElementInternals` interface, reflects the value of the `aria-colindextext` attribute.

Associated roles
----------------

Used in roles:

* `cell`

Inherits into roles:

* `columnheader`
* `rowheader`
Specifications
--------------

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

See Also
--------

* `Element.ariaColIndexText`
* `aria-colindex`
* `aria-rowindextext`
* `aria-colcount`
* `cell` role
* `columnheader` role
* `rowheader` role


aria-posinset - Accessibility

aria-posinset
=============

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

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

Short for "position in set", the `aria-posinset` attribute defines the position of the element within the whole set of listitems or treeitems when only a subset of the items are present in the DOM.

If all the items in a list are present in the DOM, the browser can calculate the total and the position of each, making `aria-posinset` unnecessary. When only a portion of a set is in the DOM, include `aria-posinset` to provide information about the element's position within the set along with `aria-setsize` to inform the user how many items are in the full set.

The following example shows a listbox with four element options out of the 118 in the periodic table of chemical elements.

```html
<h2 id="periodic-table">Periodic table of chemical elements</h2>
<ul role="listbox" aria-labelledby="periodic-table">
  <li role="option" aria-setsize="118" aria-posinset="1">Hydrogen</li>
  <li role="option" aria-setsize="118" aria-posinset="3">Lithium</li>
  <li role="option" aria-setsize="118" aria-posinset="11">Sodium</li>
  <li role="option" aria-setsize="118" aria-posinset="19">Potassium</li>
</ul>
```

The value of each `aria-posinset` is an integer greater than or equal to `1`, and less than or equal to the size of the set when that size is known.

**Note:** When using `aria-posinset` you must also include value for `aria-setsize`, which is the size of the entire set. If the size of the entire set is unknown, set `aria-setsize="-1"`.

For `menuitem`, `menuitemcheckbox`, or `menuitemradio`, set the value of `aria-posinset` with respect to the total number of items in the menu, excluding any separators.

In a `feed`, each `<article>` element has `aria-posinset` set to a value that represents its position in the feed along with the `aria-setsize` set to either the number of articles that have been loaded or the total number in the feed, depending on which value is most helpful to users.

Values
------

`<integer>`

Integer greater than or equal to 1, and less than or equal to the value of `aria-setsize`.

Associated interfaces
---------------------

`Element.ariaPosInSet`

The `ariaPosInSet` property, part of the `Element` interface, reflects the value of the `aria-posinset` attribute.

`ElementInternals.ariaPosInSet`

The `ariaPosInSet` property, part of the `ElementInternals` interface, reflects the value of the `aria-posinset` attribute.

Associated roles
----------------

Used in roles:

* `article`
* `associationlistitemkey`
* `associationlistitemvalue`
* `comment`
* `listitem`
* `menuitem`
* `option`
* `radio`
* `row`
* `tab`

Inherits into roles:

* `comment`
* `menuitemcheckbox`
* `menuitemradio`
* `treeitem`
Specifications
--------------

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

See Also
--------

* `aria-setsize`