ARIA: menubar role - Accessibility

ARIA: menubar role
==================

A `menubar` is a presentation of `menu` that usually remains visible and is usually presented horizontally.

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

A menu is a widget that offers a list of choices to the user, such as a set of actions or functions. The menubar type of menu is usually presented as a persistently visible horizontal bar of commands. Menubars behave like native operating system menubars, such as the menubars containing pull down menus, commonly found at the top of many desktop application windows.

The `menubar` role is used to create a menu bar similar to those found near the top of the window in many desktop applications, visually persistent, typically horizontal, bar of menu items offering the user quick access to a consistent set of commands.

A `menubar` contains three types of menu items, including `menuitem`, `menuitemradio` and `menuitemcheckbox`. These menu items may optionally be nested in one or more `group` containers. Groups or items may optionally by separated with `separator` elements. While every menu item must be able to receive focus, even if disabled, the `group` and `separator` elements are not focusable.

An example of a native menubar is the bar which may be present at the top of the screen if you are reading this in a desktop browser. An example of a web-based menubar is the horizontal menu bar that reads "File Edit View Insert Format", etc., which is usually visible under the document name in a Google doc.

Menubar interactions should be similar to the typical menu bar interaction in a desktop graphical user interface. In Google Docs, each of those menu items is a `menuitem` with a popup submenu, so each has an `aria-haspopup` attribute set to `true`. The `menubar` element does not.

The menubar and all the menu items are focusable and have a tabindex attribute set. When the menubar receives focus through tabbing, keyboard focus is placed on the first menuitem. Each item in the menu has `tabindex` set to `-1`, except the first item has which has its `tabindex` set to `0`.

If a menubar receives focus as a result of a context action, such as a shortcut key, `Escape` or `Enter` may return focus to the invoking context. That said, make sure not to create shortcut keys that interfere with user agent, operating system, or assistive technology shortcuts - any UA, OS, or AT.

Every menu item, no matter how deeply nested, is able to receive focus, even if disabled.

If a `menubar` has a visible label, include `aria-labelledby` set to a value that refers to the labelling element. Otherwise, provide the menubar with an accessible name by including a descriptive `aria-label`.

A `menuitem` element in the `menubar` can contain a child submenu of menu items. Submenus can be nested several deep. Generally, the outer `menubar` is horizontal and all the submenus are vertical. If this is not the case, if your menubar is vertical, include `aria-orientation="vertical"` on the `menubar` element. Otherwise, this attribute is not necessary, as the default value is horizontal.

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

`group` role

Identifies a set of menu items

`menuitem` role

An option in a set of choices contained by a `menubar`. May have a submenu.

`menuitemradio` role

A checkable menu item in a set of elements with the same role, only one of which can be checked at a time.

`menuitemcheckbox` role

a menu item with a checkable state whose possible values are `true`, `false`, or `mixed`.

`aria-orientation`

Include `aria-orientation="vertical"` on `menubar` element if it's the menubar is vertical. The default orientation is `horizontal`.

### Keyboard interactions

When focus is in a `menubar` it is always on a menu item within the menu bar. When focus is on a top level `menuitem` in a menu bar, the following keyboard interactions must be supported:

`Down Arrow`

If the currently focused `menuitem` has a submenu, opens the submenu and places focus on the first item in the submenu.

`Up Arrow`

(Optional) If the currently focused `menuitem` has a submenu, opens the submenu and places focus on the *last* item in the submenu.

`Right Arrow`

Moves focus to the next item, optionally wrapping from the last to the first.

`Left Arrow`

Moves focus to the previous item, optionally wrapping from the first to the last.

`Home`

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

`End`

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

`Tab`

Moves focus to the next element in the tab sequence. If that makes it exit the menubar, all submenus in the menubar get closed.

`shift + Tab`

Moves focus to the previous element in the tab sequence. If that makes it exit the menubar, all submenus in the menubar get closed.

See `menuitem` keyboard interactions, `menuitemradio` keyboard interactions, and `menuitemcheckbox` keyboard interactions for more information on keyboard interactions when focus is on a menuitem in a menubar (which it always is).

Note: The above interactions assumed the `menubar` is horizontal. If the `menubar` is vertical, include `aria-orientation="vertical"` and change the following keyboard keys accordingly:

`Down Arrow`

Performs like the `Right Arrow` as described above.

`Up Arrow`

Performs like the `Left Arrow` as described above

`Right Arrow`

Performs like the `Down Arrow` as described above.

`Left Arrow`

Performs as the `Up Arrow` as described above

Examples
--------

* W3C WAI-ARIA practices: navigation `menubar` example
* W3C WAI-ARIA practices: editor `menubar` example
Specifications
--------------

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

See Also
--------

* `toolbar` role


ARIA: document role - Accessibility

ARIA: document role
===================

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

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

The `document` role is for the top container containing content that assistive technology users may want to browse in a reading mode. Only useful on focusable sections within complex composite widgets or applications, the `document` role informs assistive technologies to the reading context back to a reading mode: The `document` role tells assistive technologies with reading or browse modes to use the document mode to read the content contained within this element.

```html
<div role="dialog">
  …
  <div id="InfoText" role="document" tabindex="0">
    <p>Some informational text goes here.</p>
  </div>
  …
  <button>Close</button>
</div>
```

This example shows a dialog, a complex composite widget role, with some controls and a section with some informational text that the assistive technology user can go into reading mode when tabbed to.

By default, web pages are treated as documents; assistive technologies (AT) enter browse or read mode when entering a new web page. This mode can be altered through various roles, including the widget and application roles. The `document` role brings the AT back into browse or read mode.

Generally placed within an application role or other interactive widget role, the `document` role is used to indicate a section of a complex composite widget that an assistive technology user should read using its browse or virtual reading mode, if available.

Because ATs with reading mode default to that mode for all elements except for those with a widget or application role set, document role is only useful for focusable elements within a widget or application that should be read as static rich text. Adding `role="document"` and `tabindex="0"` to the element containing the text within a widget enables the screen reader user to press the Tab key to place focus on the document element and read the text with the screen reader's reading cursor.

Assistive technologies should switch context back to document mode, possibly intercepting from controls rewired for the parent's dynamic context, re-enabling the standard input events, such as Up or Down arrow keyboard events, to control the reading cursor.

In contrast to the `article` role, the `document` role does not have any relation to other elements with a document role, it merely has a relationship to the containing composite widget. An article can have associated articles.

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

`aria-expanded`

Include with a value of `true` or `false` if the document element is collapsible, to indicate if the document is currently expanded or collapsed. Other values include the default `undefined` which means the document is not collapsible.

tabindex="0"

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

### Keyboard interactions

The element should be made focusable by setting the `tabindex="0"` attribute / value pair on it. This way, the user can tab to it, reading mode is invoked automatically, and the content can be read right away.

### Required JavaScript features

None, except as required by any attributes. For example, if the `document` is collapsible, then the state and the value of `aria-expanded` must be maintained.

Examples
--------

An example is Gmail and the single conversation view. GMail is a web application. When in GMail, most user agent interactions are usurped by the application. However, when the Keyboard focus is set on the starting heading on a single conversation that contains the subject of the conversation, the screen reader user can use the reading mode commands to read through the messages, expand or collapse them, and manipulate them. Once focus returns to the message list either by activating the Back button or pressing an associated keystroke, direct application interaction mode is invoked again, and the user can move to a different conversation in the list with the `arrow` keys.

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

Always make sure an item with the document role is focusable, by setting the `tabindex` attribute with a value of 0. That will also include it in the tab order.

### Added benefits

The document role is an easy way to indirectly control assistive technology behavior by unambiguously stating that this is content the user should read with standard screen reader commands.

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

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

See also
--------

* ARIA: `widget` role
* ARIA: `application` role


ARIA: cell role - Accessibility

ARIA: cell role
===============

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

```html
<div role="row">
  <span role="cell">France</span>
  <span role="cell">67 million</span>
</div>
```

A better, more semantic way of writing the cells above would be to use the semantic `<td>` element.

```html
<tr role="row">
  <td role="cell">France</td>
  <td role="cell">67 million</td>
</tr>
```

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

The element with `role="cell"` is a cell within a row, optionally within a `rowgroup`, within a `table`. If the cell is in a `grid` or `treegrid`, opt for `gridcell`. Using native HTML `<td>` elements, whenever possible, is strongly encouraged.

Each element with `role="cell"` MUST be nested in a container element with `role="row"`. That row, in turn, can be nested within an element with `role="rowgroup"`, and should be nested within a `grid`, `table` or `treegrid`. If a cell contains column or row header information, use the `columnheader` or `rowheader` roles, respectively. If the cell does not contain header information and is nested in a `grid` or `treegrid`, the role of `gridcell` may be more appropriate.

A cell can contain a number of property attributes clarifying the cell's position within the tabular data structure, including `aria-colindex`, `aria-colspan`, `aria-rowindex`, and `aria-rowspan`.

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

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

#### Context roles

role="row"

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

role="rowgroup"

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

role="table"

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

role="grid"

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

role="treegrid"

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

#### Subclass roles

role="gridcell"

A cell in a row within a `grid` or `treegrid`.

role="columnheader"

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

role="rowheader"

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

#### States and properties

`aria-colspan`

Similar to the HTML `<th>` and `<td>` colspan attribute, it defines the number of columns spanned by the cell.

`aria-rowspan`

Similar to the HTML `<th>` and `<td>` rowspan attribute, it defines the number of rows spanned by the cell.

`aria-colindex` attribute

The `aria-colindex` attribute is only needed if columns are hidden from the DOM. The attribute takes as its value an integer between 1 and the total number of columns within the `table`, `grid` or `treegrid`. The `aria-colindex` defines an element's column index or position with respect to the total number of columns within a row. If all the columns are in the DOM, this attribute is not necessary.

`aria-rowindex` attribute

The `aria-rowindex` attribute is only needed if rows are hidden from the DOM, to indicate which row, in the list of total rows, the current cell is in. The attribute, takes as its value an integer between 1 and the total number of rows within the table, grid, or treegrid, indicating the position, or index, of the cell. For example, a cell in the first row of the first header would likely have `aria-rowindex="1"` set, and cells in row 47 would have `aria-rowindex="47"`, if `aria-rowindex` were needed due to not all rows being in the DOM. If the rows that are visible are contiguous, and there are no cells with a `colspan` or `rowspan` greater than one, this property can be added to the parent rows instead of all the rows' cells.

### Keyboard interactions

None

### Required JavaScript features

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. Employ the HTML `<td>` element instead of the ARIA role of `cell` 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-rowindex="1"
 >ARIA Role</span
 >
      <span role="columnheader" aria-sort="none" aria-rowindex="1"
 >Semantic Element</span
 >
    </div>
  </div>
  <div role="rowgroup">
    <div role="row">
      <span role="cell" aria-rowindex="11">header</span>
      <span role="cell" aria-rowindex="11">h1</span>
    </div>
    <div role="row">
      <span role="cell" aria-rowindex="16">header</span>
      <span role="cell" aria-rowindex="16">h6</span>
    </div>
    <div role="row">
      <span role="cell" aria-rowindex="18">rowgroup</span>
      <span role="cell" aria-rowindex="18">thead</span>
    </div>
    <div role="row">
      <span role="cell" aria-rowindex="24">term</span>
      <span role="cell" aria-rowindex="24">dt</span>
    </div>
  </div>
</div>
```

The above is a non-semantic ARIA table with five of 81 rows present in the DOM: one within a table header and four rows within the table body. Because not all the rows are in the DOM, we've included the `aria-rowindex` property on every cell. If no cells spanned more than one row or column, the `aria-rowindex` could have been placed on the row rather than the row's individual cells.

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

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

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

Above is the semantic way of writing a table. The ARIA roles are not necessary if the native semantics of the table, and therefore the table rows, have not been altered, such as through the display property.

### Added benefits

When applied to a `<td>`, it returns cell semantics to the element in case the semantics were removed, such as with `display: grid;`.

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

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

See also
--------

* `role="row"`
* `role="gridcell"`
* HTML `<td>` element
* HTML `<th>` element
* HTML table advanced features and accessibility
* HTML table basics


ARIA: widget role - Accessibility

ARIA: widget role
=================

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

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

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

The abstract `widget` role is a superclass role for some interactive GUI elements and grouping roles. `role="widget"` should not be confused with widgets roles, such as `option`, `menuitem`, and `searchbox`.

The `widget` role is a superclass role several abstract interactive GUI roles, including `command`, `composite`, `input`, `range`, and `separator` (if focusable), which should not be used by web authors.

The abstract `widget` role is also a superclass role for some grouping roles which can be used by web authors, including `gridcell`, `row`, `separator` (when not focusable), and `tab`, which can and should be used when appropriate. When the user navigates to one of these non-abstract roles of widget, keyboard events can switch to an application browsing mode, and pass keyboard events through to the browser.

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

Do not use.

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

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

See Also
--------

* ARIA: `roletype` role
* ARIA: `command` role
* ARIA: `composite` role
* ARIA: `gridcell` role
* ARIA: `input` role
* ARIA: `range` role
* ARIA: `row` role
* ARIA: `separator` role
* ARIA: `tab` role


ARIA: banner role - Accessibility

ARIA: banner role
=================

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

By default, the HTML's `<header>` element has an identical meaning to the `banner` landmark, unless it is a descendant of `<aside>`, `<article>`, `<main>`, `<nav>`, or `<section>`, at which point `<header>` exposes a `generic` role, and not the equivalent of the site-wide banner.

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

A `banner` landmark role overwrites the implicit ARIA role of the container element upon which it is applied. It should be reserved for globally repeating site-wide content that is generally located at the top of every page.

The banner typically includes things such as a logo or corporate identity, or possibly a site-specific search tool, and is generally what your marketing team would call the "header" or "top banner" of the site. If the `header` element technique is not being used for that banner, a declaration of `role="banner"` should be used to define a banner landmark to assistive technologies.

Assistive technologies can identify the `header` element of a page as the `banner` if it is a descendant of the `body` element, and not nested within an `article`, `aside`, `main`, `nav` or `section` subsection.

Each page may have a `banner` landmark, but each page should generally be limited to a single element with the role of banner. In the case of a page containing nested `document` and/or `application` roles, each nested `document` or `application` role may also have one `banner` landmark. If a page includes more than one `banner` landmark, each should have a unique accessible name.

### Associated ARIA roles, states, and properties

None

### Keyboard interactions

None

### Required JavaScript features

None

Examples
--------

Here's a fake simple banner with a skip to navigation link, a logo, a title and a subtitle. As this is the main header for the site, we've added the `banner` landmark role to the container element.

```html
<div role="banner">
  <a href="#main" id="skipToMain" class="skiptocontent">Skip To main content</a>
  <img src="images/w3c.png" alt="W3C Logo" />
  <h1>ARIA Landmarks</h1>
  <p>Identifying page subsections for easy navigation</p>
  <nav>…</nav>
</div>
```

We could also have written the above with the HTML `header` element:

```html
<header>
  <a href="#main" id="skipToMain" class="skiptocontent">Skip To main content</a>
  <img src="images/w3c.png" alt="W3C Logo" />
  <h1>ARIA Landmarks</h1>
  <p>Identifying page subsections for easy navigation</p>
  <nav>…</nav>
</header>
```

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

While it is best to use the `header` element and ensure it is not a descendant of any subsection of the page, sometimes you don't have access to the underlying HTML. If this is the case, you can add the role of `banner` to the element of the page which should be exposed as a `banner` with JavaScript. Identifying the page's banner in this way will help improve the site's accessibility.

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

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

See also
--------

* HTML `header` element
* WC3 Landmarks Example


ARIA: landmark role - Accessibility

ARIA: landmark role
===================

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

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

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

A `landmark` is an abstract role for a section of content that is important enough that users will likely want to be able to navigate to the section easily and have it included in a dynamically generated summary of the page. Landmarks allow assistive technologies to navigate and to find content quickly.

To create a landmark role, define the purpose of the content by using a semantic element such as `<section>`, `<nav>`, or `<main>`, or adding an ARIA role that is a subclass of the `landmark` role such as `role="banner"`, `role="complementary"`, or `role="region"`. Do not use `role="landmark"`.

A visible label should be provided, referenced with `aria-labelledby`. If necessary, brief, descriptive, label can be provided with `aria-label`.

For screen reader users, adding landmark roles effectively creates 'skip links' for screen reader users, but don't replace in page navigation as the landmark roles are not otherwise surfaced.

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

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

Landmarks ensure content is in navigable regions. Use `<main>` for `role="main"`, `<header>` for `role="banner"`, `<nav>` for `role="navigation"`, and `<footer>` for `role="contentinfo"`. It is also good practice to include the role redundantly with the associated semantic element. It is not as good practice to use non-semantic elements, such as `<div>`, adding semantics with landmark roles. But do include one or the other or both. Otherwise, your content is no longer as navigable for screen reader users.

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

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

See Also
--------

* ARIA: `section` role
* ARIA: `banner` role
* ARIA: `complementary` role
* ARIA: `contentinfo` role
* ARIA: `form` role
* ARIA: `main` role
* ARIA: `navigation` role
* ARIA: `region` role
* ARIA: `search` role
* Using HTML landmark roles to improve accessibility on MDN blog (2023)


ARIA: heading role - Accessibility

ARIA: heading role
==================

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

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

The heading role indicates to assistive technologies that this element should be treated like a heading. Screen readers would read the text and indicate that it is formatted like a heading. In addition, the level tells assistive technologies which part of the page structure this heading represents. A level 1 heading, indicated with `aria-level="1"`, usually indicates the main heading of a page, a level 2 heading, defined with `aria-level="2"` the first subsection, a level 3 is a subsection of that, and so on.

```html
<div role="heading" aria-level="1">This is a main page heading</div>
```

This defines the text in the `<div>` to be the main heading of the page, indicated by being level 1 via the `aria-level` attribute. Opt for using the h1 (through h6) element instead.

```html
<h1>This is a main page heading</h1>
```

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

`aria-level`

The `aria-level` attribute specifies the heading level in the document structure. If no level is present, a value of 2 is the default.

### Keyboard interactions

This role does not require any special keyboard navigation. As with any heading, giving it an ID ensures it can be referenced from anchor links, making it accessible via the keyboard.

### Required JavaScript features

Required event handlers

None.

Changing attribute values

Usually not required, unless dynamically inserting content. In that case, the newly-added headings need `aria-level` attributes whose values are consistent with the rest of the document structure.

**Note:** Instead of using a `<div>` or `<span>` with a `heading` role and `aria-level`, consider using a native h1 through h6 elements instead to indicate that this text is a heading, and what part of the structure it represents.

Examples
--------

The following shows a typical page structure.

```html
<div id="container">
  <div role="heading" aria-level="1">The main page heading</div>
  <p>This article is about showing a page structure.</p>
  <div role="heading" aria-level="2">Introduction</div>
  <p>An introductory text.</p>
  <div role="heading" aria-level="2">Chapter 1</div>
  <p>Text</p>
  <div role="heading" aria-level="3">Chapter 1.1</div>
  <p>More text in a sub section.</p>
</div>
```

However, instead, you should do:

```html
<div id="container">
  <h1>The main page heading</h1>
  <p>This article is about showing a page structure.</p>
  <h2>Introduction</h2>
  <p>An introductory text.</p>
  <h2>Chapter 1</h2>
  <p>Text</p>
  <h3>Chapter 1.1</h3>
  <p>More text in a sub section.</p>
</div>
```

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

**Warning:** Using `aria-label` or `aria-labelledby` will hide the content of your heading from assistive technologies, reading the label instead of the heading.

If you must use the `heading` role and `aria-level` attribute, do not go over level 6 so that you are consistent with HTML. Although theoretically you can go higher, and some screen readers may support it, the results can be unpredictable with other browser and screen reader combinations.

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

The best way to use this role is to **not use it at all**, and instead use the native heading tags h1 through h6 as shown in the example above. The `heading` role and `aria-level` attribute should only be used to retrofit accessibility on legacy code that you cannot make major changes to.

Instead of using the ARIA `heading` role, use the semantic HTML element:

| HTML Element | `heading` role |
| --- | --- |
| h1 | `<div role="heading" aria-level="1">` |
| h2 | `<div role="heading" aria-level="2">` |
| h3 | `<div role="heading" aria-level="3">` |
| h4 | `<div role="heading" aria-level="4">` |
| h5 | `<div role="heading" aria-level="5">` |
| h6 | `<div role="heading" aria-level="6">` |

### Added benefits

None.

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

| Specification |
| --- |
| Accessible Rich Internet Applications (WAI-ARIA) # heading |
| Unknown specification # when\_to\_use\_structural\_roles |

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

The heading role overrides the native semantic meaning of the element it is being used for. The `aria-level` attribute, in addition, determines what level of heading is being exposed.

See also
--------

* `<h1>` through `<h6>`: The HTML Section Heading elements


ARIA: slider role - Accessibility

ARIA: slider role
=================

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

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

The `slider` role is for range input widgets where the user selects a value from within given minimum and maximum values.

### The `slider` role compared other range options

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

The `progressbar` role, similar to HTML's `<progress>` element, is a read-only range indicating 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 indicating 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 set 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 `slider` 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 slider value, touch-based assistive technologies need to respond to user gestures for increasing and decreasing the value by synthesizing key events.
 Fully test slider widgets using assistive technologies on devices where touch is a primary input mechanism before using the `slider` 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, inclusive. This attribute is required for `slider` and `meter`, and optional for `progressbar`.

For `slider`, unless using the `<input type="range">` element, the `aria-valuenow` value must be updated programmatically when the user updates the value.

The optional `aria-valuetext` attribute is included when the `aria-valuenow` numeric value doesn't reflect the intended value of the slider. As the minimum, maximum, and current values are all numeric, when the values those 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 slider for t-shirt sizes, the `aria-valuetext` attribute should shift from xx-small through to XX-large as the `aria-valuenow` increases.

The `aria-valuetext` value must be updated as the `value` or `aria-valuenow` is updated. While there is no equivalent HTML attribute for `<input type="range">`, you can include `aria-valuetext` on any `<input>` type. ARIA attributes are supported on semantic HTML elements.

When `aria-valuetext` is an important feature for a slider, consider using `<select>` with `<option>` elements instead. While not visually a range, every option's value is more accessible to all users, not just users of assistive technology.

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

When not using the HTML `<input>` element to create your slider, include the `tabindex` attribute to make the slider focusable. Of the three range types, only `slider` is user-interactive, and so is the only one that requires being able to receive focus. Focus should be placed on the slider thumb.

Sliders have an implicit `aria-orientation` value of `horizontal`. This attribute is not supported with `meter` or `progressbar`.

### User interactions

Unlike the read-only `meter` and `progressbar` roles, a `slider` is an input, accepting user interaction. In addition to including the `tabindex` attribute to enable slider focus, keyboard and pointer device support must be implemented.

The slider represents the range of possible values. The position of the slider thumb along the slider represents the current value. User actions that must be supported include changing the value by dragging the thumb or clicking the slider for pointing devices and using directional keys such as arrow keys for the keyboard users. See keyboard interactions below.

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

### Range with multiple thumbs

A multi-thumb slider is a slider with two or more thumbs that each set a value in a group of related values. For example, in a product search, a two-thumb slider could be used to enable users to set the minimum and maximum price limits for the search.

In many two-thumb sliders, the thumbs are not allowed to pass one another, such as when the slider sets the minimum and maximum values for a range. For example, in a price-range selector, the maximum value of the thumb that sets the lower end of the range is limited by the current value of the thumb that sets the upper end of the range. The minimum value of the upper-end thumb is also limited by the current value of the lower-end thumb.

It is not a requirement that the thumbs in multi-thumb sliders be dependent on the other thumb values, but intuitive user experience is a requirement, so it is recommended to avoid this anti-pattern.

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

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

```html
<div role="slider"><h3>Temperature in Celsius</h3></div>
```

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

```html
<div role="slider"><h3 role="presentation">Temperature in Celsius</h3></div>
```

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

```html
<div role="slider">Temperature in Celsius</div>
```

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

`aria-valuetext`

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

`aria-valuemin`

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

`aria-valuemax`

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

`aria-label` or `aria-labelledby`

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

`aria-orientation`

Indicates whether the element's orientation is horizontal, vertical, or unknown/ambiguous. With a slider, the implicit value is `horizontal` but can be set to `vertical`. As it has an implicit value, the slider orientation is never ambiguous.

Examples
--------

In the example below, we create a vertical thermometer with which the user can set the room temperature:

```html
<div>
  <div id="temperatureLabel">Temperature</div>
  <div id="temperatureValue">20°C</div>
  <div id="temperatureSlider">
    <div
 id="temperatureSliderThumb"
 role="slider"
 aria-labelledby="temperatureLabel"
 aria-orientation="vertical"
 tabindex="0"
 aria-valuemin="15.0"
 aria-valuemax="25.0"
 aria-valuenow="20.0"
 aria-valuetext="20 degrees Celsius"
 style="top: calc((25 - 20)\*2rem - 0.5rem)"></div>
  </div>
</div>
```

The position of the thumb is the maximum value minus the current value times the height of one degree, minus half the height of the thumb to center it. The rest of the styles are static.

```css
[id="temperatureSlider"] {
  position: relative;
  height: 20rem;
  width: 1rem;
  outline: 1px solid;
  margin: 3rem;
}

[id="temperatureSliderThumb"] {
  position: absolute;
  height: 1rem;
  width: 2rem;
  background-color: currentcolor;
  left: -0.5rem;
}
```

For this example to work, we have to write a script to handle all keyboard and pointer events, including event listeners for `pointermove`, `pointerup`, `focus`, `blur`, and `keydown`, and provide styles for the default state and when the thumb and slider receive focus. The position of the thumb, the `aria-valuenow` and `aria-valuetext` values, and the inner text of the element with the `id` "temperatureValue" need to be updated every time `ArrowLeft`, `ArrowDown`, `ArrowRight`, `ArrowUp`, `Home`, `End`, and, optionally, `PageDown` and `PageUp` keys are released and when the user drags the thumb or otherwise clicks on the temperature slider.

Using semantic HTML, this could have been written as:

```html
<label for="temperature"> Temperature </label>
<output id="temperatureValue">20°C</output>
<input
 type="range"
 id="temperatureSlider"
 min="15"
 max="25"
 step="0.1"
 value="20"
 aria-valuetext="20 degrees celsius"
 style="transform: rotate(-90deg);" />
```

By using `<input>`, we get an already-styled range-input widget with keyboard focus, focus styling, keyboard interactions, and `value` updated on user interaction for free. We still need to use JavaScript to change the `aria-valuetext` and the value of the `<output>` element.

There are a few ways to make a range input vertical. In this example, we used CSS transforms.

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 one step |
| Page Down | (Optional) decrease the value by a set amount greater than one step |
| Home | Set the slider to the minimum value. |
| End | Set the slider to the maximum value. |

For the optional `Page Up` and `Page Down` keys, the change in slider value should be by an amount larger than the step changes made by up and down arrows.

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

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

HTML's `<input type="range">` implicitly has the `role` of `slider`. Do not use `aria-valuemax` or `aria-valuemin` attributes on `<input type="range">` elements; use `min` and `max` instead. Otherwise, any global `aria-*` attributes and any other `aria-*` attributes applicable to the slider role.

### Prefer HTML

It is recommended to use a native `<input>` of type `range`, `<input type="range">`, rather than the `slider` role.

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

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

See also
--------

* `<input type="range">`,
* HTML `<progress>` element
* HTML `<meter>` element
* Other range widgets include:
    + `meter`
    + `scrollbar`
    + `separator` (if focusable)
    + `progressbar`
    + `spinbutton`
* Working examples:
    + Horizontal Multi-Thumb Slider
    + Horizontal Slider
    + Slider with `aria-orientation` and `aria-valuetext`


ARIA: treegrid role - Accessibility

ARIA: treegrid role
===================

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

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

 A `treegrid` is a hierarchical data grid, or table, consisting of tabular information that is editable or interactive. A `treegrid` is a combination of the `tree` and `grid` roles. Like a `grid`, the `treegrid` is made up of rows, columns, and gridcells. Like a `tree`, parent nodes in a `treegrid` are expandable and collapsible.
 The `treegrid` widget contains one or more `row` elements, optionally with `rowgroup` elements grouping the rows. Each row, in turn, contains one or more cells. Each cell is either a DOM descendant of or owned by a row element and is either a `columnheader`, `rowheader`, or `gridcell` element, with the `gridcell` role being used for all cells that do not contain column or row header information.

A `row` that can be expanded or collapsed to show or hide a set of child rows is a **parent row**. Each parent row has the `aria-expanded` state set on either the row element or on a cell contained in the row.

The `aria-expanded` state is set to `true` when the child rows are displayed and set to `false` when the child rows are hidden. Elements that do not control display of child rows should not have the `aria-expanded` attribute because the presence of the attribute indicates to assistive technologies that the element with the attribute is a parent.

When your grid UI calls for rows supporting `aria-expanded` or if your grid requires supporting `aria-posinset`, `aria-setsize`, or `aria-level`, use `treegrid` and not `grid`.

Each `row` or `gridcell` in a row should be keyboard focusable, and keyboard focus for all these tree grid descendants must be managed. The exception to this rule is column header cells which aren't required to be focusable if they do not provide functionality such as sort or filter. Every row and cell should either contain a focusable element or be focusable itself, regardless of whether individual cell content is editable or interactive.

### Single and multi-select treegrids

If the `treegrid` allows the user to choose just one item for an action, then it is known as a **single-select** treegrid. In single-select treegrids, the item with focus also has a selected state set with `aria-selected`.

If the treegrid supports selection of more than one row or cell, it is a **multi-select** treegrid. In the multi-select treegrid, the selected state is independent of the focus. The visual design and assistive technologies must distinguish between items that are selected and the item that has focus.

For multi-select treegrids, include `aria-multiselectable="true"` on the element with the `treegrid` role. All selected rows or cells have `aria-selected` set to true. All rows and cells that are selectable but not currently selected have `aria-selected` set to `false`. Don't include the `aria-selected` attribute on rows and cells that are not individually selectable as the presence of the attribute indicates to assistive technologies that the row or cell is selectable.

### Orphan rows

In cases where a child `row` or `rowgroup` is not nested within the `treegrid` in the DOM, the `aria-owns` attribute, referencing all of the IDs of the non-descendant children must be set on the `treegrid` element. If rows or cells are included in a treegrid via `aria-owns`, they will be presented to assistive technologies after the DOM descendants of the `treegrid` element unless the grid's actual DOM descendants are also included in the `aria-owns` attribute.

### Treegrids with dynamically loaded content

If some rows or columns are not in the DOM and are dynamically loaded when scrolling, `aria-colcount`, `aria-rowcount`, `aria-colindex` and `aria-rowindex` come into play. The `aria-colcount` and `aria-rowcount` properties get set on the `treegrid`. The values being the total number of columns and rows of the fully loaded grid, respectively. The indexes for each row and column get set on individual cells, not on the `treegrid` element.

### A treegrid's accessible name, description, and focus

The element with the role of `treegrid` must have an accessible name. If an appropriate label is visible in the content, provide the name via `aria-labelledby`. In other words, if there is an element in the user interface that serves as a label for the treegrid, include `aria-labelledby` as an attribute on the element with the role of `treegrid`, and set the value of the attribute to the `id` of the labelling element or elements. If no visible label is present, use `aria-label` instead. Not both.

If the content includes a caption or description for the `treegrid`, include `aria-describedby` on the `treegrid` element with the attribute value being the `id` of the element containing the description.

If the `treegrid` container itself receives focus, the value of its `aria-activedescendant` property should reference the `id` of the selected `row`, `columnheader`, `rowheader` or `gridcell`, unless roving tabindex is used to manage focus between those roles, in which case `aria-activedescendant` should not be used.

If the `treegrid` is disabled, make that disabled state visually apparent, programmatically enforced, and include the `aria-disabled` attribute on the `treegrid` itself to inform assistive technologies of its disabled state.

### Treegrid sorting

If the treegrid provides sort functions, the `aria-sort` attribute is included on relevant header cell elements, not on the grid itself.

### Treegrid menus

If the `treegrid` has an attached `menu` that opens when right clicked, include `aria-haspopup="true"` on the `treegrid` element. This informs assistive technologies that the `treegrid` has an associated popup. The ability for both keyboard and pointer device users to open and set focus in the menu must be added with JavaScript.

### Read-only treegrids

By default, treegrids are assumed to be editable. If a tree grid is not editable, use the `aria-readonly` attribute to inform assistive technologies the `treegrid` is readonly. The attribute value, when set on the element with the `treegrid` role, propagates down to all `columnheader`, `rowheader`, and `gridcell` elements. That global value can be overridden for individual `gridcell` elements by including `aria-readonly` on individual tree grid element descendants.

Like all ARIA attributes, adding `aria-readonly` only informs assistive technologies that the content is or is not editable, but it does nothing to enable or disable interactivity. That must be done with HTML's global `contenteditable` attribute or with JavaScript.

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

`row` role

A row of cells within a tabular structure, optionally within a `rowgroup`. Contains one or more rows of grid cells, column headers, or row headers.

`rowgroup` role

A group of rows within a tabular structure.

`gridcell` role

Intended to mimic the functionality of the HTML `<td>` element, is found in `grid` and `treegrid` roles and must be the direct child of a `row`.

columnheader role

A cell in a row containing header information for a column, similar to the native `<th>` element with column scope

rowheader role

A cell containing header information for a `row` within a tabular structure.

`aria-expanded`

For expandable items, the value is `true` or `false`. Also indicates that the item is expandable, so should not be present if the item cannot be expanded.

`aria-owns`

Identifies a contextual relationship between a parent and its child elements when the DOM hierarchy cannot be used to represent the relationship

`aria-labelledby`

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

`aria-label`

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

### Keyboard interactions

Being able to move focus among rows and cells of the grid with a keyboard must be implemented in order to create an accessible treegrid. Moving focus into the grid may result in the first cell or the first row being focused. Whether focus goes to the next adjacent cell or the row depends on its content requirements, with some treegrids not providing focus to rows.

The following keyboard interactions need to be supported when an element in the grid has received focus, e.g., after a user has moved focus to the grid with Tab.

`Enter`

If cell-only focus is enabled and focus is on the first cell with the `aria-expanded` property, opens or closes the child rows. Otherwise, performs the default action for the cell.

`Tab`

If the row containing focus contains focusable elements such as an `<input>`, `<button>` or `<a>`, moves the focus to the next input in the row. If focus is on the last focusable element in the row, moves focus out of the treegrid widget to the next focusable element.

`Right Arrow`

If focus is on a collapsed row, expand the row. If focus is on an expanded row or is on a row that does not have child rows, moves focus to the first cell in the row. If focus is on the right-most cell in a row, focus does not move. If focus is on any other cell, moves focus one cell to the right.

`Left Arrow`

If focus is on an expanded row, collapses the row. If focus is on a collapsed row or on a row that does not have child rows, focus does not move. If focus is on the first cell in a row and row focus is supported, moves focus to the row. If focus is on the first cell in a row and row focus is not supported, focus does not move. If focus is on any other cell, moves focus one cell to the left.

`Down Arrow`

If focus is on a row, moves focus one row down. If focus is on the last row, focus does not move. If focus is on a cell, moves focus one cell down. If focus is on the bottom cell in the column, focus does not move.

`Up Arrow`

If focus is on a row, moves focus one row up. If focus is on the first row, focus does not move. If focus is on a cell, moves focus one cell up. If focus is on the top cell in the column, focus does not move.

`Page Down`

If focus is on a row or cell, moves focus down a predetermined number of rows or cells. Usually, it moves down the equivalent of the height of the treegrid, scrolling so the bottom row in the currently visible set of rows becomes one of the first visible rows. If focus is in the last row, focus does not move.

`Page Up`

If focus is on a row or cell, moves focus up an predetermined number of rows. Usually, it moves up the equivalent of the height of the treegrid, scrolling so the top row in the currently visible set of rows becomes one of the last visible rows. If focus is in the first row, focus does not move.

`Home` `Control + Home`

If focus is on a row, moves focus to the first row. If focus is in the first row, focus does not move. If focus is on a cell, moves focus to the first cell in the row. If focus is in the first cell of the row, focus does not move.

`End` `Control + End`

If focus is on a row, moves focus to the last row. If focus is in the last row, focus does not move. If focus is on a cell, moves focus to the last cell in the row. If focus is in the last cell of the row, focus does not move. If not all rows are present in the DOM, this can be used to focus on the last row present in the DOM, or on the last row available if the entire database were present in the DOM.

If a treegrid supports selection of cells, rows, or columns, the following keys are commonly used for these functions.

`Control + Space`

If focus is on a row, selects all cells. If focus is on a cell, selects the column that contains the focus.

`Shift + Space`

If focus is on a row, select the row. If focus is on a cell, select the row that contains the focus. If the treegrid includes a column with checkboxes for selecting rows, this key can also be used as a shortcut for checking the box when focus is not on the checkbox.

`Control + A`

Selects all cells.

`Shift + Right Arrow`

if focus is on a cell, extends selection one cell to the right.

`Shift + Left Arrow`

if focus is on a cell, extends selection one cell to the left.

`Shift + Down Arrow`

If focus is on a row, extends selection to all the cells in the next row. If focus is on a cell, extends selection one cell down.

`Shift + Up Arrow`

If focus is on a row, extends selection to all the cells in the previous row. If focus is on a cell, extends selection one cell up.

If navigation functions can dynamically add more rows or columns to the DOM, key events that move focus to the beginning or end of the grid, such as `control + End`, may move focus to the last row in the DOM rather than the last available row in the back-end data.

While navigation keys, such as arrow keys, are moving focus from cell to cell, they are not available to do something like operate a combobox or move an editing caret inside of a cell. If this functionality is needed, see Editing and Navigating Inside a Cell.

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

It is important for all cells to be able to receive or contain keyboard focus because screen readers are generally in application reading mode, rather than their document reading mode, when users are interacting with the grid. While in application mode, a screen reader user hears only focusable elements and content that labels focusable elements. If content can't receive focus, screen reader users may unknowingly overlook elements contained in the treegrid.

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

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

See Also
--------


ARIA: gridcell role - Accessibility

ARIA: gridcell role
===================

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

```html
<div role="gridcell">Potato</div>
<div role="gridcell">Cabbage</div>
<div role="gridcell">Onion</div>
```

Elements that have `role="gridcell"` applied to them must be the child of an element with a role of `row`.

```html
<div role="row">
  <div role="gridcell">Jane</div>
  <div role="gridcell">Smith</div>
  <div role="gridcell">496-619-5098</div>
  …
</div>
```

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 HTML `<td>` element:

```html
<td>Potato</td>
<td>Cabbage</td>
<td>Onion</td>
```

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

### gridcells with dynamically added, hidden, or removed rows and columns

Any element with a `role="gridcell"` applied to it should use ARIA to describe its order in the table-style grouping, provided the table, grid, or treegrid has the ability to have rows and/or columns dynamically added, hidden, or removed.

Use `aria-colindex` to describe a `gridcell`'s order in the list of columns, and `aria-rowindex` to describe a gridcell's order in the list of rows. Use `aria-colcount` and `aria-rowcount` on the parent element with `role="grid"` applied to it to set the total number of columns or rows.

This sample code demonstrates a table-style grouping of information where the third and fourth columns have been removed. `aria-colindex` is being used to describe the rows' position and allows a person using assistive technology to infer that certain rows have been removed:

```html
<div role="grid" aria-colcount="6">
  <div role="rowgroup">
    <div role="row">
      <div role="columnheader" aria-colindex="1">First name</div>
      <div role="columnheader" aria-colindex="2">Last name</div>
      <div role="columnheader" aria-colindex="5">City</div>
      <div role="columnheader" aria-colindex="6">Zip</div>
    </div>
  </div>
  <div role="rowgroup">
    <div role="row">
      <div role="gridcell" aria-colindex="1">Debra</div>
      <div role="gridcell" aria-colindex="2">Burks</div>
      <div role="gridcell" aria-colindex="5">New York</div>
      <div role="gridcell" aria-colindex="6">14127</div>
    </div>
  </div>
  …
</div>
```

### Describing the position of gridcells when the overall structure is unknown

In situations where the table-style grouping of content does not provide information about the columns and rows, gridcells must have their positions programmatically described by using `aria-describedby`. The `id`s provided for `aria-describedby` should correspond to parent elements intended to be the rows and columns.

By referencing the parent elements with roles of `rowheader` or `columnheader` applied to them via `aria-describedby`, it allows assistive technology to understand the position and relationship of the `gridcell` element to the rest of the table-style grouping of content.

### Interactive grids and treegrids

#### Editable cells

Both `<td>` elements and elements with a role of `gridcell` applied to them can be made editable, mimicking functionality similar to editing a spreadsheet. This is done by applying the HTML `contenteditable` attribute.

```html
<td contenteditable="true">Notes</td>

<div role="gridcell" contenteditable="true">Item cost</div>
```

`contenteditable` will make the element it is applied to focusable via the `Tab` key. If a gridcell is conditionally toggled into a state where editing is prohibited, toggle `aria-readonly` on the gridcell element.

#### Expandable cells

In a treegrid, gridcells may be made expandable by toggling the `aria-expanded` attribute. Note that if this attribute is provided, it applies only to the individual gridcell.

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

`grid`

Communicates that a parent element is a table or tree style grouping of information.

`row`

Required to communicate the `gridcell` is part of a row of a table-style grouping of information.

`columnheader`

Specifies which element is the associated column header.

`aria-colindex`

Identifies the position of an element in relation to the rest of the table-style grouping of information's columns.

`rowheader`

Specifies which element is the associated row header.

`aria-rowindex`

Identifies the position of an element in relation to the rest of the table-style grouping of information's rows.

### Examples

The following example creates a table-style grouping of information:

```html
<h3 id="table-title">Jovian gas giant planets</h3>
<div role="grid" aria-describedby="table-title">
  <div role="rowgroup">
    <div role="row">
      <div role="columnheader">Name</div>
      <div role="columnheader">Diameter (km)</div>
      <div role="columnheader">Length of day (hours)</div>
      <div role="columnheader">Distance from Sun (10<sup>6</sup>km)</div>
      <div role="columnheader">Number of moons</div>
    </div>
  </div>
  <div role="rowgroup">
    <div role="row">
      <div role="gridcell">Jupiter</div>
      <div role="gridcell">142,984</div>
      <div role="gridcell">9.9</div>
      <div role="gridcell">778.6</div>
      <div role="gridcell">67</div>
    </div>
  </div>
  <div role="rowgroup">
    <div role="row">
      <div role="gridcell">Saturn</div>
      <div role="gridcell">120,536</div>
      <div role="gridcell">10.7</div>
      <div role="gridcell">1433.5</div>
      <div role="gridcell">62</div>
    </div>
  </div>
</div>
```

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

Support for `gridcell` and certain `gridcell` related ARIA roles and properties have poor support with assistive technologies. If at all possible, use HTML table markup in their place.

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

See also
--------

* The Table element
* ARIA: Grid role
* Grid Role - Maxability
* The Table row element
* ARIA: row role
* Row Role - Maxability
* aria-rowcount - Maxability
* ARIA: rowgroup role
* Rowgroup Role - Maxability
* The Table header element
* Columnheader - Maxability
* aria-colcount - Maxability
* The Table Data Cell element
* gridcell: Accessible Rich Internet Applications (WAI-ARIA) 1.1
* Gridcell Role - Maxability


ARIA: feed role - Accessibility

ARIA: feed role
===============

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

```html
<section role="feed" aria-busy="false">
  …
  <article aria-posinset="427" aria-setsize="-1">…</article>
  <article aria-posinset="428" aria-setsize="-1">…</article>
  <article aria-posinset="429" aria-setsize="-1">…</article>
  …
</section>
```

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

A `feed` is a type of `list`, the containing role for scrollable `articles` where scrolling may cause articles to be added to the top or end of the list. The role enables assistive technology to use the browse mode reading cursor to both read and scroll through a stream of rich content that may continue scrolling infinitely by loading more content as the user reads. Examples include an RSS feed, news feeds, social media feeds like Facebook, Instagram or Twitter, or even a list of related products on an e-commerce page. These streams can be limited or infinite, loading more content as the user scrolls. Implementing the `feed` pattern allows a screen reader to reliably read and trigger the loading of feed content while in reading mode.

Unlike the document structure elements that represent static HTML elements, the `feed` role requires specific interactions and implementation of keyboard navigation. The `feed` is a container element whose children are `<article>`s or have role `article`. Each article within a feed should be focusable, with tabindex of 0 or -1. An article should be scrolled into view when it, or a descendant element, receives focus. If the addition of articles occupies the main browser thread, make sure to set `aria-busy="true"` on the feed itself, and make sure to set it back to `false` when processing ends, or the user may not see the updates.

If the number of articles is known, set `aria-setsize` on the articles themselves. However, if the total number is extremely large, indefinite, or changes often, set `aria-setsize="-1"` to indicate that the size of the feed is not known.

Another feature of the feed pattern is skim reading: Articles within a feed can contain both an accessible name with the `aria-label` and a description with an `aria-describedby,` suggesting to screen readers which elements to speak after the label when navigating by article. By identifying the elements inside an article that provide the title and the primary content, assistive technologies can provide functions that enable users to jump from article to article and efficiently discern which articles they want to read.

The feed pattern enables reliable assistive technology reading mode interaction by establishing the following interoperability agreement between the web page and assistive technologies:

In the context of a feed, the web page code is responsible for:

* Appropriate visual scrolling of the content based on which article contains DOM focus.
* Loading or removing feed articles based on which article contains DOM focus.
### Keyboard interactions

Supporting the following, or a similar, interface is recommended when focus is inside the feed:

* `Page Down`: Move focus to next article.
* `Page Up`: Move focus to previous article.
* `Control + End`: Move focus to the first focusable element after the feed.
* `Control + Home`: Move focus to the first focusable element before the feed.

If a feed is nested within a feed, such as a comments feed within a feed of blog posts, the convention is to tab into the nested feed with the `Tab` key and to provide another key, such as `Alt + Page Down`, to navigate from an 'outer' article to the first item in that article's nested feed. Navigate between the nested feed and main feed with `Control + End`, moving focus from the inner feed to the next article in the outer feed.

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

`aria-label`

If the feed has no visible title, the `feed` element has a label specified with `aria-label`. If it does, see `aria-labelledby`.

`aria-labelledby`

If the feed has a visible title, the `feed` element has `aria-labelledby` referring to the element containing the title. If not, add an `aria-label`.

`aria-busy`

When busy, such as when articles are being added or removed from the `feed`, set `aria-busy="true"` during the update operation. Make sure it's reset to `false` when the operation is complete or the changes may not become visible.

article

Each section of content in a feed should be contained in an `<article>` or element with role `article`. Each `article` should have an `aria-labelledby` referring to the article title or other child that can serve as a distinguishing label. Each article should preferably have `aria-describedby` referring to one or more elements inside the article that serve as the primary content of the article. Each `article` element has `aria-posinset` set to a value that represents its position in the feed and an `aria-setsize` set to a value that represents either the total number of articles that have been loaded or the total number in the feed, depending on which value is more helpful to users. If the total number in the feed is not known, set `aria-setsize="-1"`.

### Required JavaScript features

None, except as required by any attributes. For example, setting `aria-busy` to `true` during the update operation if needed, and then to `false` upon completion.

Note: It is the author's responsibility to apply the "above" keyboard behavior.

Examples
--------

Example Implementation of Feed Pattern

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

To ensure good user experience, avoid inserting or removing articles in the middle of a `feed`, load new articles before the user has reached the end of the feed, and provide keyboard commands for moving focus among articles so that keyboard users can navigate through your feed. See Keyboard interactions.

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

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

See also
--------

* The HTML `<article>` element
* The `<ul>` unordered list element
* ARIA: `article` role
* ARIA: `list` role


ARIA: tab role - Accessibility

ARIA: tab role
==============

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

```html
<button role="tab" aria-selected="true" aria-controls="tabpanel-id" id="tab-id">
  Tab label
</button>
```

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

An element with the `tab` role controls the visibility of an associated element with the `tabpanel` role. The common user experience pattern is a group of visual tabs above, or to the side of, a content area, and selecting a different tab changes the content and makes the selected tab more prominent than the other tabs.

Elements with the role `tab` *must* either be a child of an element with the `tablist` role, or have their `id` as part of the `aria-owns` property of a `tablist`. This combination identifies to assistive technology that the element is part of a group of related elements. Some assistive technology will provide a count of the number of `tab` role elements inside a `tablist`, and inform users of which `tab` they currently have targeted. Further, an element with the `tab` role *should* contain the `aria-controls` property identifying a corresponding `tabpanel` (that has a `tabpanel` role) by that element's `id`. When an element with the `tabpanel` role has focus, or a child of it has focus, that indicates that the connected element with the `tab` role is the active tab in a `tablist`.

When elements with the `tab` role are selected or active they should have their `aria-selected` attribute set to `true`. Otherwise, their `aria-selected` attribute should be set to `false`. When a single-selectable `tablist` is selected or active, the `hidden` attribute of the other tabpanels should be set to true until the user selects the tab associated with that tabpanel. When a multi-selectable `tablist` is selected or active, its corresponding controlled `tabpanel` should have its `aria-expanded` attribute set to `true` and its `hidden` attribute set to `false`, otherwise the reverse.

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

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

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

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

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

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

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

### Associated roles and attributes

`aria-selected`

boolean

`aria-controls`

`id` of element with `tabpanel` role

id

content

### Keyboard interaction

| Key | Action |
| --- | --- |
| `Tab` | When focus is outside of the `tablist` moves focus to the active tab. If focus is on the active tab moves focus to the next element in the keyboard focus order, ideally the active tab's associated `tabpanel`. |
| `→` | Focuses and optionally activates the next tab in the tab list. If the current tab is the last tab in the tab list it activates the first tab. |
| `←` | Focuses and optionally activates the previous tab in the tab list. If the current tab is the first tab in the tab list it activates the last tab. |
| `Delete` | When allowed removes the currently selected tab from the tab list. |

### Required JavaScript features

**Note:** While there are ways to build tab-like functionality without JavaScript, there is no substitute combination using only HTML and CSS that will provide the same set of functionality that's required above for accessible tabs with content.

Example
-------

This example combines the role `tab` with `tablist` and elements with `tabpanel` to create an interactive group of tabbed content. Here we are enclosing our group of content in a `div`, with our `tablist` having an `aria-label` which labels it for assistive technology. Each `tab` is a `button` with the attributes previously mentioned. The first `tab` has both `tabindex="0"` and `aria-selected="true"` applied. These two attributes must always be coordinated as such—so when another tab is selected, it will then have `tabindex="0"` and `aria-selected="true"` applied. All unselected tabs must have `aria-selected="false"` and `tabindex="-1"`.

All of the `tabpanel` elements have `tabindex="0"` to make them tabbable, and all but the currently active one have the `hidden` attribute. The `hidden` attribute will be removed when a `tabpanel` becomes visible with JavaScript. There is some basic styling applied that restyles the buttons and changes the `z-index` of `tab` elements to give the illusion of it connecting to the `tabpanel` for active elements, and the illusion that inactive elements are behind the active `tabpanel`.

```html
<div class="tabs">
  <div role="tablist" aria-label="Sample Tabs">
    <button
 role="tab"
 aria-selected="true"
 aria-controls="panel-1"
 id="tab-1"
 tabindex="0">
      First Tab
    </button>
    <button
 role="tab"
 aria-selected="false"
 aria-controls="panel-2"
 id="tab-2"
 tabindex="-1">
      Second Tab
    </button>
    <button
 role="tab"
 aria-selected="false"
 aria-controls="panel-3"
 id="tab-3"
 tabindex="-1">
      Third Tab
    </button>
  </div>
  <div id="panel-1" role="tabpanel" tabindex="0" aria-labelledby="tab-1">
    <p>Content for the first panel</p>
  </div>
  <div id="panel-2" role="tabpanel" tabindex="0" aria-labelledby="tab-2" hidden>
    <p>Content for the second panel</p>
  </div>
  <div id="panel-3" role="tabpanel" tabindex="0" aria-labelledby="tab-3" hidden>
    <p>Content for the third panel</p>
  </div>
</div>
```

```
.tabs {
  padding: 1em;
}

[role="tablist"] {
  margin-bottom: -1px;
}

[role="tab"] {
  position: relative;
  z-index: 1;
  background: white;
  border-radius: 5px 5px 0 0;
  border: 1px solid grey;
  border-bottom: 0;
  padding: 0.2em;
}

[role="tab"][aria-selected="true"] {
  z-index: 3;
}

[role="tabpanel"] {
  position: relative;
  padding: 0 0.5em 0.5em 0.7em;
  border: 1px solid grey;
  border-radius: 0 0 5px 5px;
  background: white;
  z-index: 2;
}

[role="tabpanel"]:focus {
  border-color: orange;
  outline: 1px solid orange;
}
```

There are two things we need to do with JavaScript: we need to change focus and tab index of our `tab` elements with the right and left arrows, and we need to change the active `tab` and `tabpanel` when we click on a `tab`.

To accomplish the first, we listen for the `keydown` event on the `tablist`. If the event's `key` is `ArrowRight` or `ArrowLeft`, we react to the event. We start by setting the `tabindex` of the current `tab` element to -1, making it no longer tabbable. Then, if the right arrow is being pressed, we increase our tab focus counter by one. If the counter is greater than the number of `tab` elements we have, we circle back to the first tab by setting that counter to 0. If the left arrow is being pressed, we decrease our tab focus counter by one, and if it is then less than 0, we set it to the number of `tab` elements minus one (to get to the last element). Finally, we set `focus` to the `tab` element whose index is equal to the tab focus counter, and set its `tabindex` to 0 to make it tabbable.

To handle changing the active `tab` and `tabpanel`, we have a function that takes in the event, gets the element that triggered the event, the triggering element's parent element, and its grandparent element. We then find all tabs with `aria-selected="true"` inside the parent element and sets it to `false`, then sets the triggering element's `aria-selected` to `true`. After that, we find all `tabpanel` elements in the grandparent element, make them all `hidden`, and finally select the element whose `id` is equal to the triggering `tab`'s `aria-controls` and removes the `hidden` attribute, making it visible.

```js
window.addEventListener("DOMContentLoaded", () => {
  const tabs = document.querySelectorAll('[role="tab"]');
  const tabList = document.querySelector('[role="tablist"]');

  // Add a click event handler to each tab
  tabs.forEach((tab) => {
    tab.addEventListener("click", changeTabs);
  });

  // Enable arrow navigation between tabs in the tab list
  let tabFocus = 0;

  tabList.addEventListener("keydown", (e) => {
    // Move right
    if (e.key === "ArrowRight" || e.key === "ArrowLeft") {
      tabs[tabFocus].setAttribute("tabindex", -1);
      if (e.key === "ArrowRight") {
        tabFocus++;
        // If we're at the end, go to the start
        if (tabFocus >= tabs.length) {
          tabFocus = 0;
        }
        // Move left
      } else if (e.key === "ArrowLeft") {
        tabFocus--;
        // If we're at the start, move to the end
        if (tabFocus < 0) {
          tabFocus = tabs.length - 1;
        }
      }

      tabs[tabFocus].setAttribute("tabindex", 0);
      tabs[tabFocus].focus();
    }
  });
});

function changeTabs(e) {
  const target = e.target;
  const parent = target.parentNode;
  const grandparent = parent.parentNode;

  // Remove all current selected tabs
  parent
    .querySelectorAll('[aria-selected="true"]')
    .forEach((t) => t.setAttribute("aria-selected", false));

  // Set this tab as selected
  target.setAttribute("aria-selected", true);

  // Hide all tab panels
  grandparent
    .querySelectorAll('[role="tabpanel"]')
    .forEach((p) => p.setAttribute("hidden", true));

  // Show the selected panel
  grandparent.parentNode
    .querySelector(`#${target.getAttribute("aria-controls")}`)
    .removeAttribute("hidden");
}
```

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

It is recommended to use a `<button>` element with the role `tab` for their built-in functional and accessible features instead, as opposed to needing to add them yourself. For controlling tab key functionality for elements with the role `tab`, it is recommended to set all non-active elements to `tabindex="-1"`, and to set the active element to `tabindex="0"`.

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

What are the related properties, and in what order will this attribute or property be read, which property will take precedence over this one, and which property will be overwritten.

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

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

See also
--------

* HTML `<button>` element
* KeyboardEvent.key
* ARIA `tabpanel` role


ARIA: directory role - Accessibility

ARIA: directory role
====================

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

**Warning:** The `directory` role was deprecated in ARIA 1.2

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

A directory is a static table of contents, whether linked or unlinked. This includes tables of contents built with lists, including nested lists. Dynamic tables of contents, however, might use a tree role instead.

 The deprecated `directory` role was used for lists of references to members of a group, such as a static table of contents.
 Use the `list` role instead. Or, better yet, use the `<ul>` or `<ol>` elements, as using `directory` does not provide any additional benefits to assistive technology users.

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

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

See Also
--------

* The `list` role
* The `<ul>` element
* The `<ol>` element


ARIA: rowgroup role - Accessibility

ARIA: rowgroup role
===================

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

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

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

`Rowgroup` establishes a relationship between owned row elements and is a structural equivalent to the `<thead>`, `<tfoot>` and `<tbody>` elements in HTML. There is, however, no differentiation between different types of rowgroups. Their elements must be contained in, or owned by, elements with either the table or grid role. Using the native `<thead>`, `<tfoot>` and `<tbody>` HTML elements, whenever possible, is strongly encouraged.

To create an ARIA table header, table footer or table body, add `role="rowgroup"` to the element. That rowgroup should be nested within a grid, table or treegrid, encompassing a group of one or more rows. Each row, in turn, contains child cells. These cells can be of different types, depending on whether they are column or row headers, or plain or grid cells.

**Note:** Using the native HTML table element (`<table>`) along with the table header (`<thead>`), footer (`<tfoot>`), and body (`<tbody>`) elements whenever possible is strongly encouraged.

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

#### Context roles

role="table"

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

role="grid"

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

role="treegrid"

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

#### Descendant roles

role="row"

A row of cells within a tabular structure. A row contains one or more cells, gridcell, or column headers, and sometimes a row header.

### 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>` element instead of the ARIA role of table whenever possible.

Examples
--------

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

The above is a non-semantic ARIA table with 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. 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 the ARIA table role 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">
      <td role="cell">header</td>
      <td role="cell">h1</td>
    </tr>
    <tr role="row" aria-rowindex="16">
      <td role="cell">header</td>
      <td role="cell">h6</td>
    </tr>
  </tbody>
</table>
```

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

### Added benefits

none

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

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

See also
--------

* HTML table
* HTML table body
* HTML table footer
* HTML table header


ARIA: separator role - Accessibility

ARIA: separator role
====================

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

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

A separator is a divider that separates and distinguishes sections of content or groups of menuitems. There are two types of separators: a static structure that provides a visible boundary, identical to the HTML `<hr>` element, and a focusable, moveable widget.

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

### Non-focusable separator

A non-focusable separator is a static structural element that can be used to help visually divide two groups of menu items in a menu or to provide a horizontal rule between two sections of a page. Thematic breaks that aren't focusable can still be perceivable by a screen reader user when using a reading cursor that does not depend on focus.

```html
<h2>My first blog post</h2>
…
<img src="blueline.gif" role="separator" alt="" />
<h2>Two years later, my second post</h2>
…
```

In the example, an image creates a visual separator between two blog posts. The author could have used a semantic thematic break `<hr>` element and styled it with CSS to make it blue (and not have to change the image when they change the blog's theme), or the author could have encompassed each post in the semantic `<article>` element, or both.

```html
<section role="feed">
  <article>
    <h2>My first blog post</h2>
    …
  </article>
  <hr />
  <article>
    <h2>Two years later, my second post</h2>
    …
  </article>
</section>
```

```css
[role="feed"] > hr {
  height: 3px;
  background-color: blue;
}
```

An accessible name is not needed.

### Focusable separator

The separator role can be used to identify the element as a visual separator between groups of items within a menu, such as groups of `menuitemradio` or `menuitemcheckbox` elements.

If the separator is focusable, providing a visible boundary between two sections of content and enabling the user to change the relative size of the sections it separates by changing its position, the value of `aria-valuenow` must be set to a number reflecting the current position of the separator and the value must be updated when it changes. The `aria-valuemin` and `aria-valuemax` should also be included if they aren't set to the default values of 0 and 100, respectively.

An accessible name, with `aria-label` should be included if there is more than one focusable separator.

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

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

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

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

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

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

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

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

`aria-orientation` (default is horizontal for separator)

By default, the divider for `separator` roles is assumed to be horizontal. The value can be included and set to horizontal, undefined (the default for other roles unless otherwise specified), or vertical.

`aria-valuenow`

If the separator is focusable and has a known value, the `aria-valuenow` defines the current value. If not focusable or the value is unknown, do not include this attribute.

`aria-valuemin` (default is 0)

If the separator is focusable, and the minimum value is not 0, include the minimum value with `aria-valuemin`. If the

`aria-valuemax` (default is 100)

If the separator is focusable, and the maximum value is not 100, include `aria-valuemax` with a value equal to or larger than `aria-valuemin`.

`aria-valuetext`

If the separator is focusable, and the `aria-valuenow` is not optimal in providing the user with usable information, included `aria-valuetext` content will be read instead of the `aria-valuenow` value.

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

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

See Also
--------

* Thematic break HTML `<hr>` element
* Example separator in a menubar


ARIA: searchbox role - Accessibility

ARIA: searchbox role
====================

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

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

The `searchbox` can be used instead of `textbox` when the text box is within an element with role `search`. A `searchbox` is the semantic equivalent is HTML's `<input>` of type `search`, `<input type="search">`, which should be used instead if possible.

 The `searchbox` must have an accessible name. If the `searchbox` role is applied to an HTML `<input>` element, an associated `<label>` should be used.
 Otherwise, use `aria-labelledby` if a visible label is present, or `aria-label` if a visible label is not present.

The screen reader will announce "search box", "search edit", or "search field" plus the accessible name. This can be redundant if "search" is included in the label.

Examples
--------

```html
<div tabindex="0" aria-label="search" role="searchbox" contenteditable></div>
```

While the above is valid, it is simpler, more concise, and less redundant to the screen reader user to write:

```html
<input type="search" />
```

The following is a search form with a searchbox and button, ARIA live region, and container for search results.

```html
<form role="search">
  <input
 type="search"
 role="searchbox"
 aria-description="search results will appear below"
 id="search"
 value="" />
  <label for="search">Search this site</label>
  <button>Submit search</button>
</form>
<div aria-live="polite" role="region" aria-atomic="true">
  <div class="sr-only"></div>
</div>
<div id="search-results"></div>
```

Including `role="searchbox"` when the form is a `search` and the label indicates the element is a search may result in assistive technology announcing something along the lines of "search search this site search box", which is redundant. The inclusion of `role="searchbox"` is not necessary:

```html
<input
 type="search"
 aria-description="search results will appear below"
 id="search"
 value="" />
```

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

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

See Also
--------

* `<input type="search">`
* ARIA: `search` role
* ARIA: `textbox` role


ARIA: definition role - Accessibility

ARIA: definition role
=====================

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

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

The `definition` ARIA role can be included on an element that is a definition of a term or concept, similar to the native `<dfn>` element. To associate the definition with the `term` being defined, and to provide an accessible name, reference the term being defined with `role="term"`, using `aria-labelledby`.

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

**Note:** Instead of a `<span>` with the `term` and `definition` roles, use the `<dfn>` element. **Always use native element if available.**

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

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

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

See Also
--------

* The `term` role
* The `<dfn>` element
* The `<dd>` element
* The `<dl>` element
* The `<dt>` element