recursal/MDN huggingface dataset:
How to file ARIA-related bugs
=============================

The state of ARIA technology has always depended on the community. If you notice an implementation issue, please take a little time and let the developers know. Here's where to file bugs:

### Screen Readers

| Software | Where to file | Notes |
| --- | --- | --- |
| Freedom Scientific JAWS | JAWS technical support form |  |
| GW Micro Window Eyes | Window-Eyes comments, questions, and feedback |  |
| Non Visual Desktop Access (NVDA) | File NVDA bugs | Discuss NVDA issues |

### Browsers

| Software | Where to file | Notes |
| --- | --- | --- |
| Apple Safari | File WebKit.org bugs |  |
| Google Chrome | File Chromium bugs |  |
| Mozilla Firefox | File Firefox bugs | Use Component: Disability Access APIs |
| Opera | File Opera bugs | Use [ARIA] in the summary field |
ARIA guides
===========

 Accessible Rich Internet Applications (**ARIA**) define ways to make the web more accessible to people with disabilities.
 This page lists the guides that you can use to help improve the accessibility of web page features such as tables, forms, and keyboard-navigation.

* Designing accessible forms
* Understanding WAI-ARIA basics
* Creating keyboard-navigable JavaScript widgets
* Using ARIA for labels with embedded fields inside them
* Managing focus in composite widgets (`aria-activedescendant` vs. roving tabindex)
* Testing ARIA
* Displaying accessible tables
See also
--------

The following references are helpful for common accessibility use cases:

* Labeling widgets
* Landmark roles
* ARIA live regions
* HTML Drag and Drop API
* ARIA: presentation role
ARIA: log role
==============

The `log` role is used to identify an element that creates a live region where new information is added in a meaningful order and old information may disappear.

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

A log is a type of live region where new information is added in meaningful order and old information may disappear. Examples include chat logs, messaging history, game log, or an error log. In contrast to other live regions, in this role there is a relationship between the arrival of new items in the log and the reading order. The log contains a meaningful sequence and new information is added only to the end of the log, not at arbitrary points.

In contrast to other types of live region, a log is sequentially ordered and new information is only added to the end of the log. When this role is added to an element, the browser will send out an accessible log event to assistive technology products which can then notify the user about it.

By default, updates contain only the changes to the live region and these are announced when the user is idle. Elements with the role `log` have an implicit `aria-live` value of `polite`. Where the user needs to hear the entire live region upon a change `aria-atomic="true"` should be set. To have announcements made as soon as possible and where the user may be interrupted, `aria-live="assertive"` can be set for more aggressive updates.

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

`aria-atomic`

Defines whether assistive technologies should present all, or only parts of, the changed region. Elements with the role `log` have an implicit aria-atomic value of `false`.

`aria-live`

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

`aria-label` and `aria-labelledby`

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

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

With an area that has scrolling text, such as a stock ticker, the `marquee` role should be used instead.

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

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

See Also
--------

* ARIA: `alert` role
* ARIA: `marquee` role
* ARIA: `status` role
* ARIA: `timer` role
* ARIA live regions
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: 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: 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: 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
=====================

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
ARIA: range role
================

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

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

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

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

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

Do not use.

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

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

See Also
--------

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

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

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

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

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

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

Do not use.

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

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

See Also
--------

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

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

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

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

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

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

`aria-sort`

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

### Keyboard interactions

This role does not support any specific keyboard interaction.

### Required JavaScript features

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

Examples
--------


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

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

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

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

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

### Prefer HTML

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

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

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

See Also
--------

* `table` role
* `grid` role
* `treegrid` role
* `row` role
* `rowgroup` role
* The `<th>` element
* The `<table>` element
* The `<tr>` element
* The `<td>` element
ARIA: input role
================

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

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

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

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

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

Do not use.

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

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

See Also
--------

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

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


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

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

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

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

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

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

`list`

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

`group`

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

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

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

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


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


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


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


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

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

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

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

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

See also
--------

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

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

Examples
--------

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


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


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


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

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


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

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

### Prefer HTML

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

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

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

See also
--------

* ARIA annotations