aria-atomic - Accessibility

aria-atomic
===========

In ARIA live regions, the global `aria-atomic` attribute indicates whether assistive technologies such as a screen reader will present all, or only parts of, the changed region based on the change notifications defined by the `aria-relevant` attribute.

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

Live regions are sections of a web page that are updated, whether by user interaction or not, when user focus is elsewhere. As they update outside the user's focus, assistive technologies such as screen readers may not "see" the update to report it to the user. WAI-ARIA has 4 properties that allow the developer to identify these live regions and tell the assistive technology how to process them, including `aria-live`, `aria-relevant`, `aria-busy` and `aria-atomic`.

When the content of a live region changes, the DOM is traversed from the changed element through its ancestors to find the first element with `aria-atomic` set. This determines the content that the user should be presented with.

If no ancestor has explicitly set `aria-atomic`, only the node or nodes of live region content that have been updated are read. The difference between omitting `aria-atomic` altogether and explicitly setting an ARIA live region's ancestor node with `aria-atomic="false"` is that explicitly setting `aria-atomic="false"` will stop the screen reader from going up the ancestor chain. Both lead to only the updated node being read. When set to `aria-atomic="true"`, the entire changed region as a whole will be presented, including the updated node's `label`, if there is one.

Values
------

`false` (default)

present only the changed node or nodes.

`true`

present the entire changed region as a whole, including the author-defined label if one exists.

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

Used in **ALL** roles.

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

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

See Also
--------

* Event.ariaAtomic


aria-description - Accessibility

aria-description
================

The global `aria-description` attribute defines a string value that describes or annotates the current element.

**Note:** `aria-description` is still in W3C Editor's Draft for ARIA 1.3. For the time being, continue to use `aria-describedby`, which has been supported since ARIA 1.1.

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

The global `aria-description` attribute provides a mechanism for the developer to describe or annotate the current element providing greater context for assistive technology users.

```html
<div
 role="application"
 aria-label="calendar"
 aria-description="Game schedule for the Boston Red Sox 2021 Season">
  <h1>Red Sox 2021</h1>
  <div role="grid">…</div>
</div>
```

The `aria-description` attribute is similar to `aria-label` in that both provide a text string to associate with the element, but a label should be short and concise, while the description can be longer as it is intended to provide more context and information.

The `aria-description` and `aria-describedby` properties have the same purpose; both provide the user with additional descriptive text for the object on which it is set. If descriptive text is available in the DOM, use `aria-describedby` instead.

The `aria-description` property should only be used when providing a visible description is not the desired user experience. The `aria-describedby` attribute takes as its value a list of `id`s of the elements that contain descriptive text about the object. The `aria-description` is used when there is no appropriate descriptive text that can be associated with the object by `id` reference. If both attributes are present, `aria-describedby` takes precedence in defining the accessible description property.

The content of the description, whether set by `aria-description` or `aria-describedby`, should be flat text. If the content is very long, has semantic meaning requirements, or has a navigational structure, use `aria-details` instead.

Values
------

`<string>`

The value is a string, an unconstrained value type, that is intended to be conveyed to the assistive technology user.

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

`Element.ariaDescription`

The `ariaDescription` property, part of the `Element` interface, reflects the value of the `aria-description` attribute, which defines a string value that describes or annotates the current element.

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

Used in **ALL** roles.

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

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

See Also
--------

* HTML `title` attribute
* `aria-describedby`
* `aria-details`


aria-hidden - Accessibility

aria-hidden
===========

The `aria-hidden` state indicates whether the element is exposed to an accessibility API.

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

The `aria-hidden` attribute can be used to hide non-interactive content from the accessibility API.

Adding `aria-hidden="true"` to an element removes that element and all of its children from the accessibility tree. This can improve the experience for assistive technology users by hiding:

* Purely decorative content, such as icons or images
* Duplicated content, such as repeated text
* Offscreen or collapsed content, such as menus

The presence of the `aria-hidden` attribute hides content from assistive technology but doesn't visually hide anything.

`aria-hidden="true"` should not be used on elements that can receive focus. Additionally, since this attribute is inherited by an element's children, it should not be added onto the parent or ancestor of a focusable element.

**Warning:** Do not use `aria-hidden="true"` on focusable elements.

An element's hidden status is based on whether it is rendered. Rendering is usually controlled by CSS. For example, an element whose `display` property is set to `none` via CSS is not rendered. An element is considered hidden if it, or any of its ancestors are not rendered or have their `aria-hidden` attribute value set to true. Note that an element and its children that has `aria-hidden="true"` declared on it will still be visible, unless also hidden by CSS.

Use caution when using `aria-hidden` to hide visibly rendered content from assistive technologies. You should not be hiding visible content unless doing so improves the experience for users of assistive technologies by removing redundant or extraneous content. Only when identical or equivalent meaning and functionality is exposed to assistive technologies can removing visible content from the accessibility API be considered.

**Note:** Consider all disabilities when hiding visibly rendered content from assistive technologies. Not all users of assistive technology are visually impaired. If visible content doesn't match text content in the accessibility API, the user experience will be negatively impacted for sighted users.

On the surface, the `aria-hidden="true"` and the `role="presentation"` and its synonym `role="none"` seem similar, but the intent behind each is different.

* `aria-hidden="true"` will remove the entire element from the accessibility API.
* `role="presentation"` and `role="none"` will remove the semantic meaning of an element while still exposing it and its content to assistive technology.

`aria-hidden="true"` should not be added when:

* The HTML `hidden` attribute is present
* The element or the element's ancestor is hidden with `display: none`
* The element or the element's ancestor is hidden with `visibility: hidden`

In all three scenarios, the attribute is unnecessary to add because the element has already been removed from the accessibility tree. Visually hiding elements with `display` or `visibility` hides content from the screen and from assistive technologies.

Using `aria-hidden="false"` will not re-expose the element to assistive technology if any of its parents specify `aria-hidden="true"`.

Example
-------

Adding `aria-hidden="true"` to the icon hides the icon character from being included in the accessible name.

```html
<button>
  <span class="fa fa-tweet" aria-hidden="true"></span>
  <span class="label"> Tweet </span>
</button>
```

We have a button with a Font Awesome icon. We hide the icon from assistive technologies with `aria-hidden="true"`, as exposing the icon to assistive technologies could lead to redundancy or, if the icon doesn't have the same content as the visible text, confusion.

Values
------

`false`

The element is exposed to the accessibility API as if it was rendered.

`true`

The element is hidden from the accessibility API.

`undefined` (default)

The element's hidden state is determined by the user agent based on whether it is rendered.

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

`Element.ariaHidden`

The `ariaHidden` property, part of the `Element` interface, reflects the value of the `aria-hidden` attribute, which Indicates whether the element is exposed to an accessibility API.

`ElementInternals.ariaHidden`

The `ariaHidden` property, part of the `ElementInternals` interface, reflects the value of the `aria-hidden` attribute

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

Used in **ALL** roles

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

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

See Also
--------

* `aria-disabled`
* `aria-modal`
* `aria-expanded`
* HTML `hidden` attribute
* CSS `display` property
* CSS `visibility` property


aria-setsize - Accessibility

aria-setsize
============

The `aria-setsize` attribute defines the number of items in the current set of listitems or treeitems when not all items in the set are present in the DOM.

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

Browsers automatically calculate the set size and position for each item in a group of items, like the number of `<li>`s in a list, buttons in a same-named group of radio buttons, and `<option>`s in a `<select>`. Assistive technologies, like screen readers, take advantage of this state management to report set sizes to the user.

When the DOM is not complete, the browser calculation of the number of items in a set can be incorrect. When only a subset of items, such as list items, are loaded into the DOM, the browser calculates the number of items based only on those present. The `aria-setsize` attribute should be used to override the browser's incorrect count. It defines the number of items in the current set of listitems or treeitems had the entire set been loaded.

`aria-setsize` attribute is set on each item, rather than on any containing element. The value is the same for each item: an integer reflecting number of items in the complete set, or `-1` if the set size is unknown. If all the items are present in the DOM, the browser can calculate the set size and the position of each item, making both `aria-setsize` and `aria-posinset` unnecessary.

Elements with the `aria-setsize` generally have the `aria-posinset` attribute included as well to indicate the position of that item within the set. The `aria-posinset` value is between `1` and the positive value of `aria-setsize`.

For example, in a page's comments section, When comments in are not all in the DOM, such as when comments are paginated, the level, total number of comments, and position of each comment should be set with ARIA. The hierarchical level of comments can be indicated with `aria-level`. Group positional information is indicated with `aria-posinset` and `aria-setsize`.

When a feed has a static number of articles, `aria-setsize` can be added to each article element with the value being either the total number of articles loaded or the total number in the feed. The value chosen depends on which value is most helpful to users. If the number of articles is extremely large, indefinite, or changes often, `aria-setsize="-1"` can be set to communicate the size of the set is unknown.

In a `listbox`, when the complete set of available options is not present in the DOM due to dynamic loading on scroll, both `aria-setsize` and `aria-posinset` can be set on each `option`.

In a tree view, if the complete set of available nodes is not present in the DOM due to dynamic loading as the user moves focus in or scrolls the tree, each node has `aria-level`, `aria-setsize`, and `aria-posinset` set.

In a menu, `aria-setsize` is set on all `menuitem`, `menuitemcheckbox`, or `menuitemradio` roles, with the value being the total number of items in the menu, excluding any separators.

Example
-------

The following example shows items 5 through 8 in a set of 16.

```html
<h2 id="label\_fruit">Available Fruit</h2>
<ul role="listbox" aria-labelledby="label\_fruit">
  <li role="option" aria-setsize="16" aria-posinset="5">apples</li>
  <li role="option" aria-setsize="16" aria-posinset="6">bananas</li>
  <li role="option" aria-setsize="16" aria-posinset="7">cantaloupes</li>
  <li role="option" aria-setsize="16" aria-posinset="8">dates</li>
</ul>
```

To orient the user, assistive technologies would list the bananas above as "item 6 out of 16."

Values
------

`<integer>`

The number of items in the full set or `-1` is the set size is unknown.

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

`Element.ariaSetSize`

The `ariaSetSize` property, part of the `Element` interface, reflects the value of the `aria-setsize` attribute.

`ElementInternals.ariaSetSize`

The `ariaSetSize` property, part of the `ElementInternals` interface, reflects the value of the `aria-setsize` attribute.

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

Used in roles:

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

Inherits into roles:

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

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

See Also
--------

* `aria-posinset`
* Treegrid Email Inbox example
* Navigation Treeview Using Declared Properties example


aria-multiselectable - Accessibility

aria-multiselectable
====================

The `aria-multiselectable` attribute indicates that the user may select more than one item from the current selectable descendants.

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

The default behavior of selection lists, such as `<select>`, is to be able to choose only one item or option. By default or by convention, when a user is presented with list from which they must select an item, they assume they can only select a single item unless otherwise notified. The `aria-multiselectable` attribute is the way to inform assistive technology users that they may select more than one item from the current selectable items if they so choose. Lists and trees are examples of roles that might allow users to select more than one item at a time.

**Note:** When allowing for multiple selections, inform the user that multiple values are allowed and provide directions on how to provide multiple values, such as "to select more than one value, keep the control key pressed during selection."

### Used with `aria-selected`

When the user does select one or more items, remember to set the selected descendants as selected with `aria-selected="true"`, and selectable descendants that are not selected have `aria-selected="false"` set. If an element is not selectable, omit the `aria-selected` attribute altogether as its presence informs the user the item is selectable.

If a tree, grid, tab list, or list box supports selection of more than one node, the element with role `grid`, `listbox`, `tablist`, or `tree` has `aria-multiselectable` set to `true`. Otherwise, `aria-multiselectable` is either set to `false` or the default value of false is implied.

Example
-------

```html
<p id="colorOptions">Choose the colors for your flag.</p>
<ul
 tabindex="0"
 role="listbox"
 aria-labelledby="colorOptions"
 aria-multiselectable="true">
  <li id="red" role="option" aria-selected="false">Red</li>
  <li id="orange" role="option" aria-selected="false">Orange</li>
  <li id="yellow" role="option" aria-selected="false">Yellow</li>
  <li id="green" role="option" aria-selected="false">Green</li>
  <li id="blue" role="option" aria-selected="false">Blue</li>
  <li id="purple" role="option" aria-selected="false">Purple</li>
  <li id="magenta" role="option" aria-selected="false">Hot pink</li>
  <li id="lightpink" role="option" aria-selected="true">Light pink</li>
  <li id="white" role="option" aria-selected="true">White</li>
  <li id="lightblue" role="option" aria-selected="true">Light blue</li>
  <li id="black" role="option" aria-selected="false">Black</li>
  <li id="brown" role="option" aria-selected="false">Brown</li>
</ul>
```

This listbox supports multiple selection so we set the element with role `listbox` with `aria-multiselectable="true"`. All selected options have `aria-selected` set to `true`. All options that are not selected but are selectable have `aria-selected` set to false. Had we included options that were disabled or otherwise not selectable, we would have omitted the `aria-selected` attribute altogether. Including the attribute, even with no value or explicitly set to `false` indicates to assistive technology users that the item is selectable.

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." Instead of creating an unordered list requiring `tabindex`, ARIA and JavaScript to turn text into selectable options, we could have used a native multiselect: the `<select>` element has a Boolean `multiple` attribute. If included, the user can select multiple options. If not, only a single option can be selected.

```html
<label for="flagcolors"> Choose the colors for your flag. </label>
<select multiple id="flagcolors">
  <option value="red">Red</option>
  <option value="orange">Orange</option>
  <option value="yellow">Yellow</option>
  <option value="green">Green</option>
  <option value="blue">Blue</option>
  <option value="purple">Purple</option>
  <option value="magenta">Hot pink</option>
  <option value="lightpink" selected>Light pink</option>
  <option value="white" selected>White</option>
  <option value="lightblue" selected>Light blue</option>
  <option value="black">Black</option>
  <option value="brown">Brown</option>
</select>
```

This HTML `<select>` version is accessible and interactive, and needs no ARIA or JavaScript to function.

If the above isn't stylable to your liking, you can also create a list of selectable options with HTML checkboxes, which is also semantic, focusable, and infinitely stylable with CSS:

```html
<fieldset>
  <legend>Choose the colors for your flag.</legend>
  <ul>
    <li>
      <label><input type="checkbox" name="fc" value="red" />Red</label>
    </li>
    <li>
      <label><input type="checkbox" name="fc" value="orange" />Orange</label>
    </li>
    <li>
      <label><input type="checkbox" name="fc" value="yellow" />Yellow</label>
    </li>
    <li>
      <label><input type="checkbox" name="fc" value="green" />Green</label>
    </li>
    <li>
      <label><input type="checkbox" name="fc" value="blue" />Blue</label>
    </li>
    <li>
      <label><input type="checkbox" name="fc" value="purple" />Purple</label>
    </li>
    <li>
      <label><input type="checkbox" name="fc" value="magenta" />Hot pink</label>
    </li>
    <li>
      <label
 ><input type="checkbox" name="fc" value="lightpink" checked />Light
        pink</label
 >
    </li>
    <li>
      <label
 ><input type="checkbox" name="fc" value="white" checked />White</label
 >
    </li>
    <li>
      <label
 ><input type="checkbox" name="fc" value="lightblue" checked />Light
        blue</label
 >
    </li>
    <li>
      <label><input type="checkbox" name="fc" value="black" />Black</label>
    </li>
    <li>
      <label><input type="checkbox" name="fc" value="brown" />Brown</label>
    </li>
  </ul>
</fieldset>
```

Instead of `aria-selected="true"`, include the `checked` attribute. The browser does the rest.

Values
------

`true`

More than one item in the widget may be selected at a time

`false`

Only one item can be selected

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

`Element.ariaMultiSelectable`

The `ariaMultiSelectable` property, part of the `Element` interface, reflects the value of the `aria-multiselectable` attribute.

`ElementInternals.ariaMultiSelectable`

The `ariaMultiSelectable` property, part of the `ElementInternals` interface, reflects the value of the `aria-multiselectable` attribute.

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

Used in roles:

* `grid`
* `listbox`
* `tablist`
* `tree`

Inherited into roles:

* `treegrid`
Specifications
--------------

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

See Also
--------

* HTML `<select>` element
* HTML `<option>` element
* HTML `<input>` element
* multiple attribute
* `aria-selected`


aria-level - Accessibility

aria-level
==========

The `aria-level` attribute defines the hierarchical level of an element within a structure.

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

Levels of hierarchy appear in headings, trees, nested grid, nested tablists, and more. If the DOM ancestry does not accurately represent the level, the `aria-level` attribute should be used to define the hierarchical level elements within their hierarchical structures. Levels increase with depth. The value for aria-level is an integer greater than or equal to `1`.

When it comes to the headings in a document structure, you can have first-level headings, second-level headings, third-level headings, etc. In trees, you have the root element, its children, the children's children (or grandchildren), and so on.

The `aria-level` attribute exposes hierarchy to assistive technologies so it can be communicated to the users. Like all ARIA attributes, it has no impact on the user agent and therefore no impact on the user agent's determination of the document structure.

If the DOM ancestry accurately represents the level, the user agent can calculate the level of an item from the document structure, making `aria-level` not only redundant but a risk of creating misinformation. `aria-level` should really only be used to provide an explicit indication of level when it is not possible to calculate from the document structure. Test to see if this attribute is needed. If the user agent can calculate the level, it is best to omit the `aria-level` attribute.

### With `heading` role

The `aria-level` attribute is a required attribute of the `heading` role which indicates to assistive technologies that the element should be treated as a heading. `<div role="heading" aria-level="1">` defines the `<div>` as being the main heading of the page. A level 2 heading, defined with `aria-level="2"` would be the first subsection, a level 3 is a subsection of that, and so on.

```html
<div role="heading" aria-level="3">Heading for this sub section</div>
```

Opt for using the h1 through h6 elements instead.

### Within `treegrid` role

In the case of a `treegrid`, `aria-level` is supported on elements with the role `row`, not elements with role `gridcell`. Rows act as leaf nodes within the vertical orientation of the grid. Gridcells are leaf nodes within the horizontal orientation of each row. `Aria-level` is not supported on cells within rows. So, in treegrids, the `aria-level` attribute is applied to the element with the role `row`.

If a complete set of available nodes is not present in the DOM due to dynamic loading as the user moves focus in or scrolls the tree, each node has `aria-level`, `aria-setsize`, and `aria-posinset` included.

Values
------

`<integer>`

An integer greater than or equal to 1

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

`Element.ariaLevel`

The `ariaLevel` property, part of the `Element` interface, reflects the value of the `aria-level` attribute.

`ElementInternals.ariaLevel`

The `ariaLevel` property, part of the `ElementInternals` interface, reflects the value of the `aria-level` attribute.

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

Used in roles:

* `associationlistitemkey`
* `comment`
* `heading`
* `row`
Specifications
--------------

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

See Also
--------

* `<h1>` through `<h6>`: The HTML Section Heading elements (h1, h2, h3, h4, h5, and h6)


aria-rowcount - Accessibility

aria-rowcount
=============

The `aria-rowcount` attribute defines the total number of rows in a table, grid, or treegrid.

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

Some tables have hundreds, even millions, of rows. Even for tables with fewer rows, loading only a subsection of rows may be a design requirement, improve performance, or improve user experience. When only a subset of rows are loaded, you do need to let all users know that only a subset of the data is being displayed. The `aria-rowcount` attribute is used to define the total number of rows in a table, grid, or treegrid.

Included on the `<table>` element or on an element with a role of `table`, the value is the number of rows in the full table, as an integer. If the total number of rows is not known, include `aria-rowcount="-1"`, which tells the browser to not count the total number of rows.

If all of the rows are loaded and in the DOM, you don't need to include `aria-rowcount` as browsers automatically count the total number of rows. However, if the rows aren't all present in the DOM at any time, this attribute is needed to provide the number of rows when the full table size is known and to tell the browser to not automatically count the rows when the total number of rows is not known.

Example
-------

The following example shows a grid with 24 rows, of which the first row and rows 7 through 9 are displayed to the user.

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

Values
------

`<integer>`

The number of rows in the full table or `-1` is the table size is not known.

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

`Element.ariaRowCount`

The `ariaRowCount` property, part of the `Element` interface, reflects the value of the `aria-rowcount` attribute.

`ElementInternals.ariaRowCount`

The `ariaRowCount` property, part of the `ElementInternals` interface, reflects the value of the `aria-rowcount` attribute.

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

Used in roles:

* `table`

Inherited into roles:

* `grid`
* `treegrid`
Specifications
--------------

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

See Also
--------

* `aria-rowindex`
* `aria-colcount`


aria-rowspan - Accessibility

aria-rowspan
============

The `aria-rowspan` attribute defines the number of rows spanned by a cell or gridcell within a table, grid, or treegrid.

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

Similar to the `rowspan` attribute of the `<td>` and `<th>` elements, but for cells and gridcells which are not contained in a native table, the `aria-rowspan` attribute defines the number of rows spanned by a `cell` or `gridcell` within a `table`, `grid`, or `treegrid`.

This attribute is intended for cells and gridcells which are **not** part of an HTML `<table>`. When a cell is nested in a semantic `<table>`, the `rowspan` attribute should be used when a or spans more than one row. If both are present, `rowspan` takes precedence over `aria-rowspan`. But, like all ARIA attributes, `aria-rowspan` only impacts the accessibility tree. It doesn't change your layout.

**Note:** ARIA modifies the accessibility tree and how assistive technology presents content to your users. ARIA doesn't change anything about an element's function, behavior, or appearance. When using non-semantic elements, you must use CSS to manage layout and appearance.

The value of `aria-rowspan` is an integer greater than or equal to 0 and less than the value which would cause the cell or gridcell to overlap the next cell or gridcell in the same column. Setting the value to `0` indicates that the cell or gridcell is to span all the remaining rows in the row group. The default value is `1`.

Values
------

`<integer>`

An integer greater than or equal to `0` and less than would cause a cell to overlap the next cell in the same column.

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

`Element.ariaRowSpan`

The `ariaRowSpan` property, part of the `Element` interface, reflects the value of the `aria-rowspan` attribute.

`ElementInternals.ariaRowSpan`

The `ariaRowSpan` property, part of the `ElementInternals` interface, reflects the value of the `aria-rowspan` attribute.

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

Used in roles:

* `cell`

Inherited into roles:

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

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

See Also
--------

* The `rowspan` attribute on `<td>`
* `aria-rowindex`
* `aria-colspan`


aria-orientation - Accessibility

aria-orientation
================

The `aria-orientation` attribute indicates whether the element's orientation is horizontal, vertical, or unknown/ambiguous.

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

It may be important for the user to know the orientation to know how to navigate certain widgets, as orientation impacts the expected behaviors of the left, right, up and down arrows. The `aria-orientation` attribute is used to indicate to assistive technology users whether an element's orientation is `horizontal` or `vertical`, or `undefined`.

Several widgets have default orientations:

Horizontal by default:

* `slider`,
* `tablist`
* `toolbar`
* `menubar`

Vertical by default:

* `scrollbar`
* `tree`
* `listbox`
* `menu`

Each `separator` should have `aria-orientation` consistent with the separator's orientation.

When nodes in a tree are arranged horizontally instead of its default vertical orientation, or when a tab list is vertical instead of its default horizontal, the down arrow performs as a right arrow normally would, and the up arrow performs as a left arrow normally would. In these instances, assistive technology users need to know the widget's orientation so as to navigate correctly.

Up and down arrows are generally available for normal browser scrolling, even when focus is inside a tree or tab list. Include `aria-orientation` to enable alerting users when a widget doesn't have the default, expected orientation and associated navigation.

Always remember that ARIA only modifies how assistive technology presents content to your users; altering the behavior of arrow keys requires JavaScript.

Values
------

`horizontal`

The element is oriented horizontally.

`undefined` (default)

The element's orientation is unknown/ambiguous.

`vertical`

The element is oriented vertically.

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

`Element.ariaOrientation`

The `ariaOrientation` property, part of the `Element` interface, reflects the value of the `aria-orientation` attribute.

`ElementInternals.ariaOrientation`

The `ariaOrientation` property, part of the `ElementInternals` interface, reflects the value of the `aria-orientation` attribute.

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

Used in roles:

* `scrollbar`
* `select`
* `separator`
* `slider`
* `tablist`
* `toolbar`

Inherited into roles:

* `listbox`
* `menu`
* `menubar`
* `radiogroup`
* `tree`
* `treegrid`
Specifications
--------------

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

See Also
--------

* Understanding WCAG: Keyboard


aria-describedby - Accessibility

aria-describedby
================

The global `aria-describedby` attribute identifies the element (or elements) that describes the element on which the attribute is set.

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

The `aria-describedby` attribute lists the `id`s of the elements that describe the object. It is used to establish a relationship between widgets or groups and the text that describes them.

The `aria-describedby` attribute is not limited to form controls. It can also be used to associate static text with widgets, groups of elements, regions that have a heading, definitions, and more. The `aria-describedby` attribute can be used with semantic HTML elements and with elements that have an ARIA `role`.

The `aria-describedby` attribute is very similar to `aria-labelledby` attribute. While `aria-labelledby` lists the `id`s of the labels or elements that describe the essence of an object, `aria-describedby` lists the `id`s of the descriptions or elements providing more information that the user might need. Both `aria-labelledby` and `aria-describedby` reference other elements to calculate a text alternative, but a label should be concise, while a description is intended to provide more verbose information; a label describes the essence of an object, while a description provides more information that the user might need.

The elements linked via `aria-describedby` don't need to be visible. It is possible to reference an element even if that element is hidden. For example, a form control can have a description that is hidden by default that is revealed on request using a disclosure widget like a "more information" icon. The sighted user clicks on the icon; for assistive technology users the description is referenced from that form field directly with `aria-describedby`.

The `aria-describedby` property is appropriate when the associated content contains descriptions experienced as plain text. If the content contains a large amount of content, useful semantics, or has a complex structure requiring user navigation, use `aria-details`. `aria-details` allows assistive technology users to visit the associated structured content and provides additional navigation commands, making it easier to understand the structure, or to experience the information in smaller pieces.

**Note:** The `aria-describedby` content should only be a text string. If there are important underlying semantics in the content, consider using `aria-details`.

Example
-------

```html
<button aria-describedby="trash-desc">Move to trash</button>
…
<p id="trash-desc">
  Items in the trash will be permanently removed after 30 days.
</p>
```

**Note:** The `aria-describedby` attribute is not designed to reference descriptions from external resources. As its value is one or more `id`s (space-separated if multiple), it must reference elements in the same DOM document.

Values
------

ID reference list

The `id` or space-separated list of element `id`s that describe the current element.

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

Used in **all** roles. Usable in all HTML elements as well.

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

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

See Also
--------

* `<label>`
* `aria-labelledby`
* `aria-description`
* `aria-details`
* Browser and AT support for `aria-describedby`


aria-dropeffect - Accessibility

aria-dropeffect
===============

The global `aria-dropeffect` attribute indicates what functions may be performed when a dragged object is released on the drop target.
Deprecated

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

Deprecated in ARIA 1.1, the `aria-dropeffect` property indicates what functions may be performed when a dragged object is released on the drop target. The global `aria-dropeffect` attribute provides assistive technology users the same information provided via the `DataTransfer.dropEffect` to sited users via the dropeffect icon.

Text selections, images, and links can be dragged by default. Setting the global `draggable="true"` attribute, part of HTML5's Drag and Drop API, with a `dragstart` event handler, means any DOM node can be made draggable as well.

When a drag event occurs, a translucent image is generated of the dragged element which follows the user's pointer during the drag. The default image can be changed to any image with `setDragImage`. Along with the default image identifying the element being dragged, there is a `dataTransfer.dropEffect` property that can be used to control the visual feedback the user is given during a drag-and-drop operation. The `aria-dropeffect` property should be used to provide assistive technology users the same feedback provided to sited users via `dataTransfer.dropEffect` property.

`dropeffect` defines which cursor the browser displays while dragging, and is set on the element on which the element may be dropped. During the drag operation, as the draggable element is dragged over different drop areas, the drag effects—both the `dataTransfer.dropeffect` and the `aria-dropeffect` should be modified to indicate the type of operation that will occur if the dragged element is released.

More than one drop effect may be supported for a given element. Therefore, the value of the `aria-dropeffect` attribute is a space separated list of functions. Functions include `copy`, `execute`, `link`, and `move`. The default is `none`, meaning there is no supported functionality in the application. Setting `aria-dropeffect="popup"` informs assistive technology users that there is a popup menu or dialog of drag operations from which the user can choose.

Including the attribute provides assistive technologies the ability to convey the possible drag options available to the assistive technology user, but doesn't add any actual functionality.

The `aria-dropeffect` property is expected to be replaced by a new feature in a future version of WAI-ARIA and is considered deprecated.

Typically, drop effect functions can only be provided once an object has been grabbed for a drag operation, as the drop effect functions available are dependent on the object being dragged. Therefore, you'll generally add `aria-dropeffect` to all the potential drop targets when the `dragstart` event is fired.

Values
------

The value is a space separated list of possible actions. The following are the valid tokens:

`copy`

A duplicate of the source object will be dropped into the target.

`execute`

A function supported by the drop target is executed, using the drag source as an input.

`link`

A reference or shortcut to the dragged object will be created in the target object.

`move`

The source object will be removed from its current location and dropped into the target.

`none` (default)

No operation can be performed; effectively cancels the drag operation if an attempt is made to drop on this object. Ignored if combined with any other token value; for example, 'none copy' is equivalent to a 'copy' value.

`popup`

There is a popup menu or dialog that allows the user to choose one of the drag operations (copy, move, link, execute) and any other drag functionality, such as cancel.

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

Used in **ALL** roles.

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

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

See Also
--------

* `aria-grabbed`
* HTML global `draggable` attribute
* HTML Drag and Drop API
* `dataTransfer`
* `DataTransfer.dropEffect`
* `dragstart`


aria-controls - Accessibility

aria-controls
=============

The global `aria-controls` property identifies the element (or elements) whose contents or presence are controlled by the element on which this attribute is set.

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

When an interactive widget or element, be it a combobox, tab, button, etc., is used to adjust or modify another element or component in a document or application, the `aria-controls` attribute can be used to programmatically associate the corresponding element or elements the controlling element. The `aria-controls` attribute identifies the element (or elements) whose contents or presence are controlled by the element on which the attribute is set, regardless of what type of interaction initiates the impacted behavior.

A combobox element has `aria-controls` set to a value that refers to the element that serves as the popup. The `aria-controls` only needs to be set when the popup is visible, but it is valid and easier to program to reference an element that is not visible.

Other examples of controls include:

* The button parts of an accordion widget that toggle the visibility of their associated panel content. Each button may have an `aria-controls` specified, referencing the ID of the element containing the content associated with the invoking control.
* An element with a role of `scrollbar`: the scrollbar requires an `aria-controls` attribute referencing the ID of the element it controls.
* A group of tabs that each display a different tab panel: each element with `role="tab"` has an `aria-controls` attribute referencing its associated `tabpanel`.
Example
-------

In this tabs example, each tab controls one tabpanel:

```html
<div class="tab-interface">
  <div role="tablist" aria-label="Sample Tabs">
    <span
 role="tab"
 aria-selected="true"
 aria-controls="panel-1"
 id="tab-1"
 tabindex="0">
      First Tab
    </span>
    <span
 role="tab"
 aria-selected="false"
 aria-controls="panel-2"
 id="tab-2"
 tabindex="-1">
      Second Tab
    </span>
    <span
 role="tab"
 aria-selected="false"
 aria-controls="panel-3"
 id="tab-3"
 tabindex="-1">
      Third Tab
    </span>
  </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"
 class="display-none">
    <p>Content for the second panel</p>
  </div>
  <div
 id="panel-3"
 role="tabpanel"
 tabindex="0"
 aria-labelledby="tab-3"
 class="display-none">
    <p>Content for the third panel</p>
  </div>
</div>
```

**Note:** ARIA only modifies the accessibility tree for an element, identifying how assistive technology can present the content to users. ARIA doesn't change any implicit functionality or styling.

Values
------

`id` list

A space-separated list of one or more ID values referencing the elements being controlled by the current element

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

`Element.ariaBusy`

The `ariaControls` property, part of each element's interface, reflects the value of the `aria-controls` attribute, which indicates whether an element is being modified.

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

Used in **ALL** roles.

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

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

See Also
--------

* `aria-owns`


aria-required - Accessibility

aria-required
=============

The `aria-required` attribute indicates that user input is required on the element before a form may be submitted.

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

When a semantic HTML `<input>`, `<select>`, or `<textarea>` must have a value, it should have the `required` attribute applied to it. The HTML `required` attribute disables submitting the form unless the required form controls have valid values, while ensuring those navigating with the aid of assistive technologies understand which semantic form controls need valid content.

When form controls are created using non-semantic elements, such as a `<div>` with a role of `checkbox`, the `aria-required` attribute should be included, with a value of `true`, to indicate to assistive technologies that user input is required on the element for the form to be submittable. The `aria-required` attribute can be used with HTML form elements; it is not limited to elements that have an ARIA role assigned.

Similar to the HTML `required` attribute set on semantic HTML form controls, the `aria-required` attribute explicitly conveys to assistive technologies that the element is required before a form may be submitted. The `required` attribute on a semantic HTML form control will prevent the form control from being submitted if no value is present — providing native error messaging in some browsers if a required value is invalid when the user attempts to submit the form. The `aria-required` attribute, like all ARIA states and properties, has no impact on element functionality. Functionality and behavior must be added in with JavaScript.

**Note:** ARIA only modifies the accessibility tree, modifying how assistive technology presents content to users. ARIA does not change anything about an element's function or behavior. When not using semantic HTML elements for their intended purpose and default functionality, you must use JavaScript to manage behavior, focus, and ARIA states.

The CSS `:required` and `:optional` pseudoclasses match `<input>`, `<select>`, and `<textarea>` elements based on whether they are required or optional, respectively. When using non-semantic elements as form controls, you don't get this CSS pseudoclass selector benefit. You can, however, use attribute selectors if the attribute is present: `[aria-required="true"]` or `[aria-required="false"]`.

If a form contains both required and optional form elements, the required elements should be indicated visually using a treatment that does not rely solely on color to convey meaning. Typically, descriptive text and/or an icon are used.

**Note:** Which elements are required should be apparent to all users. Ensure the visual presentation indicates the form control is required in a consistent, visible manner, remembering that color is not enough to convey information.

Examples
--------

The attribute should be added to the form-control role. If the user needs to fill in an email address `textbox`, include `aria-required="true"` on the textbox.

```html
<div id="tbLabel">Email Address *</div>
<div
 role="textbox"
 contenteditable
 aria-labelledby="tblabel"
 aria-required="true"
 id="email1"></div>
```

**Note:** If the field's label already contains the word "required", it is recommended to leave out the `aria-required` attribute. This avoids that screen readers read out the term "required" twice.

In this example, JavaScript must be used to prevent the containing form from being submitted if the textbox has no content.

This could be written semantically, without the need for JavaScript:

```html
<label for="email1">Email Address (required)</label>
<input type="email" id="email1" required />
```

Values
------

`true`

The element requires a value or must be checked for the form to be submittable.

`false`

The element is not required.

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

`Element.ariaRequired`

The `ariaRequired` property, part of the `Element` interface, reflects the value of the `aria-required` attribute.

`ElementInternals.ariaRequired`

The `ariaRequired` property, part of the `ElementInternals` interface, reflects the value of the `aria-required` attribute.

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

Used in roles:

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

Inherits into roles:

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

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

See Also
--------

* HTML `required` attribute
* `:optional` pseudoclass
* `:required` pseudoclass
* `aria-invalid` attribute
* MDN Understanding WCAG, Guideline 3.3 explanations
* Understanding Success Criterion 3.3.2 | W3C Understanding WCAG 2.0


aria-autocomplete - Accessibility

aria-autocomplete
=================

The `aria-autocomplete` attribute indicates whether inputting text could trigger display of one or more predictions of the user's intended value for a `combobox`, `searchbox`, or `textbox` and specifies how predictions will be presented if they are made.

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

Autocompletion is user interface feature wherein inline suggestions are made as a user types in an input. Suggested text for completing the value of the field dynamically appears in the field after the input cursor, and the suggested value becomes the value if the user performs an action, such as tabbing, that causes focus to leave the field.

The `aria-autocomplete` property describes the type of autocompletion interaction model a textbox, searchbox, or combobox will use when dynamically helping users complete text input. It distinguishes between two models: the **inline** model (`aria-autocomplete="inline"`), which presents a single predicted value and the **list** model (`aria-autocomplete="list"`), which presents a collection of possible values in a separate element that pops up next to or below the text input, similar to a `<datalist>`. A third value, `aria-autocomplete="both"` is for when the interface will present a list while also including a predicted value. The default is `none`, meaning the textbox, searchbox, or combobox will not provide an auto complete value.

The `aria-autocomplete` property only describes the type of predictive behavior for an input element for assistive technologies; it doesn't provide the functionality. The actual autocompletion should be provided using HTML attributes or JavaScript.

If the suggested autocomplete value provides suggested values that aren't dependent on the input provided by the user, consider omitting autocomplete for everyone. For example, a searchbox input displaying unfiltered recent search terms may be helpful to a marketing team on an e-commerce site, but likely isn't helpful for the screen reader user. When it is best to not specify a value for `aria-autocomplete` or to set the value to the `none` default, likely your non-assistive technology users also don't need the experience.

When implementing autocomplete functionality, ensure the suggested portion of the value is presented as selected text to enable distinguishing between a user's input and the suggestion. Make sure that when the suggested value is not the desired value, users can easily delete the suggestion or replace it by continuing to type.

When implementing a list of values, DOM focus should remain on the text input while the suggestion list is displayed.

* include `aria-controls` with the value of the id of the suggested list of values.
* include `aria-haspopup` matching the role of the element that contains the collection of suggested values.
* manage focus, if required, including using `aria-activedescendant` if the collection container supports.
* use the `aria-expanded` state on the element with role `combobox` to communicate that the list is displayed.

If an autocomplete list value is automatically accepted when the field loses focus, the list must be contained in a role that supports `aria-activedescendant`, with the value of `aria-activedescendant` on the input field dynamically adjusted to refer to the element containing the selected suggestion.

Values
------

`none` (default)

When a user is providing input, no automatic suggestion is displayed.

`inline`

`aria-autocomplete="inline"` text suggesting one way to complete the provided input may be dynamically inserted after the caret.

`list`

`aria-autocomplete="list"` When a user is providing input, an element containing a collection of values that could complete the provided input may be displayed.

`both`

`aria-autocomplete="both"` an input to offer both models at the same time. When a user is providing input, an element containing a collection of values that could complete the provided input may be displayed. If displayed, one value in the collection is automatically selected, and the text needed to complete the automatically selected value appears after the caret in the input.

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

Used in roles:

* `combobox` role
* `textbox` role
* inherits from `searchbox` role
Specifications
--------------

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

See Also
--------

* `combobox` role
* `textbox` role
* `searchbox` role
* `<datalist>` element and the `<input> list` attribute
* `aria-controls` attribute
* `aria-haspopup` attribute
* `aria-activedescendant` attribute
* `aria-expanded` attribute
* Editable Combobox With Both List and Inline Autocomplete Example
* Event.ariaAutoComplete


aria-multiline - Accessibility

aria-multiline
==============

The `aria-multiline` attribute indicates whether a `textbox` accepts multiple lines of input or only a single line.

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

The default behavior of the `Enter` or `Return` key differs between single-line and multi-line text fields. When user focus is in a single-line `<input type="text">`, an `Enter` or `Return` keystroke usually submits the form.

When user focus is in a multi-line `<textarea>`, the keystroke inserts a line break. Only relevant for elements with the `textbox` role set, the `aria-multiline` attribute indicates to assistive technologies whether that text box accepts multiple lines of input or only a single line, setting expectations as to what type of data to enter and what those keystroke will do.

**Note:** Where possible, use the HTML `<input>` or the `<textarea>`, as these have built in semantics and behaviors, do not require ARIA attributes or scripting, and have keyboard support built in.

If the `aria-multiline="true"` is set, it means the textbox widget will accept line breaks within the input, similar to the HTML `<textarea>`. Elements with a role of `textbox` that do not have the attribute, or with the value set to `false`, are simple text box.

Be aware of focus and keystrokes when designing text boxes. ARIA only modifies the accessibility tree and therefore how assistive technology presents the textbox to your users. ARIA doesn't change anything about an element's default function or behavior. When not using semantic HTML elements for their intended purpose and default functionality, you must use JavaScript to manage behavior and functionality, including responding to keystroke events.

Values
------

`true`

The text box accepts multiple lines of input.

`false`

The text box only accepts a single line of input.

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

`Element.ariaMultiLine`

The `ariaMultiLine` property, part of the `Element` interface, reflects the value of the `aria-multiline` attribute.

`ElementInternals.ariaMultiLine`

The `ariaMultiLine` property, part of the `ElementInternals` interface, reflects the value of the `aria-multiline` attribute.

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

Used in roles:

* `textbox`

Inherits into roles:

* `searchbox`
Specifications
--------------

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

See Also
--------

* ARIA `textbox` role
* ARIA `searchbox` role


aria-roledescription - Accessibility

aria-roledescription
====================

The `aria-roledescription` attribute defines a human-readable, author-localized description for the role of an element.

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

Some assistive technologies (AT), such as screen readers, present the role of an element as part of the user experience. The `aria-roledescription` attribute provides a way to define a different human-readable name to be presented by AT as the role of an element.

**Note:** Only use aria-roledescription to clarify the purpose of non-interactive container roles and to provide a more specific description to a widget.

Users depend on the presentation of known role name to understand the purpose of the element and, if it is a widget, how to interact with it. So, only use `aria-roledescription` to clarify the purpose of non-interactive container roles like `group` or `region` and to provide a more specific description to a widget.

The `aria-roledescription` property overrides how ATs localize and express the name of a role. When you override a role name the user understands, you can potentially negatively impact a users' ability to understand and interact with an element.

Avoid using the `aria-roledescription` attribute. When a use case appears special worthy of a unique roledescription, the interactions can often times be broken down into smaller pieces that have relevant roles.

When there are no semantic or ARIA widget roles that correspond to the interaction model of your widget, use `role="application"`, provide an `aria-roledescription` with a human-readable, author-localized customized role name, and use `aria-describedby` to provide user instructions.

ATs may customize and localize the names of ARIA roles. If you are using `aria-roledescription` to change how the role name is presented to the user, remember to handle localization. The value should be translated when a page is localized.

Changing how the role is presented to the user has no impact on the functionality of the element. For example, if an element has a role of `region` or `button` when AT provides functions for navigating to the next region or button, if you set the `aria-roledescription` to `continent` and `escape` respectively, the AT will still allow those functions to navigate to regions and buttons.

Again, avoid using `aria-roledescription`. In this example, `escape` has no relevant meaning to the user, but `button` with "escape" as a label does.

When using `aria-roledescription`, also ensure that the element to which it is applied has a valid ARIA `role` or has implicit role semantics and that the value itself is not empty and contains more than just whitespace characters.

The `aria-roledescription` is required when using `aria-brailleroledescription`. Note that, in general, `aria-brailleroledescription` should only be used in rare cases when a `aria-roledescription` is excessively verbose when rendered in Braille.

Examples
--------

The following example shows the use of `aria-roledescription` to indicate that a non-interactive container is a "slide" in a web-based presentation application.

```html
<div
 role="article"
 aria-roledescription="slide"
 id="slide"
 aria-labelledby="slideheading">
  <h1 id="slideheading">Quarterly Report</h1>
  <!-- remaining slide contents -->
</div>
```

In the previous examples, a screen reader user may hear "Quarterly Report, slide" rather than the less precise "Quarterly Report, article".

Values
------

`<string>`

A non-empty string, an unconstrained value type, containing more than just white space.

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

`Element.ariaRoleDescription`

The `ariaRoleDescription` property, part of the `Element` interface, reflects the value of the `aria-roledescription` attribute.

`ElementInternals.ariaRoleDescription`

The `ariaRoleDescription` property, part of the `ElementInternals` interface, reflects the value of the `aria-roledescription` attribute.

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

Supported by all roles and by all base markup elements except for `role="generic"`.

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

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

See Also
--------

* ARIA roles


aria-labelledby - Accessibility

aria-labelledby
===============

The `aria-labelledby` attribute identifies the element (or elements) that labels the element it is applied to.

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

The `aria-labelledby` property enables authors to reference other elements on the page to define an accessible name. This is useful when using elements that don't have native support for associating elements to provide an accessible name.

Some elements get their accessible name from their inner content. For example, the accessible name for a `<button>`, `<a>`, or `<td>` comes from the text between the opening and closing tags. Other elements, such as form `<textarea>`, `<fieldset>`, and `<table>` get their accessible name from the content of associated elements; for these elements, the accessible name comes from the `<label>` with a `for` attribute, `<legend>`, and `<caption>` respectively.

All interactive elements must have an accessible name. `aria-labelledby` can be used to reference another element to define its accessible name, when an element's accessible name needs to use content from elsewhere in the DOM.

If there is no content that can be referenced to create an accessible name, the `aria-label` attribute should be used instead.

The purpose of `aria-labelledby` is the same as that of `aria-label`. It provides the user with a recognizable, accessible name for an interactive element. If an element has both attributes set, `aria-labelledby` will be used. `aria-labelledby` takes precedence over all other methods of providing an accessible name, including `aria-label`, `<label>`, and the element's inner text.

The `aria-labelledby` and `aria-describedby` attributes both reference other elements to calculate text alternatives. `aria-labelledby` should reference brief text that provides the element with an accessible name. `aria-describedby` is used to reference longer content that provides a description. If there is no element in the DOM that provides a brief label appropriate for an accessible name for an interactive element, use `aria-label` to define the accessible name for an interactive element.

**Note:** While in U.S. English the attribute would be assumed to be spelled "labeledby", the "labelledby" spelling has been established and is the spelling used in accessibility APIs.

The following example uses `aria-labelledby` to provide an accessible name for a checkbox input by using the text content of a sibling element:

```html
<span
 role="checkbox"
 aria-checked="false"
 tabindex="0"
 aria-labelledby="tac"></span>
<span id="tac">I agree to the Terms and Conditions.</span>
```

Note that while using `aria-labelledby` is similar in this situation to using an HTML `<label>` element with the `for` attribute, there are some very important differences. The `aria-labelledby` attribute only defines the accessible name. It doesn't provide any of `<label>`'s other functionality, such as making clicking on the labeling element activate the input it is associated with. That has to be added back in with JavaScript.

Fortunately, the HTML `<input>` with `type="checkbox"` works with native `<label>`. When feasible, use the following:

```html
<label for="tac">
  <input id="tac" type="checkbox" name="terms-and-conditions" />
  I agree to the Terms and Conditions.
</label>
<p><a href="tac.html">Read our Terms and Conditions</a>.</p>
```

### Benefits (and drawbacks)

1. The `aria-labelledby` property has the highest precedence when browsers calculate accessible names. Be aware that it overrides other methods of naming the element, including `aria-label`, other naming attributes, and even the element's contents.

```html
<button aria-label="Blue" aria-labelledby="color">Red</button>
<span id="color">Yellow</span>
```

In this example, that accessible name is "Yellow".
2. The `aria-labelledby` property takes as value a space-separated id reference list, which means you can combine more than one element into a single accessible name. You can include the `id` of the element itself to reference its own content.

```html
<h2 id="attr" class="article-title">13 ARIA attributes you need to know</h2>
<p>
  There are over 50 ARIA states and properties, but 13 of them stand out…
  <a href="13.html" id="rm13" aria-labelledby="rm13 attr">read more</a>
</p>
```

In this example, the accessible name is "read more 13 ARIA attributes you need to know".
3. The `aria-labelledby` property value order matters. When more than one element is referenced by `aria-labelledby`, the content from each referenced element is combined in the order that they are referenced in the `aria-labelledby` value. Had we written `aria-labelledby="attr rm13">`, the accessible name would have been "13 ARIA attributes you need to know read more".
4. The `aria-labelledby` property ignores repeated `id`s in its value. If an element is referenced more than one time, only the first reference is processed. `aria-labelledby="attr attr rm13 rm13">` is treated as `aria-labelledby="attr rm13">`
5. The `aria-labelledby` property value can include content from elements that aren't even visible. While you should provide assistive technology users with the same content as all other users, you can include content from elements with the HTML `hidden` attribute, CSS `display: none`, and CSS `visibility: hidden` in the calculated name string.
6. The `aria-labelledby` property incorporates the value of input elements. If the value references an `<input>`, the current value of the form control is included in the calculated name string, changing if the value is updated.
7. The `aria-labelledby` property cannot be chained. If an element with `aria-labelledby` references another element that also has `aria-labelledby`, the `aria-labelledby` attribute on the referenced element is ignored.

**Warning:** Because calculating the name of an element with `aria-labelledby` can be complex and reference hidden content, testing with assistive technologies to ensure the expected name is presented to users is very important.

Values
------

ID reference list

Space separated list of one or more ID values referencing the elements that label the current element.

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

Used in almost all roles **except** roles that can not be provided an accessible name by the author.

The `aria-labelledby` attribute is **NOT** supported in:

* `code`
* `caption`
* `deletion`
* `emphasis`
* `generic`
* `insertion`
* `mark`
* `paragraph`
* `presentation` / `none`
* `strong`
* `subscript`
* `superscript`
* `suggestion`
* `term`
* `time`
Specifications
--------------

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

See Also
--------

* HTML `<label>` element
* HTML `<legend>` element
* HTML `<caption>` element
* `aria-label`
* `aria-describedby`


aria-colcount - Accessibility

aria-colcount
=============

The `aria-colcount` attribute defines the total number of columns in a `table`, `grid`, or `treegrid` when not all columns are present in the DOM.

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

Some tables are very large, and it's not possible to show all the columns to the user. Or, it is possible, but having such a wide table would be a bad user experience. Use the `aria-colcount` attribute to let assistive technologies know how many columns the table would have if all columns were present. The value is an integer representing the number of columns that make up the full table. If you don't know the total number of columns a table will have, but know they will not all be in the DOM, use the value -1, so `aria-colcount="-1"`. This value tells the user agent that the current number of columns present in the DOM may not be the actual number of columns in the table.

If all columns in a table are present in the DOM, the `aria-colcount` attribute isn't needed, as browsers automatically calculate the total number of columns. However, if only a portion of the columns is present in the DOM at a given moment, that is when this attribute is helpful and needed.

When using `aria-colcount` when you have a known number of columns, make sure to also use `aria-colindex` to label each column, or, if the columns are contiguous－if it's a group of columns in the original order with no breaks－label each row.

The following example shows a grid with 6 columns, of which columns 1, 2, 5, and 6 are displayed to the user. The total number of columns that make up the table is set as `aria-colcount="6"` on the table itself. As the columns aren't contiguous, every `cell` - in this case `columnheader` and `gridcell` elements - have the `aria-colindex` attribute set.

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

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." If we employ native HTML semantics with `<table>`, `<th>`, `<td>`, etc., the `aria-colcount` attribute is still necessary, but the mark up is not as verbose. When using semantic table header elements and not all columns are in the DOM, the `aria-colcount` must still be used, but the `aria-colindex` attribute only needs to be defined once per column in the column header `<th>`.

```html
<table aria-colcount="6">
  <thead>
    <tr>
      <th aria-colindex="1" scope="col">First name</th>
      <th aria-colindex="2" scope="col">Last name</th>
      <th aria-colindex="5" scope="col">City</th>
      <th aria-colindex="6" scope="col">Zip</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Debra</td>
      <td>Burks</td>
      <td>New York</td>
      <td>14127</td>
    </tr>
    …
  </tbody>
</table>
```

Values
------

`<integer>`

The number of columns in the full table

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

Used in roles:

* `table`

Inherits into roles:

* `grid`
* `treegrid`
Specifications
--------------

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

See Also
--------

* `aria-colindex`


aria-relevant - Accessibility

aria-relevant
=============

Used in ARIA live regions, the global `aria-relevant` attribute indicates what notifications the user agent will trigger when the accessibility tree within a live region is modified.

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

ARIA live regions are areas of a web page that are updated when user's attention may be elsewhere. When an update is outside of the user's keyboard focus, assistive technologies such as screen readers use a live region area to report updates to the user.

Examples of live regions include news marquees, stock tickers, chat windows, and score boards. These update without user interaction. Some updates are important for the user to know about. They're relevant. Others are not. The `aria-relevant` is used to describe what types of changes have occurred to an `aria-live` region, and which are relevant and should be announced.

The value is a space-separated list of change types, including `additions`, `removals`, and `text`, with a shorthand `all` meaning all three.

When `aria-relevant` is not defined, the value is inherited from the nearest ancestor with a defined value. Inherited values are not additive; the value provided on a descendant element completely overrides any inherited value from an ancestor element. When a live region doesn't have an `aria-relevant` attribute set and has no ancestor with it set, it defaults to `additions text`, because generally text modifications and node additions are relevant, but node removals are not.

While not a supported value, if the value of `none` makes the most sense, it should not be a live region.

The values of `removals` and `all` should be used sparingly. For example, when a goal happens in the World Cup, the new score (the addition) is important, the old value (the removal) is not. Assistive technologies only need to be informed of content removal when its removal represents an important change, such as a when a player is taken out of the game.

Values
------

`additions`

Element nodes are added to the accessibility tree within the live region.

`all`

Shorthand for `additions removals text`.

`removals`

Text content, a text alternative, or an element node within the live region is removed from the accessibility tree.

`text`

Text content or a text alternative is added to any descendant in the accessibility tree of the live region.

`additions text` (default)

Element nodes are added to the accessibility tree within the live region AND text content or a text alternative is added to any descendant in the accessibility tree of the live region.

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

`Element.ariaRelevant`

The `ariaRelevant` property, part of the `Element` interface, reflects the value of the `aria-relevant` attribute.

`ElementInternals.ariaRelevant`

The `ariaRelevant` property, part of the `ElementInternals` interface, reflects the value of the `aria-relevant` attribute.

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

Used in **ALL** roles.

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

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

See Also
--------

* `aria-atomic`
* `aria-live`
* `aria-busy`
* ARIA live regions


aria-live - Accessibility

aria-live
=========

The global `aria-live` attribute indicates that an element will be updated, and describes the types of updates the user agents, assistive technologies, and user can expect from the live region.

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

When content changes after initial load, assistive technology (AT) users may not "see" the changes. Some changes are important. Others are not. The `aria-live` attribute enables developers to inform the user of updates and choose, based on importance and urgency, whether to immediately, proactively, or passively inform AT users of changes to the content.

If a section of the screen updates, if it's styled in a way to be noticeable, most sighted users will generally notice live updates. Screen readers, on the other hand, only focus on one part of the page at a time; and that part may not be where the update is. The `aria-live` attribute provides a way for developers to announce such changes to AT based on event triggers set by the developer rather than by user initiated actions so they are made aware that the content has changed.

```html
<div id="announce" aria-live="polite"></div>
```

The `aria-live` attribute is set on an **empty** element. When an update to the page occurs, the empty element with that `aria-live` attribute should be updated with a brief announcement informing the user an update has been made.

```html
<div id="announce" aria-live="polite">
  <p>This message is announced.</p>
</div>
```

When the accessibility API recognizes a change to the live region above, it will announce the contents of that live region based on the value of the attribute. The element is **not** given focus.

If you want all the contents of the live region to be read, use the `aria-atomic`. Use `aria-relevant` to define only the sections of an update that need to be reread to the user. Use `aria-busy` to prevent announcements while updates are still being made.

### Choosing the `aria-live` value

As some assistive technology users can't "see" live updates, the `aria-live` attribute is used to define what updated information the user should be:

* Made aware of immediately,
* Informed about if the opportunity avails itself, and
* Proactively informed about but can learn when they choose to focus on the updated area.

`aria-live`'s value describes the types of updates the user agents, assistive technologies, and user can expect from the live region, and is used to express degrees of importance.

When `aria-live`'s attribute is set to `polite`, assistive technologies will notify users of updates but generally do not interrupt the current task, with the updates having a low priority. When set to `assertive`, assistive technologies immediately notify the user, potentially clearing the speech queue of previous updates.

Screen readers buffer content when the page is loaded. Because of this, content added after the initial accessibility tree is built may not be noticed as AT users start consuming content before dynamic widgets are populated—users may not know about the page or view content updating as widgets finish loading. In this situation you can let users know the page has been updated by setting `aria-live="polite"`.

Fully populated pages may have updates too. Examples are content like real-time sports scores, news crawlers, and stock market tickers. Unless these kinds of updates are the main function of the page, you likely do not want to inform the user every time it updates, but do want to inform them the widget does get updated. Here, you would set `aria-live="off"`. In these scenarios there is no reason to inform the user of updates unless they are focused on the live region.

Some live updates are important and time sensitive. For example, if you are selling concert tickets and the user has a limited time to make the purchase, you don't want to wait until a lull in activity to tell them their time is almost up (or already over). When being informed as soon as possible is necessary, set `aria-live="assertive"`. If the updated information is an `alert`, the `aria-live` attribute is not needed.

In this time-limit scenario, to be accessible, you need to also provide a way for users to extend the time available or turn the timer off completely.

### Using `aria-live`

A live region includes the element and all its descendants. When not set on updating content, `aria-live`'s value comes from the nearest ancestor with a valid `aria-live` attribute value set. When set to `off`, or when the attribute is omitted altogether on the updated element and all the ancestor nodes in the DOM tree, the user is not informed. Users will still be able to hear the updates if they navigate to the live region, however.

**Warning:** Because an interruption may disorient users or cause them to not complete their current task, don't use the `assertive` value unless the interruption is imperative.

Values
------

`assertive`

Indicates that updates to the region have the highest priority and should be presented to the user immediately.

`off` (default)

Indicates that updates to the region should **not** be presented to the user unless the user is currently focused on that region.

`polite`

Indicates that updates to the region should be presented at the next graceful opportunity, such as at the end of speaking the current sentence or when the user pauses typing.

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

`Element.ariaLive`

The `ariaLive` property, part of the `Element` interface, reflects the value of the `aria-live` attribute.

`ElementInternals.aria-live`

The `ariaLive` property, part of the `ElementInternals` interface, reflects the value of the `aria-live` attribute.

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

Used in **ALL** roles.

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

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

See Also
--------

* `aria-atomic`
* `aria-relevant`
* `aria-busy`
* `alert` role


aria-disabled - Accessibility

aria-disabled
=============

The `aria-disabled` state indicates that the element is perceivable but disabled, so it is not editable or otherwise operable.

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

The `aria-disabled` attribute, when set to `true`, indicates that the element upon which it is set and all of its focusable descendants are meant to be in the disabled state. This declaration will inform people using assistive technologies, such as screen readers, that such elements are not meant to be editable or otherwise operable.

Unlike HTML's `disabled` Boolean attribute, which will communicate a form control as semantically being disabled, change its styling to reflect its state and suppress all functionality along with disallowing the element's value from participating in form submission, the `aria-disabled="true"` **only** semantically exposes these elements as being disabled. Web developers must manually ensure such elements have their functionality suppressed when exposed to the disabled state.

When needing to disable native HTML form controls, developers will need to specify the `disabled` attribute, as it provides all of the generally expected features of disabling a control by default. However, there can be instances where elements need to be exposed as disabled, but are still available for users to find when navigating via the `Tab` key. Doing so can improve their discoverability as they will not be removed from the focus order of the web page, as `aria-disabled` does not change the focusability of such elements, nor will the elements be dimmed by default browser styling, making them easier to read. Some examples of where this may be useful include:

* The header button element associated with non-collapsible accordion panel,
* A button which is important to keep in the page's focus order, but its action is presently unavailable - such as submitting a form,
* Temporarily inactive items in a menu widget that would otherwise be skipped over via standard keyboard navigation.

In each of these cases, one may want users to find these elements through standard keyboard navigation, though the functionality of that control is removed or "disabled". Developers will still need to use JavaScript to fully disable the functionality of the element while also changing the appearance of the element so sighted users know it is disabled.

**Note:** The state of being disabled applies to the element with `aria-disabled="true"` and all of its focusable descendants. Take care when using this attribute on container elements. Particularly in the case where a container may have both form controls and links - where the intent may be to expose the form controls as being in the disabled state, but **not** to communicate the links as being "disabled".

Another reason to use the `aria-disabled` attribute over the HTML `disabled` attribute is if you have created custom controls which need to be marked as disabled, but are not using an element that allows for the `disabled` attribute. For instance, in the following snippet a `<div>` was used to create a custom button which needs to be marked as disabled. However, the `<div>` element does not expect, nor respect the `disabled` attribute - even if it were to be given a `role="button"` to change its exposed ARIA role. The `aria-disabled` attribute is required to disable such custom controls.

```html
<div role="button" aria-disabled="true" tabindex="-1">Edit</div>
```

Similarly to needing to use JavaScript to ensure an element with `aria-disabled="true"` is not functional, the element will also need styling adjustments. In contrast to the HTML `disabled` attribute, where specifying it provides `:disabled` user-agent styles to be applied, adding `aria-disabled="true"` doesn't. The element can be styled with the attribute selector `[aria-disabled="true"]`.

```css
[aria-disabled="true"] {
  opacity: 0.5;
}
```

If you are purposefully using the `aria-disabled` attribute to allow for a form control to remain in the page's keyboard focus order, particularly if the element represents important content that all users should be able to perceive, then you may need to use styling that still passes color contrast requirements. For instance, a disabled button/heading that introduces a non-collapsible accordion panel is content that still needs to be legible.

```css
@media (forced-colors: active) {
  [aria-disabled="true"] {
    border-color: GrayText;
    color: GrayText;
  }
}
```

The `forced-colors` media query detects if the user agent has enabled a forced colors mode; if so, the text and border colors are both set to the system color `greyText`.

Another thing to keep in mind, when using `aria-disabled` over the native HTML attribute, is that the ARIA attribute will require the manual styling necessary to visually communicate the element as disabled in Windows High Contrast Mode.

**Note:** If you are using CSS's `pointer-events: none;` to make an element non-clickable, make sure you disable interactivity with JavaScript as well. `pointer-events: none;` prevents mouse clicks, but does not prevent the element from being activated via the keyboard.

```js
function onClick(event) {
  event.preventDefault();
}

function toggleDisabled(element, status, update) {
  if (status) {
    //element.input.disabled = false;
    element.setAttribute("aria-disabled", "false");
    update.textContent = "The element is now enabled.";
    element.addEventListener("click", onClick);
  } else {
    //element.input.disabled = true;
    element.setAttribute("aria-disabled", "true");
    update.textContent = "The element is now disabled.";
    element.removeEventListener("click", onClick);
  }
}
```

When toggling from `aria-disabled="true"` to `"false"`, use JavaScript to:

1. Toggle the value to `false` (or remove the attribute entirely),
2. Enable the element, and
3. Let the user know the control is now enabled.

If you used just CSS to style the disabled state using an attribute selector, the selector will no longer match and the disabled styling will no longer be in effect.

Values
------

`true`

The element is disabled

`false`

The element is not disabled

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

`Element.ariaDisabled`

The `ariaDisabled` property, part of the `Element` interface, reflects the value of the `aria-disabled` attribute, which indicates that the element is perceivable but disabled, so it is not editable or otherwise operable.

`ElementInternals.ariaDisabled`

The `ariaDisabled` property of the `ElementInternals` interface reflects the value of the `aria-disabled` attribute.

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

Used in roles:

* `application`
* `button`
* `composite`
* `gridcell`
* `group`
* `input`
* `link`
* `menuitem`
* `scrollbar`
* `separator`
* `tab`

Inherits into roles:

* `checkbox`
* `columnheader`
* `combobox`
* `grid`
* `listbox`
* `menu`
* `menubar`
* `menuitemcheckbox`
* `menuitemradio`
* `option`
* `radio`
* `radiogroup`
* `row`
* `rowheader`
* `searchbox`
* `select`
* `slider`
* `spinbutton`
* `switch`
* `tablist`
* `textbox`
* `toolbar`
* `tree`
* `treegrid`
* `treeitem`
Specifications
--------------

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

See Also
--------

* Making disabled buttons more inclusive by Sandrina Pereira
* Styling for Windows high contrast with new standards for forced colors
* disabled
* `Element.ariaDisabled`
* `ElementInternals.ariaDisabled`
* `aria-hidden`
* `aria-readonly`


aria-selected - Accessibility

aria-selected
=============

The `aria-selected` attribute indicates the current "selected" state of various widgets.

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

The `aria-selected` attribute indicates the current "selected" state for `gridcell`, `option`, `row` and `tab` roles.

This attribute is used to indicate which elements within single-selection and multiple-selection composite widgets are selected. If more than one element is selectable at a time, include `aria-multiselectable="true"` on the grid, listbox, tablist, or other owning role, while including `aria-selected` only on the selectable cells, options, and tabs.

For other roles, the currently selected state is set with `aria-current`, or possibly `aria-checked` or `aria-pressed`, depending on the role.

Widgets that support both `aria-selected` and `aria-current` at the same time have different meanings for each. For example, `aria-current="page"` can be used in a navigation tree to indicate which page is currently displayed, while `aria-selected="true"` indicates which page will be displayed if the user activates the `treeitem`.

### Grid

Setting `aria-selected="false"` on a focusable gridcell indicates the cell is selectable. If the grid allows more than one gridcell to be selected at a time, set `aria-multiselectable="true"` on the element with role `grid`. Setting `aria-selected` on a column or row header gridcell does not propagate the state to other cells in the column or row.

### Option

Both `aria-selected` and `aria-checked` are valid for `option`. Some user interfaces indicate selection with `aria-selected` in single-select list boxes and with `aria-checked` in multi-select list boxes.

Don't specify both `aria-selected` and `aria-checked` on `option` elements contained by the same `listbox` unless the meaning and purpose of `aria-selected` is different from the meaning and purpose of aria-checked in the user interface, the meaning and purpose of each state apparent, and the UI provides separate methods for controlling each state.

### Row

The `aria-selected` attribute is supported on `row` but not `column`. If a grid supports selection, when a cell or row is selected, the selected element has `aria-selected="true"` set.

If the grid supports column selection and a column is selected, all cells in the column have `aria-selected` set to `true`.

### Tab

In a tablist, `aria-selected` is used on a tab to indicate the currently-displayed `tabpanel`.

The selected `tab` in a `tablist` should have the attribute `aria-selected="true"` set. All inactive tabs in the tablist should have `aria-selected="false"` set. Setting the state only impacts the accessibility tree: make sure to style the active tab in a way that visual indicates it's selected state. The default value for `aria-selected` on a `tab` role is `false`.

If more than one tab is selectable at a time, include `aria-multiselectable` on the `tablist`.

Examples
--------

In this `tablist` example, the first `tab` is selected:

```html
<div class="tab-interface">
  <div role="tablist" aria-label="Sample Tabs">
    <span
 role="tab"
 aria-selected="true"
 aria-controls="panel-1"
 id="tab-1"
 tabindex="0">
      First Tab
    </span>
    <span
 role="tab"
 aria-selected="false"
 aria-controls="panel-2"
 id="tab-2"
 tabindex="-1">
      Second Tab
    </span>
    <span
 role="tab"
 aria-selected="false"
 aria-controls="panel-3"
 id="tab-3"
 tabindex="-1">
      Third Tab
    </span>
  </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>
```

**Note:** ARIA only modifies the accessibility tree for an element and how assistive technology presents the content to users. ARIA doesn't change anything about an element's function or behavior.

Values
------

`true`

The selectable element is selected.

`false`

The selectable element is not selected. Implicit default for `tab`.

`undefined` (default)

The element is not selectable.

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

`Element.ariaSelected`

The `ariaSelected` property, part of the `Element` interface, reflects the value of the `aria-selected` attribute.

`ElementInternals.ariaSelected`

The `ariaSelected` property, part of the `ElementInternals` interface, reflects the value of the `aria-selected` attribute.

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

Used in roles:

* `gridcell`
* `option`
* `row`
* `tab`

Inherited into roles:

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

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

See Also
--------

* `aria-pressed`
* `aria-checked`


aria-current - Accessibility

aria-current
============

A non-null `aria-current` state on an element indicates that this element represents the current item within a container or set of related elements.

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

When you have a group of related elements, such as several links in a breadcrumb or steps in a multi-step flow, with one element in the group styled differently from the others to indicate to the sighted user that this is the current element within its group, the `aria-current` should be used to inform the assistive technology user what has been indicated via styling.

In a breadcrumb list, when a link within a set of pagination links is styled to indicate the user is currently on that page, `aria-current="page"` should be set on that link. In a multi step based process with a step indicator such as a multi-page survey or a multi step checkout or registration process, when the current step icon is visually different to represent that it is the current step, that icon's container should have `aria-current="step"` for assistive technology users who may not be able to "see" the visual difference.

The `aria-current` attribute indicates the element on which it is set, to a value other than `false`, represents the current item within a container or set of related elements. Only mark one element in a set of elements as current with `aria-current`.

The `aria-current` attribute accepts a limited list of values including `page`, `step`, `location`, `date`, `time`, `true`, and `false`. Any non-null string value not included in this list of enumerated values is treated as if `aria-current="true"` were set, not the default `false` value. If the attribute is not present, is an empty string, is present with no value, or is set to `aria-current="false"` it is not exposed to the user.

When something is selected rather than current, such as a `tab` in a `tablist`, use `aria-selected` to indicate the currently-displayed tabpanel.

**Note:** Don't use `aria-current` as a substitute for `aria-selected` in `gridcell`, `option`, `row` or `tab`.

Example
-------

The breadcrumb for the "current page" should have `aria-current="page"` set on it.

```html
<nav aria-label="Breadcrumb" class="breadcrumb">
  <ol>
    <li>
      <a href="../../../../../">Web technology for developers</a>
    </li>
    <li>
      <a href="../../../../">Accessibility</a>
    </li>
    <li>
      <a href="../../../">ARIA</a>
    </li>
    <li>
      <a href="../../">ARIA States and Properties</a>
    </li>
    <li>
      <a href="./" aria-current="page">ARIA: `aria-current` attribute</a>
    </li>
  </ol>
</nav>
```

If the element representing the current page in the breadcrumb was not a link, the `aria-current` is optional.

Values
------

`page`

Represents the current page within a set of pages such as the link to the current document in a breadcrumb.

`step`

Represents the current step within a process such as the current step in an enumerated multi step checkout flow .

`location`

Represents the current location within an environment or context such as the image that is visually highlighted as the current component of a flow chart.

`date`

Represents the current date within a collection of dates such as the current date within a calendar.

`time`

Represents the current time within a set of times such as the current time within a timetable.

`true`

Represents the current item within a set.

`false` (default)

Does not represent the current item within a set.

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

`Element.ariaCurrent`

The `ariaCurrent` property, part of the `Element` interface, reflects the value of the `aria-current` attribute.

`ElementInternals.ariaCurrent`

The `ariaCurrent` property of the `ElementInternals` interface reflects the value of the `aria-current` attribute.

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

Usable in all roles; except in for elements with the role of `gridcell`, `option`, `row` and `tab` where `aria-selected` should be used

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

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

See Also
--------

* `aria-selected`
* `:local-link`
* Breadcrumb navigation with `aria-current`


aria-grabbed - Accessibility

aria-grabbed
============

The `aria-grabbed` state indicates an element's "grabbed" state in a drag-and-drop operation.
Deprecated

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

Text selections, images, and links can be dragged by default. Setting the global `draggable="true"` attribute, part of HTML5's Drag and Drop API, with a `dragstart` event handler, means any DOM node can be made draggable as well.

The `aria-grabbed` attribute was used to indicate if an element is in a "grabbed" state in a drag-and-drop operation with `aria-grabbed="true"` or if that the element is grabbable, but not currently grabbed with `aria-grabbed="false"`.

Setting `aria-grabbed="true"` indicated the element had been selected for dragging. Setting `aria-grabbed="false"` indicated that the element could be grabbed for a drag-and-drop operation, but is not currently grabbed.

When `aria-grabbed` is set to `true`, the `aria-dropeffect` attribute of all potential drop targets should be updated with the type of function, or effect, will occur to the grabbed element when it is dropped. When no element is in a grabbed state, revert the `aria-dropeffect` attributes of all your drop targets.

The `aria-grabbed` property is expected to be replaced by a new feature in a future version of WAI-ARIA and is considered deprecated.

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

Values
------

`true`

The element has been selected for dragging.

`false`

The element is not currently selected for dragging, but can be made available for dragging by setting the property to `true`.

`undefined` (default)

The element does not support being dragged

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

Used in **ALL** roles

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

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

See Also
--------

* `aria-dropeffect`
* HTML global `draggable` attribute
* HTML Drag and Drop API
* `dataTransfer`
* `DataTransfer.dropEffect`
* `dragstart`
* Accessible Drag and Drop by Gez Lemon