aria-errormessage - Accessibility

aria-errormessage
=================

The `aria-errormessage` attribute on an object identifies the element that provides an error message for that object.

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

When there is a user-created error, you want to let them know it exists and tell them how to fix it. There are two attributes you need to use: set `aria-invalid="true"` to define the object as being in an error state, then add the `aria-errormessage` attribute with the value being the `id` of the element containing the error message text for that object.

The `aria-errormessage` attribute should only be used when the value of an object is not valid; when `aria-invalid` is set to `true`. If the object is valid and you include the `aria-errormessage` attribute, make sure the element referenced is hidden, as the message it contains is not relevant.

When `aria-errormessage` is relevant, the element it references must be visible so users can see or hear the error message.

Often times, you will want the element with the error message to be an ARIA live region, such as when an error message is displayed to users after they have provided an invalid value. The error message should describe what is wrong and inform the user what is required to make the object valid. Adding the error message as an ARIA live region informs assistive technologies that the user may benefit from the error message content even if the error message wouldn't otherwise be conveyed to the user.

Include a visible error message and link the invalid object with the `aria-errormessage` attribute if the failure is visually apparent and an explicit description of the error is necessary.

Example
-------

We create some styles to:

1. Hide all error messages,
2. Make invalid objects appear invalid, and
3. Show error messages that are siblings coming after an invalid object.

We use `aria-invalid="true"` to identify invalid objects:

```css
.errormessage {
  visibility: hidden;
}

[aria-invalid="true"] {
  outline: 2px solid red;
}

[aria-invalid="true"] ~ .errormessage {
  visibility: visible;
}
```

When an object is invalid, we use JavaScript to add `aria-invalid="true"`. The above CSS makes the `.errormessage` following an invalid object become visible.

```html
<p>
  <label for="email">Email address:</label>
  <input
 type="email"
 name="email"
 id="email"
 aria-invalid="true"
 aria-errormessage="err1" />
  <span id="err1" class="errormessage">Error: Enter a valid email address</span>
</p>
```

When we went from valid to invalid, the only JavaScript change for this example was an update to `aria-invalid` on the email input object. As the error message follows the input and becomes visible and available on the accessibility tree, we are able to keep our example simple. We could have also applied an `aria-live` property or used a live region roles such as `alert`.

Values
------

`id` reference

The value of the `id` of the element containing the error message for the current element

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

Used in roles:

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

Inherits from roles:

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

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

See Also
--------

* HTML `invalid` attribute
* CSS `:invalid` pseudoclass
* `aria-invalid`
* `aria-describedby`
* `aria-live`


aria-brailleroledescription - Accessibility

aria-brailleroledescription
===========================

The global `aria-brailleroledescription` attribute defines a human-readable, author-localized abbreviated description for the role of an element intended to be converted into Braille.

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

Braille is not a one-to-one transliteration of letters and numbers, but rather it includes various abbreviations, contractions, and characters that represent words (known as logograms).

Instead of converting long role descriptions to Braille, the `aria-brailleroledescription` attribute allows for providing an abbreviated version of the `aria-roledescription` value, which is a human-readable, author-localized description for the role of an element, for improved user experience with Braille interfaces.

Basically, the value of `aria-brailleroledescription` is an abbreviated version of the `aria-roledescription` attribute to be converted into Braille.

```html
<article
 aria-roledescription="slide"
 aria-brailleroledescription="sld"
 aria-labelledby="slide1heading">
  <h1 id="slide1heading">Welcome to my talk</h1>
  <img alt="Me" src="images/me.jpg" />
</article>
```

Most assistive technologies, like screen readers, will read the above as "slide, welcome to by talk. Image, Me." Braille assistive technologies will present "sld welcome to my talk gra me" in Braille. The semantic `<article>` is given the role of "slide" by the `aria-roledescription` attribute; "slide" being a role not defined in the specification, but is a common role for slides in a presentation. In Braille, the role is presented as "sld". The "gra" is short for "graphic", which is how the "image" role is shortened in Braille.

The `aria-brailleroledescription` attribute should only be used to clarify the purpose of non-interactive container roles like "group" or "region", or to provide a more specific description of a widget in a braille context.

As the `aria-brailleroledescription` attribute overrides how assistive technologies localize and express the name of a role in Braille, inappropriate values will prevent users from understanding and interacting with an element on braille interfaces.

Only use `aria-brailleroledescription` if `aria-roledescription` is present. However, if the `aria-roledescription` value works in Braille, the Braille version of the attribute is not needed. In general, `aria-brailleroledescription` should only be used in the rare case when a `aria-roledescription` is too verbose for Braille.

A few rules to remember:

* Only apply `aria-brailleroledescription` to elements with a valid ARIA role or elements with implicit role semantics.
* The `aria-brailleroledescription`, if present, must have a non-empty, none null value that is different from the `aria-roledescription` value, which, in turn, is different from the ARIA explicit or role or implicit semantic role.
* Avoid using Unicode Braille Patterns. If they must be used, ensure the `aria-brailleroledescription` value contains content other than Unicode Braille Patterns, whitespace, and Braille Pattern dots-0.
* Ensure the value is always localized to the document's language.

**Warning:** If the content is only in Unicode Braille Patterns, the value will not be translated according to the user's preferred translation table.

**Note:** Do NOT use `aria-brailleroledescription` to replicate `aria-roledescription`. Only include this attribute when `aria-roledescription` does not provide an adequate braille representation.

The `aria-brailleroledescription` value will not be exposed to the braille user if:

* The value is empty or contains only whitespace characters or the empty Braille pattern: dots-0 (U+2800).
* The element to which the attribute is applied has an explicit or implicit WAI-ARIA role where `aria-brailleroledescription` is prohibited, including the `generic` role.
* The element to which the attribute is applied does not have a valid `aria-roledescription`.

**Note:** Test your sites and applications with daily users of assistive technologies, including Braille readers, to ensure your content makes sense in Braille.

Values
------

`<string>`

The value is a string, an unconstrained value type, that is intended to be converted into Braille

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

Used in **ALL** roles (except `generic`).

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

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

See Also
--------

* `aria-roledescription`.
* `Element.ariaRoleDescription`


aria-label - Accessibility

aria-label
==========

The `aria-label` attribute defines a string value that labels an interactive element.

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

Sometimes the default accessible name of an element is missing, or does not accurately describe its contents, and there is no content visible in the DOM that can be associated with the object to give it meaning. A common example is a button containing an SVG or icon font (which you shouldn't be using) without any text.

In cases where an interactive element has no accessible name, or an accessible name that isn't accurate, and there is no content visible in the DOM that can be referenced via the `aria-labelledby` attribute, the `aria-label` attribute can be used to define a string that labels the interactive element on which it is set. This provides the element with its accessible name.

```html
<button aria-label="Close" onclick="myDialog.close()">
  <svg
 aria-hidden="true"
 focusable="false"
 width="17"
 height="17"
 xmlns="http://www.w3.org/2000/svg">
    <path
 d="m.967 14.217 5.8-5.906-5.765-5.89L3.094.26l5.783 5.888L14.66.26l2.092 2.162-5.766 5.889 5.801 5.906-2.092 2.162-5.818-5.924-5.818 5.924-2.092-2.162Z"
 fill="#000" />
  </svg>
</button>
```

**Note:** `aria-label` is intended for use on interactive elements, or elements made to be interactive via other ARIA declarations, when there is no appropriate text visible in the DOM that could be referenced as a label

Most content has an accessible name generated from its immediate wrapping element's text content. Accessible names can also be created by certain attributes or associated elements.

By default, a button's accessible name is the content between the opening and closing `<button>` tags, an image's accessible name is the content of its `alt` attribute, and a form input's accessible name is the content of the associated `<label>` element.

If none of these options are available, or if the default accessible name is not appropriate, use the `aria-label` attribute to define the accessible name of an element.

`aria-label` can be used in cases where text that could label the element is *not* visible. If there is visible text that labels an element, use `aria-labelledby` instead.

The purpose of `aria-label` is the same as `aria-labelledby`. Both provide an accessible name for an element. If there is no visible name for the element you can reference, use `aria-label` to provide the user with a recognizable accessible name. If the label text is available in the DOM, and referencing the DOM content and acceptable user experience, prefer to use `aria-labelledby`. Don't include both. If both are present on the same element, `aria-labelledby` will take precedence over `aria-label`.

**Note:** While `aria-label` is allowed on any element that can have an accessible name, in practice, `aria-label` is only supported on interactive elements, widgets, landmarks, images and iframes.

The `aria-label` attribute can be used with regular, semantic HTML elements; it is not limited to elements that have an ARIA `role` assigned.

Don't "overuse" `aria-label`. For example, use visible text with `aria-describedby` or `aria-description`, not `aria-label`, to provide additional instructions or clarify the UI. Always remember, you don't need to target instructions to screen readers only; if instructions are needed, provide them to everyone (or, preferably, make your UI more intuitive).

Not all elements can be given an accessible name. Neither `aria-label` nor `aria-labelledby` should be used with non-interactive elements or inline structural role such as with `code`, `term`, or `emphasis` nor roles whose semantics will not be mapped to the accessibility API, including `presentation`, `none`, and `hidden`. The `aria-label` attribute is intended for interactive elements only. Use `aria-label` to ensure an accessible name is provided when none is visible in the DOM for all interactive elements, like links, videos, form controls, landmark roles, and widget roles.

If you give your `<iframe>`s a `title`, your images an `alt` attributes, and your input's associated `<label>`s, `aria-label` is not necessary. But, if present, the `aria-label` will take precedence over the `title`, `alt` and `<label>` as your `iframe`, image, or input's accessible name, respectively.

**Note:** The `aria-label` is only "visible" to assistive technologies. If the information is important enough to add for AT users, consider making it visible for all users.

Values
------

`<string>`

A string of text that will be the accessible name for the object.

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

`Element.ariaLabel`

The `ariaLabel` property, part of the `Element` interface, reflects the value of the `aria-label` attribute.

`ElementInternals.ariaLabel`

The `ariaLabel` property, part of the `ElementInternals` interface, reflects the value of the `aria-label` attribute.

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

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

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

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

**Note:** The `aria-label` attribute is intended for interactive elements only. When placed on non-interactive elements, such as those listed above, it may not be read or may confuse your users as a non-interactive element that acts like an interactive one.

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

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

See Also
--------

* `<label>` element
* `aria-labelledby`
* Using HTML landmark roles to improve accessibility on MDN blog (2023)


aria-pressed - Accessibility

aria-pressed
============

The `aria-pressed` attribute indicates the current "pressed" state of a toggle button.

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

Adding `aria-pressed` to an element with a role of `button` turns the button into a toggle button. The `aria-pressed` attribute is only relevant for toggle buttons. It represents the button's current "pressed" state.

The value is "tri-state", meaning the value can be set to `true`, `false`, `mixed`, or `undefined` values. In the case of `aria-pressed`, like most tri-state value types, the default value is `undefined`.

Toggle buttons require a full press-and-release cycle to change their value. Pressing and releasing it once changes the value to `true`. If it's pressed and released again, the value changes back to `false`.

A value of `mixed` means that the values of more than one item controlled by the button do not all share the same value.

Do not change the contents of the label on a toggle when the state changes. If a button label says "pause", do not change it to "play" when pressed. In this example, when the pressed state is true, the label remains "Pause" so a screen reader would say something like "Pause toggle button pressed".

```html
<button aria-pressed="false">Pause</button>
```

If you want the label to toggle between "Paused" and "Play", don't use `aria-pressed`.

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 `<button>`, we can toggle the label instead of toggling the pressed state, removing the need for the `aria-pressed` attribute.

Values
------

`false`

The button supports being pressed but is not currently pressed.

`mixed`

Indicates a mixed mode value for a tri-state toggle button.

`true`

The button is pressed.

`undefined` (default)

The element does not support being pressed.

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

`Element.ariaPressed`

The `ariaPressed` property, part of the `Element` interface, reflects the value of the `aria-pressed` attribute.

`ElementInternals.ariaPressed`

The `ariaPressed` property, part of the `ElementInternals` interface, reflects the value of the `aria-pressed` attribute.

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

Used in roles:

* `button`
Specifications
--------------

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

See Also
--------

* `<input type="button">`
* `<input type="submit">`
* `<button>`
* `aria-checked`
* `aria-selected`


aria-modal - Accessibility

aria-modal
==========

The `aria-modal` attribute indicates whether an element is modal when displayed.

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

A section of content is "modal" means navigation is limited to the area itself and the background (the ancestors and siblings of the modal) is hidden. Setting `aria-modal="true"` on `dialog` and `alertdialog` role containers indicates the presence of a "modal" element to users of assistive technology, but does not actually make the element modal. The features that make the element actually modal must be implemented by the developer.

**Note:** ARIA only modifies the accessibility tree, modifying how assistive technology presents the content to your users. ARIA doesn't change anything about an element's function or behavior. To create a modal effect you must use JavaScript to manage behavior, focus, and ARIA states.

Relevant only on `dialog` and `alertdialog` containers, setting `aria-modal="true"` tells assistive technologies to let the user know the ability to interact with, or access other content on the page requires the modal dialog to be closed or otherwise lose focus.

Modal dialogs are when content is displayed and the user's interaction is limited to only that section until it is dismissed.

When creating modal dialogs, `aria-modal="true"` tells assistive technologies that the windows underneath the current dialog are not part of the modal content.

When a modal element is displayed, focus should be placed in the modal. Focus needs to be "trapped" inside the modal when it is visible, until it is dismissed. Assistive technology (AT) can then navigate the modal's content and understand the scope of the modal's content. The `aria-modal` attribute helps AT communicate the bounds of the modal and distinguishes it from the rest of the page's content. When dismissed, focus should return to the element that triggered the modal.

Ensure the modal is controllable using only its descendant elements. If a modal dialog has a close button, the button should be a descendant contained with the modal container in the DOM.

When a modal element is displayed, authors **should** mark all other contents as inert (such as "inert subtrees" in HTML). Disabled content is not inert content. Inert content cannot be interacted with using both normal and specialized browsing modes such as caret browsing, which allow an assistive technology user to explore a page in detail. This includes disabled content, whose content may provide meaning.

The `inert` attribute is a boolean attribute that indicates, by its presence, that the element and all its shadow-including descendants are to be made inert. Until `HTMLElement.inert` is fully supported, content can be made inert with JavaScript.

Including `aria-modal="true"` on a `dialog` or `alertdialog`, removes the requirement of putting `aria-hidden` on background content, as the `aria-modal` informs assistive technologies that content outside a dialog is inert. Note that while support for the `<dialog>` element is good, thoroughly testing your implementation is vitally important.

If a dialog is not modal — there is no inert background and focus isn't confined to the dialog — either include `aria-modal="false"` or omit the attribute altogether.

Example
-------

```html
<div id="backdrop" class="no-scroll">
  <div
 role="alertdialog"
 aria-modal="true"
 aria-labelledby="dialog\_label"
 aria-describedby="dialog\_desc">
    <h2 id="dialog\_label">Confirmation</h2>
    <div id="dialog\_desc">
      <p>Are you sure you want to delete this file?</p>
    </div>
    <button type="button" onclick="closeDialog(this)">
      No. Close this popup.
    </button>
    <button type="button" onclick="deleteFile(this)">
      Yes. Delete the file.
    </button>
  </div>
</div>
```

This partial example includes an `alertdialog` nested in a full-screen, non-scrollable backdrop.

The `role="alertdialog"` identifies the element that serves as the alert dialog container. The `aria-labelledby` provides the alert dialog an accessible name by referring to the element that provides the alert dialog title. The `aria-describedby` attribute gives the alert dialog an accessible description by referring to the alert dialog content that describes the primary message or purpose of the alert dialog.

The `aria-modal="true"` informs the assistive technology user that the content underneath the dialog is not interactive so long as the element with a declaration of `role="alertdialog"` has focus.

The `aria-modal` attribute exposes the existence of the modal to assistive technologies so the disabling of the content behind the modal can be communicated to AT users. Like all ARIA attributes, `aria-modal` itself has no effect on the page's functionality; focus management and disabling, interactivity on background elements, and the ability to remove focus from the alertdialog must all be managed with JavaScript.

Values
------

`false` (default)

Element is not modal.

`true`

Element is modal.

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

`Element.ariaModal`

The `ariaModal` property, part of the `Element` interface, reflects the value of the `aria-modal` attribute.

`ElementInternals.ariaModal`

The `ariaModal` property, part of the `ElementInternals` interface, reflects the value of the `aria-modal` attribute.

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

Used in roles:

* `window`

Inherits into roles:

* `alertdialog`
* `dialog`
Specifications
--------------

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

See Also
--------

* HTML `<dialog>` element
* `alertdialog` role
* `dialog` role
* HTML `inert` global attribute
* HTMLElement API `inert` property


aria-expanded - Accessibility

aria-expanded
=============

The `aria-expanded` attribute is set on an element to indicate if a control is expanded or collapsed, and whether or not the controlled elements are displayed or hidden.

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

There are several widgets that can be expanded and collapsed, including menus, dialogs, and accordion panels. Each of these objects, in turn, has an interactive element that controls their opening and closing. The `aria-expanded` attribute is applied to this focusable, interactive control that toggles the visibility of the object.

For example, `aria-expanded` is applied to the parent item in a DOM tree to indicate whether its child branch is shown. The parent controls the visibility of the associated child branch, as well.

There are two declarations that can be applied to objects that control the visibility of another object: `aria-controls`, or `aria-owns` combined with `aria-expanded`. The `aria-controls` and `aria-owns` indicate the relationship between the controlling element and the controlled element. The `aria-expanded` indicates to assistive technology whether the controlled element is expanded or collapsed.

Use the `aria-owns` property on the elements that own expandable grouping containers. If the expandable and collapsible grouping container is not owned by the element that has the `aria-expanded` attribute, use the `aria-controls` property to reference the grouping container instead.

### Buttons

A button that opens a widget should have `aria-controls` set to the `id` of the expandable widget and `aria-expanded` set to the current state of the widget.

```html
<button aria-expanded="false" aria-controls="widget1">Show widget</button>
```

When the widget is visible, the controlling object relays that information via having `aria-expanded="true"` set on it. The accessible name of the controlling object should reflect this change.

```html
<button aria-expanded="true" aria-controls="widget1">Hide widget</button>
```

### Menu

When a `menu` is displayed, the button object that toggles the visibility of that menu has `aria-expanded="true"` set. When the menu is hidden, aria-expanded can be omitted. If specified when the menu is hidden, it should be set as `aria-expanded="false"`. When a child menu is not visible, its parent `menuitem` has `aria-expanded`. It should be set to `true` when the child menu is visible.

### Combobox

By default, some roles are hidden or collapsed and other roles are open or expanded by default. Elements with role `combobox` have a default value for `aria-expanded` of `false`. When a combobox popup is not visible, the element with role `combobox` has `aria-expanded` set to `false`. This is the default state. When the popup element is visible, `aria-expanded` should be set to `true`.

```html
<label for="username">Username</label>
<input id="username" name="username" aria-describedby="username-desc" />
<button
 aria-expanded="false"
 aria-controls="username-desc"
 aria-label="Help about username"
 type="button">
  <span aria-hidden="true">?</span>
</button>
<p id="username-desc" hidden>
  Your username is the name that you use to log in to this service.
</p>
```

**Note:** The presence of the `aria-expanded` attribute indicates control. Avoid including it on elements that do not control the expanded state of other elements.

### Treeitems

Each element with role `treeitem` that serves as a parent node has `aria-expanded="false"` when the node is in a closed state and `aria-expanded="true"`when the node is in an open state. End nodes, nodes with no descendant nodes, should not have the `aria-expanded` attribute because, if they were to have it, they would be incorrectly described to assistive technologies as parent nodes.

### Rows

A parent row in a `treegrid` is a row that can be expanded or collapsed to show or hide a set of child rows in a table or grid. Each parent row has the `aria-expanded` state set on either the row element or on a cell contained in the row. When the child rows are hidden, `aria-expanded="false"` is set. `aria-expanded="true"` is set when the child rows are displayed. Rows that do not control the display of child rows should not include the `aria-expanded` attribute at all because including the attribute defines the rows as parent rows.

Values
------

`false`

The grouping element this element owns or controls is collapsed.

`true`

The grouping element this element owns or controls is expanded.

`undefined` (default)

The element does not own or control a grouping element that is expandable.

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

`Element.ariaExpanded`

The `ariaExpanded` property, part of the `Element` interface, reflects the value of the `aria-expanded` attribute.

`ElementInternals.ariaExpanded`

The `ariaExpanded` property, part of the `ElementInternals` interface, reflects the value of the `aria-expanded` attribute.

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

Used in roles:

* `application`
* `button`
* `checkbox`
* `combobox`
* `gridcell`
* `link`
* `listbox`
* `menuitem`
* `row`
* `rowheader`
* `tab`
* `treeitem`

Inherits into roles:

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

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

See Also
--------

* `aria-controls`
* `aria-owns`
* `aria-hidden`
* HTML `hidden` attribute


aria-colindex - Accessibility

aria-colindex
=============

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

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

Some tables are very large, and as a result have only a portion of its content is initially displayed. While loading only a subsection of the columns may improve user experience, you need to let all users know what portions of the content are being displayed, and that all the table's content is not present.

ARIA provides several attributes to provide information about `table`, `grid`, and `treegrid` structures. The `aria-colindex` attribute defines the substructure, an element's column index or position with respect to the total number of columns, within such structures.

Used in conjunction with the `aria-colcount` attribute, which informs assistive technologies how many columns the table would have if all columns were present, the `aria-colindex` is used an element's column index or position with respect to that total number of columns.

If all of the columns are present in the DOM, including `aria-colindex` is not necessary as user agents can calculate the column index of each cell or gridcell. However, if any of the columns are left out of the DOM at any time, use `aria-colindex` to indicate the column of each cell or gridcell with respect to the full table.

The value for `aria-colindex` is an integer greater than or equal to 1. Each value should be greater than the previous column's `aria-colindex` and less than or equal to the number of columns in the full table.

If a cell or gridcell spans multiple columns, set `aria-colspan` to the number of columns it spans if not using `<td>` and `<th>` HTML elements, and set `aria-colindex` to the value of the start of the span; the value it would have had if it was only one column wide spanning only the first of its columns.

If the set of columns which is present in the DOM is contiguous, and if there are no cells which span more than one row or column in that set, you only have to put the `aria-colindex` once on each row on the first column of the set. If the columns are not contiguous, include the `aria-colindex` value on all of the children or owned elements of 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., and only display a subsection of columns, the `aria-colcount` and `aria-colindex` attribute are 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-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>
```

If all the columns are in the DOM, neither `aria-colcount` nor `aria-colindex` are necessary.

Values
------

`<integer>`

Integer greater than or equal to 1 and less than or equal to the total number of columns if all were present.

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

`Element.ariaColIndex`

The `ariaColIndex` property, part of the `Element` interface, reflects the value of the `aria-colindex` attribute.

`ElementInternals.ariaColIndex`

The `ariaColIndex` property, part of the `ElementInternals` interface, reflects the value of the `aria-colindex` attribute.

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

Used in roles:

* `cell`
* `row`

Inherits into roles:

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

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

See Also
--------

* `aria-colindextext` attribute
* `aria-colcount` attribute
* `aria-colspan` attribute
* HTML `<table>` element
* HTML `<th>` element
* HTML `<td>` element


aria-keyshortcuts - Accessibility

aria-keyshortcuts
=================

The global `aria-keyshortcuts` attribute indicates keyboard shortcuts that an author has implemented to activate or give focus to an element.

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

A keyboard shortcut is a series of one or several keys that tells software to perform a pre-programmed action. Keyboard shortcuts enable keyboard users to invoke commands using the keyboard that would otherwise require accessing a menu or using touch or a mouse. The `aria-keyshortcuts` property defines the keyboard keys that have been implemented to activate or give focus to the element on which the attribute is set.

The `aria-keyshortcuts` attribute exposes the existence of the shortcut to assistive technologies so the presence of the shortcut can be communicated to its users. Like all ARIA attributes, it has no effect on the functionality of the page; the keyboard behavior must be added via JavaScript event handlers.

Keyboard shortcuts applied to disabled elements should also be disabled. For example, when disabling an element for mouse users, remember to disable it for keyboard shortcut users.

Ensure all keyboard shortcuts are both visible to sighted users and made available to assistive technology. If your application is complex enough to need keyboard shortcuts, also known as "hot keys", include a guided tour of your application, an accessibility page documenting shortcuts and other accessibility features, a shortcut cheat sheet page or dialog pop up, or other method of making the availability of keyboard short cuts known. In addition, show the shortcut in menus and tooltips.

### Property value rules

The value of the `aria-keyshortcuts` attribute is a space-separated list of key combinations that can be pressed to activate a command or textbox widget. Each key combination includes zero, one or more modifier keys followed by exactly one non-modifier key to be pressed at the same time joined with a plus sign ("+"). The attribute value is case-insensitive.

Examples of valid keyboard shortcuts include:
```

aria-keyshortcuts="A"
aria-keyshortcuts="Shift+Space"
aria-keyshortcuts="Control+Alt+."
aria-keyshortcuts="Control+Shift+'"
aria-keyshortcuts="alt+shift+p control+f"
aria-keyshortcuts="Meta+C Meta+Shift+C"
```

Modifier keys are keys that don't have any impact when used on their own. They are written as "Alt", "Control", "Shift", "Meta" (Command key on Mac), or "AltGraph" (Option key on Mac).

Non-modifier keys are keys that have impact when used alone, be that printing a character, moving focus, or otherwise creating a keyboard event when used. Non-modifiers that print a single character include characters like `P`, `z` and `.`.

Since the plus sign is used in writing key combinations, it is written as `plus` if used as the non-modifier. Other written-out non-modifiers include white space characters `Space`, `Tab`, and `Enter`, and all characters that result in actions, like `ArrowUp`, `PageUp`, and `Escape`.

If you want to use a character that might cause problems, like a double quote character within double quotes, escape the character: `Control+'`.

Modifier keys must be listed first in each key combination. Possible key combinations include `Control+P` or `Shift+Space` and `Q`. If the full shortcut requires all three of these combinations in order, it would be written as `aria-keyshortcuts="Control+P Shift+Space Q"`. When a key combination includes more than one modifier key, the order of the modifiers doesn't matter, but they all must come first, before the non-modifier.

These two attribute declarations are equivalent.
```

aria-keyshortcuts="Shift+Control+V"
aria-keyshortcuts="control+shift+v"
```

Note that text case doesn't matter. But order of non-modifier does.

These two attribute declarations are invalid because the non-modifier must be last.
```

aria-keyshortcuts="V+Shift+Control"
aria-keyshortcuts="V+Control+Shift"
```

The key combination listed must be the keys the user needs to press, not the outcome of the combined key strokes. For example, on a USA keyboard, if you need the `@` symbol, the key combination is written as `"Shift+2"`, not `"@"` nor `"Shift+@"`.

### Best practices

In trying to improve the accessibility of your sites and applications, there are some best practices to follow to ensure your "enhancements" don't negatively impact user experience. Remember, no ARIA is better than bad ARIA.

#### Don't override browser, assistive technology, or operating system shortcuts

When implementing keyboard shortcuts, make sure you don't create shortcuts that are already being used by the browser, assistive technology, or operating system, unless they are used for the same thing. For example, `"Control+P"` is used by most user-agents to initiate print functionality. Generally a web application should not create a "Control+P" shortcut as it will usurp browser functionality. There are exceptions. Web applications where printing is common, like email applications or document editors, usurping the browser's `"Control+P"` printing functionality for an application specific print flow would be expected.

Unless you're creating an HTML version of a productivity application, you should likely avoid implementing keyboard shortcut. While overriding an operating system or browser keyboard shortcut can be annoying for non-assistive technology users, if you override a screen reader's keyboard functionality you can completely shut down access for the assistive technology user. If you must create keyboard shortcuts, avoid single letter keyboard shortcuts and common screen reader keyboard shortcuts.

#### Consider language and keyboard differences

Take into account the diversity of available keyboards and the various keyboard language preferences. Modifier keys are often used to create language specific common punctuation symbols and number characters. For example, numbers, when the keyboard language preference is set to French (France), use the Shift key.

#### Don't use HTML instead

The `aria-keyshortcuts` attribute is very similar to the problematic HTML `accesskey`, which generates a keyboard shortcut for the current element. When an `accesskey` is defined for an element, the browser defines the modifiers and does all the work of handling the shortcut with no scripting required. Every browser and operating system combination has their own modifier keys for the non-modifier set in the `accesskey` attribute. What may work for one combination of operating system, assistive technology, and browser may not work with other combinations. With `aria-keyshortcuts`, the modifier keys are included in the attribute value list of key combinations and the functionality has to be scripted in.

```html
<p>
  Press the
  <strong><u>S</u></strong
 >tress reliever to relax!
</p>
<button accesskey="s">Stress reliever</button>
```

In this example, we ensured the presence of the shortcut was known to sighted users a well by highlighting the non-modifier character.

While the goal of the `accesskey` attribute matches the intention of `aria-keyshortcuts` and to do so natively, `accesskey` is rife with issues. Because of these issues, it is generally advised not to use accesskeys for most general-purpose websites and web apps.

In addition to poor browser support, the same concerns arise for `accesskey` as exist for `aria-keyshortcuts`:

* An accesskey value can conflict with a system or browser keyboard shortcut, or assistive technology functionality.
* Certain key values may not be present on certain keyboards, especially when internationalization is a concern. So adapting to specific languages could cause further problems.
* Values that rely on numbers may be confusing to individuals experiencing cognitive concerns, where the number doesn't have a logical association with the functionality it triggers.
* Informing the user that shortcuts are present, so that they are aware of the functionality. If the system lacks a method of notifying the user about this feature, the user might accidentally activate a shortcut.
Values
------

`<string>`

The space-separated list of key combinations that, when pressed, perform the action.

Example
-------

In this example, the `aria-keyshortcuts` attribute on the element is set to "Alt+Shift+A".

```html
<a href="#content" aria-keyshortcuts="Alt+Shift+A">Skip to content</a>
```

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

`Element.ariaKeyShortcuts`

The `ariaKeyShortcuts` property, part of the `Element` interface, reflects the value of the `aria-keyshortcuts` attribute.

`ElementInternals.ariaKeyShortcuts`

The `ariaKeyShortcuts` property, part of the `ElementInternals` interface, reflects the value of the `aria-keyshortcuts` attribute.

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

Used in **ALL** roles.

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

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

See Also
--------

* `aria-keyshortcuts` best practices
* HTML `accesskey` attribute
* Issues with `accesskey`


aria-colspan - Accessibility

aria-colspan
============

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

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

Intended for `cell`s and `gridcell`s which are not contained in a native HTML `<table>`, the `aria-colspan` property value defines the number of columns spanned by an individual cell an ARIA `table`, `grid`, or `treegrid`.

In HTML, `<th>` and `<td>` elements have the `colspan` attribute. When using the semantic `<table>`, use the native `colspan` attribute as designed. This ARIA attribute is intended for cells and gridcells which are not contained in a native table, and will be ignored if used on a cell in a `<table>`.

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

The value of `aria-colspan` should be a positive integer. The default or assumed value of a cell span is 1. Make sure that the included value does cause the cell or gridcell to overlap the next cell or gridcell in the same row and does not cause the cell to span outside of the containing table, grid, or treegrid.

Example
-------

The following is an example of part of a bowling tournament league scoring spreadsheet. Each game spans 10 frames, and each frame spans a 3 scores: two balls and the current total. The 10th (and last) frame in each game spans 4 columns in case someone is scoring all strikes.

```html
<div role="grid" aria-rowcount="27">
  aria-label="Bowling League Scores"
  <div role="rowgroup">
    <div role="row" aria-rowindex="1">
      <!--
 aria-rowspan and aria-colspan provide
 assistive technologies with the correct data cell header information
 when header cells span more than one row or column.
 -->

      <span role="columnheader" aria-rowspan="2">Team</span>
      <span role="columnheader" aria-colspan="2">Player</span>
      <span role="columnheader" aria-colspan="31">Game 1 Frames</span>
      <span role="columnheader" aria-colspan="31">Game 2 Frames</span>
      <span role="columnheader" aria-colspan="31">Game 3 Frames</span>
      <span role="columnheader" aria-rowspan="2">Total</span>
    </div>
    <div role="row" aria-rowindex="2">
      <span role="columnheader">Last Name</span>
      <span role="columnheader">First Name</span>
      <span role="columnheader" aria-colspan="3">1</span>
      <span role="columnheader" aria-colspan="3">2</span>
      <span role="columnheader" aria-colspan="3">3</span>
      <span role="columnheader" aria-colspan="3">4</span>
      <span role="columnheader" aria-colspan="3">5</span>
      <span role="columnheader" aria-colspan="3">6</span>
      <span role="columnheader" aria-colspan="3">7</span>
      <span role="columnheader" aria-colspan="3">8</span>
      <span role="columnheader" aria-colspan="3">9</span>
      <span role="columnheader" aria-colspan="4">10</span>
      <span role="columnheader" aria-colspan="3">1</span>
      <span role="columnheader" aria-colspan="3">2</span>
      <span role="columnheader" aria-colspan="3">3</span>
      <span role="columnheader" aria-colspan="3">4</span>
      <span role="columnheader" aria-colspan="3">5</span>
      <span role="columnheader" aria-colspan="3">6</span>
      <span role="columnheader" aria-colspan="3">7</span>
      <span role="columnheader" aria-colspan="3">8</span>
      <span role="columnheader" aria-colspan="3">9</span>
      <span role="columnheader" aria-colspan="4">10</span>
      <span role="columnheader" aria-colspan="3">1</span>
      <span role="columnheader" aria-colspan="3">2</span>
      <span role="columnheader" aria-colspan="3">3</span>
      <span role="columnheader" aria-colspan="3">4</span>
      <span role="columnheader" aria-colspan="3">5</span>
      <span role="columnheader" aria-colspan="3">6</span>
      <span role="columnheader" aria-colspan="3">7</span>
      <span role="columnheader" aria-colspan="3">8</span>
      <span role="columnheader" aria-colspan="3">9</span>
      <span role="columnheader" aria-colspan="4">10</span>
    </div>
  </div>
  <div role="rowgroup">
    <div role="row" aria-rowindex="10">
      <span role="rowheader" aria-rowspan="3">The Mighty Quokkas</span>
      <span role="cell">Henderson</span>
      <span role="cell">Alice</span>
      <span role="cell">7</span>
      <span role="cell">/</span>
      <span role="cell">20</span>
      <span role="cell" aria-colspan="2">X</span>
      <span role="cell">39</span>
      <span role="cell">9</span>
      <span role="cell">-</span>
      <span role="cell">48</span>
      <span role="cell" aria-colspan="2">X</span>
      <span role="cell">76</span>
      <span role="cell" aria-colspan="2">X</span>
      <span role="cell">96</span>
      <span role="cell">8</span>
      <span role="cell">/</span>
      <span role="cell">113</span>
      <span role="cell">7</span>
      <span role="cell">-</span>
      <span role="cell">120</span>
      <span role="cell" aria-colspan="2">X</span>
      <span role="cell">146</span>
      <span role="cell" aria-colspan="2">X</span>
      <span role="cell">166</span>
      <span role="cell">6</span>
      <span role="cell">/</span>
      <span role="cell">X</span>
      <span role="cell">186</span>
      <span role="cell">7</span>
      <span role="cell">2</span>
      <span role="cell">9</span>
      <span role="cell">6</span>
      <span role="cell">-</span>
      <span role="cell">15</span>
      <span role="cell" aria-colspan="2">X</span>
      <span role="cell">35</span>
      <span role="cell">7</span>
      <span role="cell">/</span>
      …
    </div>
    <div role="row" aria-rowindex="11">
      <span role="cell">McPherson</span>
      <span role="cell">Leslie</span>
      <span role="cell">9</span>
      <span role="cell">-</span>
      <span role="cell">9</span>
      <span role="cell">8</span>
      <span role="cell">1</span>
      <span role="cell">18</span>
      …
    </div>
  </div>
</div>
```

If we had used a `<table>` and semantic table elements our markup would have been less verbose and accessible by default.

Values
------

`<integer>`

An integer greater than or equal to the default value of 1 defining the number of columns spanned by the cell. The value must be less than what would cause a cell to overlap the next cell in the same row.

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

`Element.ariaColSpan`

The `ariaColSpan` property, part of each element's interface, reflects the value of the `aria-colspan` attribute, which defines the number of columns spanned by a cell or gridcell within a table, grid, or treegrid.

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

Used in roles:

* `cell`

Inherits into roles:

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

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

See Also
--------

* The `<th>` and `<td>` `colspan` attribute
* `aria-colindex` property
* `aria-rowspan` property
* `cell` role
* `columnheader` role
* `rowheader` role


aria-activedescendant - Accessibility

aria-activedescendant
=====================

The `aria-activedescendant` attribute identifies the currently active element when focus is on a `composite` widget, `combobox`, `textbox`, `group`, or `application`.

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

The `aria-activedescendant` property provides a method of managing focus for assistive technologies on interactive elements when they contain multiple focusable descendants, such as menus, grids, and toolbars. Instead of the screen reader moving focus between owned elements, `aria-activedescendant` can be used on container elements to refer to the currently active element, informing assistive technology users of the currently active element when focused.

With `aria-activedescendant`, the browser keeps the DOM focus on the container element or on an input element that controls the container element. However, the user agent communicates desktop focus events and states to the assistive technology as if the element referenced by `aria-activedescendant` has focus.

This attribute is only relevant on elements with role of `composite` widget, `combobox`, `textbox`, `group`, or `application` whose `id` is referenced as the attribute value.

The attribute manages providing assistive technologies with information as to which element has focus, but doesn't actually create focus. Changing focus and managing the attributes value is done with JavaScript. In addition to managing that attribute value, make sure the currently active descendant is visible and in view (or scrolls into view) when focused.

In setting the value of `aria-activedescendant` on an element with DOM focus, ensure the value refers to an owned element—either a descendant of the element with DOM focus OR a logical descendant as indicated by the `aria-owns` attribute.

When the element with DOM focus is a combobox, textbox, or searchbox, include `aria-controls` to refer to the element that supports `aria-activedescendant`.

The value of `aria-activedescendant` refers to an owned element of the controlled element. For example, in a combobox, focus may remain on the combobox while the value of `aria-activedescendant` on the combobox element refers to a descendant of a popup listbox that is controlled by the combobox.

**Note:** The attribute is supported only on a few roles. For example, `dialog`s do not support `aria-activedescendant`. When a combobox opens a dialog, DOM focus moves into the dialog from the combobox as it is not referenceable with this attribute.

**Note:** When a descendant of a `listbox`, `grid`, or `tree` popup is focused, DOM focus remains on the combobox and the combobox has `aria-activedescendant` set to a value that refers to the focused element within the popup.

Values
------

ID reference

takes as its value the `id` of the currently focused element.

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

Relevant only as an attribute on elements with the following roles:

* `application`
* `combobox`
* `composite`
* `group`
* `textbox`
Specifications
--------------

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

See Also
--------


aria-busy - Accessibility

aria-busy
=========

Used in ARIA live regions, the global `aria-busy` state indicates an element is being modified and that assistive technologies may want to wait until the changes are complete before informing the user about the update.

When multiple parts of a live region need to be loaded before changes are announced to the user, set `aria-busy="true"` until loading is complete. Then set to `aria-busy="false"`. This prevents assistive technologies from announcing changes before updates are done.

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

There is a section of content that updates. The updates are important and you want to let the user know when it has been modified, so you have converted it into an ARIA live region with the `aria-live` attribute. You may want to update several components of that section at the same time, but you can't be sure that everything will update simultaneously. Even if it is a very important live region with `aria-live="assertive"`, you don't want to interrupt the user multiple times as different parts of the content load. This is where `aria-busy` can help.

The `aria-busy` property is an optional property of live regions that can have the value `true` or `false`. The `aria-busy` attribute with a value of `true` can be added to an element currently being updated or modified, to inform the assistive technology that it should wait until the modifications or changes are complete before exposing the content to the user. Use the `ariaBusy` property of the object to change the value to `false` when downloading is complete.

```js
ariaLiveElement.ariaBusy = "false";
```

`aria-live`'s value dictates whether the changes are announced immediately upon changing the value to `false`, or the assistive technology waits until the current task is complete before interrupting the user.

### Within a `feed`

If an element with `feed` role has `aria-busy` set to `true`, the rendering changes that occur inside the feed will not be announced with the exception of user-initiated changes.

### Within a `widget`

If changes to a rendered widget would create a state where the widget is missing required owned elements during script execution, set `aria-busy` to `true` on the widget during the update process. For example, if a rendered tree grid updates multiple branches not necessarily rendered simultaneously, an alternative to replacing the whole tree in a single update would be to mark the tree busy while each of the branches is modified.

Values
------

false (default):

There are no expected updates for the element.

true

The element is being updated.

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

`Element.ariaBusy`

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

```html
<div
 id="clock"
 role="timer"
 aria-live="polite"
 aria-atomic="true"
 aria-busy="false"></div>
```

```js
const el = document.getElementById("clock");
console.log(el.ariaBusy); // false
el.ariaBusy = "true";
console.log(el.ariaBusy); // true
```

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

Used in **ALL** roles

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

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

See Also
--------

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


aria-valuetext - Accessibility

aria-valuetext
==============

The `aria-valuetext` attribute defines the human-readable text alternative of `aria-valuenow` for a range widget.

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

Numbers — even percentages — aren't always user-friendly. Assistive technologies present `aria-valuenow` as numeric values. If a progress bar is at 8%, what does that mean? `aria-valuetext` provides a way of presenting the current value in a more user-friendly, human-understandable way. For example, a battery meter value might be conveyed as `aria-valuetext="8% (34 minutes) remaining"`.

The `aria-valuetext` attribute is used with the `aria-valuenow` attribute, not instead of it, unless that value is not known.

`aria-valuetext` is only needed when the numeric value of `aria-valuenow` is not meaningful. For example, a range's values are numeric but may be used for non-numeric values, such as college class level. The values of `aria-valuenow` for a 4-year college could range from 1 through 4, which indicate the position of each value in the value space. In this case, the `aria-valuetext` could be one of the strings: "first year", "sophomore", "junior", and "senior".

If the numeric value is meaningful, such as a spinner with `aria-valuenow="3"` for how many pizza slices you want to order, `aria-valuetext` is not needed.

When both the `aria-valuetext` and `aria-valuenow` are included, the `aria-valuetext` is announced. When there is no `aria-valuetext` attribute, assistive technologies will announce the `aria-valuenow` attribute for the current value.

Values
------

`<string>`

A human-readable text alternative of the `aria-valuenow` value.

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

`Element.ariaValueText`

The `ariaValueText` property, part of the `Element` interface, reflects the value of the `aria-valuetext` attribute.

`ElementInternals.ariaValueText`

The `ariaValueText` property, part of the `ElementInternals` interface, reflects the value of the `aria-valuetext` attribute.

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

Used in roles:

* `range`
* `separator`
* `spinbutton`

Inherited into roles:

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

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

See Also
--------

* `aria-valuenow`


aria-sort - Accessibility

aria-sort
=========

The `aria-sort` attribute indicates if items in a table or grid are sorted in ascending or descending order.

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

If a grid or table provides sort functionality, the `aria-sort` attribute should be set to either `ascending` or `descending` (or `other`) on the header cell element for the sorted column or row.

The `aria-sort` attribute is only set on the currently sorted column or row. Set `aria-sort="ascending"` to indicate the data cells in the column or row are sorted in ascending order. If the sort order is reversed, toggle the value to `aria-sort="descending"`. When a different column or row becomes sorted, the single `aria-sort` attribute is moved to the header cell for the newly sorted column or row with the appropriate value for the sort order.

The `aria-sort` attribute should only be added to a single table or grid header at a time. The attribute is set to inform assistive technology users which column or row is sorted. It doesn't have any impact on the actual sort order.

Examples
--------

This table loads with the last name column sorted in ascending order.

```html
<table>
  <caption>
    Steering Committee Members
  </caption>
  <thead>
    <tr>
      <th>
        <button>First Name</button>
      </th>
      <th aria-sort="ascending">
        <button>Last Name</button>
      </th>
      <th>
        <button>Company</button>
      </th>
      <th>Email</th>
    </tr>
  </thead>
  <tbody>
    …
  </tbody>
</table>
```

If a user clicks on the *Last Name* button, `aria-pressed="true"` would be added to the `<button>` element and the `aria-sort` value would be toggled to `"descending"` with JavaScript. If the user clicks on a different header button, the `aria-sort` would be removed from the *Last Name* header to be placed on the clicked button's `<th>` parent.

We provided instructions in the caption for assistive technology who may not see the down arrows that we would add with CSS targeting the `th[aria-sort="ascending"]` and `th[aria-sort="descending"]` selectors.

Values
------

`ascending`

Items are sorted in ascending order by this column.

`descending`

Items are sorted in descending order by this column.

`none` (default)

There is no defined sort applied to the column.

`other`

A sorting algorithm other than ascending or descending has been applied.

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

`Element.ariaSort`

The `ariaSort` property, part of the `Element` interface, reflects the value of the `aria-sort` attribute.

`ElementInternals.ariaSort`

The `ariaSort` property, part of the `ElementInternals` interface, reflects the value of the `aria-sort` attribute.

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

Used in roles:

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

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

See Also
--------

* Sortable table example -W3C
* `aria-pressed`
* The `<th>` element


aria-flowto - Accessibility

aria-flowto
===========

The global `aria-flowto` attribute identifies the next element (or elements) in an alternate reading order of content. This allows assistive technology to override the general default of reading in document source order at the user's discretion.

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

Web pages should be sequentially navigable. For this reason, developers are dissuaded from using the global tabindex attribute which can change tab order and the CSS `order` property, which can change visual order from the DOM order. However, in rare circumstances a reading path different from the source order is required. For such cases, the `aria-flowto` attribute can make the content more accessible for users of assistive technologies.

The global `aria-flowto` attribute lets the author indicate to assistive technology users which element or elements might want to be focused on next, providing an alternate reading order to the source order. This allows assistive technology to read a document in an order other than the default document source reading order.

When `aria-flowto` has a single id reference, it allows assistive technologies to, at the user's request, go to the element targeted via that `id` instead of reading the document in the order of the DOM. When the `aria-flowto` value uses a space separated list of multiple `id` references, assistive technology can provide the user with a list of path choices, with each `id` referenced being a choice. The path choice names are determined by the accessible name of each target element of the `aria-flowto` attribute.

**Note:** Setting `aria-flow` does not impact the content's tab order. It only provides users the option to follow a content path that doesn't match the DOM order when using tech that supports this attribute.

Values
------

`id`

Suggested next element in the reading order.

`id` list

Space separated list of ID values referencing the suggested elements the user may want to go to next in the alternate reading order of content.

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

Used in **ALL** roles.

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

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

See Also
--------

* HTML id attribute
* HTML tabindex attribute
* CSS `order` property
* WCAG: source order
* Using aria-flowto - W3 Wiki


aria-placeholder - Accessibility

aria-placeholder
================

The `aria-placeholder` attribute defines a short hint (a word or short phrase) intended to help the user with data entry when a form control has no value. The hint can be a sample value or a brief description of the expected format.

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

A placeholder is text that appears in the form control when it has no value set. The HTML `placeholder` attribute enables providing a sample value or a brief description of the expected format for several HTML `<input>` types and `<textarea>`.

If you are creating a `textbox` using any other element, `placeholder` is not supported. That is where `aria-placeholder` comes into play. The `aria-placeholder` attribute can be used to defines a short hint to help the user understand what type of data is expected when a non-semantic form control has no value.

```html
<span id="date-of-birth">Birthday</span>
<div
 contenteditable
 role="textbox"
 aria-labelledby="date-of-birth"
 aria-placeholder="MM-DD-YYYY">
  MM-DD-YYYY
</div>
```

The placeholder hint should be shown to the user whenever the control's value is empty, including when a value is deleted.

**Note:** ARIA is only modify the accessibility tree for an element and therefore how assistive technology presents the content to your users. ARIA doesn't change anything about an elements function or behavior. When not using semantic HTML elements for their intended purpose and default functionality, you must use JavaScript to manage behavior.

The `aria-placeholder` is used in addition to, not instead of, a label. They have different purposes and different functionality. A label explains what kind of information is expected. Placeholder text provides a hint about the expected value.

**Warning:** Using a placeholder instead of a visible label harms accessibility and usability for many users including older users and users with cognitive, mobility, fine motor skill and vision impairments. Labels are better: they are always visible and they provide for a larger hit region to focus on the control. Placeholders have several drawbacks: they disappear when the control has any value including just white space, they can confuse users into thinking the value is pre-filled, and the default color has insufficient contrast.

**Note:** Placeholders should only be used to show an example of the type of data that should be entered into a form; they don't replace a proper label.

Values
------

`<string>`

The word or short phrase to display in a control when the control has no value.

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

`Element.ariaPlaceholder`

The `ariaPlaceholder` property, part of the `Element` interface, reflects the value of the `aria-placeholder` attribute.

`ElementInternals.ariaPlaceholder`

The `ariaPlaceholder` property, part of the `ElementInternals` interface, reflects the value of the `aria-placeholder` attribute.

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

Used in roles:

* `textbox`

Inherited into roles:

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

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

See Also
--------

* HTML `placeholder` attribute
* `aria-labelledby`
* `aria-label`


aria-owns - Accessibility

aria-owns
=========

The `aria-owns` attribute identifies an element (or elements) in order to define a visual, functional, or contextual relationship between a parent and its child elements when the DOM hierarchy cannot be used to represent the relationship.

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

Every element is the parent, sibling, or child of another element. The document object, made up of HTML elements and text nodes, is the basis of the DOM tree. The Accessibility Object Model (AOM) relies on a well-built DOM to enable assistive technologies to relay meaningful information about a document's contents to users.

There are circumstances where the layout that appears on screen may differ from the underlying DOM structure due to the ability of JavaScript to alter content and CSS to alter layout. When this is the case, the `aria-owns` attribute can be used to recreate a meaningful relationship for assistive technology that consumes the DOM.

When elements appear to be related visually but are not associated in the DOM, the `aria-owns` attribute enables creating the relationship that appears on screen in the accessibility layer for use by assistive technology. The **only** reason to include `aria-owns` is to expose a parent/child contextual relationship to assistive technology when the DOM's construction can't provide that relationship.

An "owning element" is any DOM ancestor of an element. If an element visually, functionally, or contextually appears to "own" (be an ancestor of) an element, but isn't actually an ancestor of the element in the DOM, include the `aria-owns` to create that relationship. Add the attribute to the owning element with reference to the non-child owned element (or elements) to tell assistive technology that an element should be treated as a child.

Referencing the ID of one or more elements allows any element to "own" any other element with an `aria-owns` declaration. The value of the `aria-owns` attribute is a space-separated ID reference list that references the IDs of one or more elements in the document.

**Note:** An "owned" element is any DOM descendant of the element, any element specified as a child via `aria-owns`, or any DOM descendant of the owned child. The `aria-owns`-owned element should be an element that belongs to a separate parent tree in the DOM but should be treated as a child of the current element.

Do not use `aria-owns` as a replacement for the DOM hierarchy. If the relationship is represented in the DOM, do not use `aria-owns`.

A child element is owned by its DOM parent by default: in this case, `aria-owns` should not be used. Avoid using the `aria-owns` attribute to rearrange existing child elements into a different order.

When using `aria-owns`, make sure you manage focus order. Ensure the visual focus order matches this assistive technology reading order.

An example of when to use `aria-owns` includes pop-up sub-menus that visually appear positioned near a parent menu, but cannot be nested in the DOM within the parent menu because it would affect the visual presentation. In this case, use `aria-owns` to present the sub-menu as a child of the parent menu to a screen reader.

**Note:** The `aria-owns` attribute should only be used when the parent/child relationship cannot be determined from the DOM.

If an element has both `aria-owns` and DOM children, the order of the child elements:

1. The actual DOM children first,
2. Then the elements referenced in `aria-owns`.

This order can be changed by including the ID references to the actual DOM children in the `aria-owns` value.

The `order` property, part of flex or grid layouts, can be used to change the order of flex and grid items making them appear in a different order from their order in the source document, creating a divergence of the logical order of elements. While it may be tempting to order the accessibility layer to match order changes created with the CSS `order` property, avoiding both the `order` property and the `aria-owns` attribute is the best option.

Make sure your owned elements have only one owner. Do not specify the `id` of an element in more than one other element's `aria-owns` attribute. An element can have only one owner.

**Warning:** At the time of this writing, `aria-owns` is not supported on MacOS and iOS with VoiceOver.

Values
------

`id` list

Space separated list of one or more ID values referencing the elements being owned by the current element

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

Used in **ALL** roles.

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

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

See Also
--------

* `aria-controls`
* `aria-owns` browser support


aria-details - Accessibility

aria-details
============

The global `aria-details` attribute identifies the element (or elements) that provide additional information related to the object.

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

The `aria-details` attribute can be used to provide additional information or complex descriptions to an object. It is used to inform assistive technology users about the content by providing more in-depth information, whether that content is within the current document or a link to additional assets.

There are other HTML and WAI-ARIA properties that have similar purposes. The HTML `<label>` element and the `aria-label` and `aria-labelledby` properties are used to provide short labels for an object. The HTML `title` attribute and the `aria-description` and `aria-describedby` properties provide for longer plain text descriptions of an object. However, when additional information, complex descriptions, or navigable content related to the object is necessary and available, the `aria-details` attribute should be used.

The `aria-details` attribute serves a similar purpose as HTML's never fully-supported `longdesc` attribute － a URL of a long description to a replaced element's content － which was deprecated due to lack of support and misuse.

The `aria-details` attribute takes the `id`, or space separated list of `id`s of the elements to get more detailed information as its values. When `aria-details` is included on an element, assistive technologies inform users of the availability of extended information, enabling the user to navigate to the referenced content.

Elements referenced by `aria-details` are intended to contain more information than would normally be provided via `aria-describedby`.

The elements referenced by `aria-details` should be visible to all users. `aria-details` informs users that otherwise might not be able to scan a screen and discern quickly that the explanatory content is available.

**Note:** `aria-details` has no impact on the accessible description.

Unlike `aria-describedby`, elements referenced by `aria-details` are not used in accessible descriptions and are not turned into a plain string when presented to assistive technology users. If the associated content is not too long and flattening the contents of the referenced element to a simple string of text wouldn't cause loss of information, consider using `aria-describedby` instead. That said, it is valid for an element to have both `aria-details` and a description specified with either `aria-describedby` or `aria-description`.

Example
-------

When it comes to definition and term roles, the `aria-details` would be included on the `term` element with the `id` of the element with a `definition` role.

```html
<p>The <strong>cubic-bezier()<strong> functional notation defines a cubic
  <span role="term" aria-details="bezier bezImg">Bézier curve</span>. As
  these curves are continuous, they are often used to smooth down the start and
  end of the curve and are therefore sometimes called easing functions.
</p>

<p role="definition" id="bezier">A <strong>Bézier curve</strong>,
 (Pronounced \ ˈbe-zē-ˌā \)
 <i aria-description="English pronunciation">BEH-zee-ay</i>) is a mathematically
 described curve used in computer graphics and animation. The curve is defined
 by a set of control points with a minimum of two. Web related graphics
 and animations use Cubic Béziers, which are curves with four control
 points P<sub>0</sub>, P<sub>1</sub>, P<sub>2</sub>, and P<sub>3</sub>.
</p>

<a href="bezierExplanation.html" id="bezImg"
 aria-label="Explanation of Bézier curve in CSS easing functions">
  <img alt="Animated Bézier curve showing 4 control points." src="bezier.gif">
</a>
```

Values
------

ID reference list

An `id` or space separated list of ids of elements that provide or link to additional related information.

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

Used in **ALL** roles.

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

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

See Also
--------

* HTML id attribute
* `aria-labelledby`
* `aria-describedby`
* `aria-description`
* The image `alt` attribute
* HTML title attribute


aria-braillelabel - Accessibility

aria-braillelabel
=================

The global `aria-braillelabel` property defines a string value that labels the current element, which is intended to be converted into Braille.

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

The global `aria-braillelabel` attribute is similar to the global `aria-label` in that it defines a string value that labels the current element. While `aria-label` is read by the screen reader, the contents of the `aria-braillelabel` attribute are converted into Braille; providing the user with a recognizable name of the object in Braille.

The purpose of the `aria-braillelabel` property is to override how assistive technologies localize and express the accessible name of an element in Braille and should only be used when accessible name, without this attribute, when converted to Braille, would not be the desired user experience.

When using `aria-braillelabel`, ensure that:

* The element to which `aria-braillelabel` is applied has a valid accessible name.
* The value of aria-braillelabel has actual content and is not empty or only whitespace in unicode or unicode Braille.
* The value is NOT the same as the accessible name.
* The `aria-braillelabel` values are localized to align with the document language.
* Communicate to the user that this attribute is available, especially if the content contains Unicode Braille Patterns, so the user knows to set the settings to apply user specific braille translations

**Note:** Assistive Technologies with braille support can convert the accessible names to Braille.
 Therefore, only use `aria-braillelabel` when the accessible name is not the user experience you want.

Using only the accessible name, e.g., from content or via `aria-label` is almost always the better user experience, so don't use aria-braillelabel to replicate aria-label. Only use `aria-braillelabel` if the accessible name cannot provide an adequate braille representation.

```html
<button aria-braillelabel="\*\*\*">
  <img alt="3 out of 5 stars" src="three\_stars.png" />
</button>
```

A braille display may display "btn \*\*\*" in Braille rather than the more verbose "btn gra 3 out of 5 stars".

Values
------

`<string>`

The value is a string, an unconstrained value type, that is intended to be converted into Braille.

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

Used in **ALL** roles.

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

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

See Also
--------

* `aria-label`
* `aria-brailleroledescription`


aria-readonly - Accessibility

aria-readonly
=============

The `aria-readonly` attribute indicates that the element is not editable, but is otherwise operable.

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

When you want to indicate that an interactive element works but is not editable, set `aria-readonly="true"`. This indicates to the user that an interactive element that would normally be focusable and copyable has been placed in a read-only (not disabled) state.

When `aria-readonly` is set to `true`, it means the user can read but not set the value of the widget. Read-only elements are still relevant to the user, so you should not prevent the user from navigating to the element or its focusable descendants or copying the value.

Examples include:

* Form elements which should not be changed.
* Row and column headers in a spreadsheet.
* The total value in a shopping cart.

If the non-changeable value shouldn't be able to receive focus, use `aria-disabled` instead.

**Note:** When using semantic HTML form controls, if you set the `readonly` attribute, you don't need to include `aria-readonly="true"`.

**Note:** The value of `<input type="checkbox">` can not be edited making `readonly` not relevant. However, when creating checkboxes with `role="checkbox"` the `aria-readonly` attribute *is* supported.

Values
------

`true`

The element is readonly.

`false` (default)

The element is not readonly.

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

`Element.ariaReadOnly`

The `ariaReadOnly` property, part of the `Element` interface, reflects the value of the `aria-readonly` attribute.

`ElementInternals.ariaReadOnly`

The `ariaReadOnly` property, part of the `ElementInternals` interface, reflects the value of the `aria-readonly` attribute.

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

Used in roles:

* `checkbox`
* `combobox`
* `grid`
* `gridcell`
* `listbox`
* `radiogroup`
* `slider`
* `spinbutton`
* `textbox`

Inherited into roles:

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

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

See Also
--------

* HTML `readonly` attribute
* `aria-disabled`


Perceivable - Accessibility

Perceivable
===========

This article provides practical advice on how to write your web content so that it conforms to the success criteria outlined in the **Perceivable** principle of the Web Content Accessibility Guidelines (WCAG) 2.0 and 2.1. Perceivable states that users must be able to perceive it in some way, using one or more of their senses.

**Note:** To read the W3C definitions for Perceivable and its guidelines and success criteria, see Principle 1: Perceivable - Information and user interface components must be presentable to users in ways they can perceive.

Guideline 1.1 — Providing text alternatives for non-text content
----------------------------------------------------------------

The key here is that text can be converted to other forms that people with disabilities can use. For example, it can be spoken by a screen reader, converted to large print, or represented on a braille display. Non-text content refers to multimedia such as images, audio, and video.

| Success criteria | How to conform to the criteria | Practical resource |
| --- | --- | --- |
| 1.1.1 Provide text equivalents (A) |
 All images that convey meaningful content should be given suitable
 alternative text.
  | Text alternatives. |
|
 Complex images or charts should have an accessible alternative provided,
 either on the same page or via a link. Use a regular link instead of
 a `longdesc` attribute.
  |
 A text description may work, or an accessible data table (see
 HTML table advanced features and accessibility). See
 Other text alternative mechanisms
 for the argument against `longdesc`.
  |
|
 Multimedia content (i.e., audio or video) should at least have a
 descriptive identification available, such as a caption or similar.
  |
 See Text alternatives
 for static caption options, and
 Audio transcripts,
 Video text tracks, and
 Other multimedia content
 for other alternatives.
  |
|
 UI controls such as form elements and buttons should have text labels
 that describe their purpose.
  |
 Buttons are simple—you should make sure the button text describes the
 function of the button (e.g., `<button>Upload image</button>`). For more information on other UI controls, see
 UI controls.
  |
|
 Implement decorative (non-content) images, video, etc., in a way that is
 invisible to assistive technology, so it doesn't confuse users.
  |
 Decorative images should be implemented using CSS background images
 (see
 Backgrounds). If you have to include an image via an
 `<img>` element, give it a blank alt
 (`alt=""`). Otherwise, screen readers may try to read out
 the filepath, etc.

 If you are including background video or audio that autoplays, make it
 as unobtrusive as possible. Don't make it look/sound like content, and
 provide a control to turn it off. Ideally, don't include it at all.
  |

**Note:** Also see the WCAG description for Guideline 1.1: Text alternatives.

Guideline 1.2 — Providing text alternatives for time-based media
----------------------------------------------------------------

Time-based media refers to multimedia with a duration, such as audio and video. Note that if the audio/video serves as an alternative to existing text content, you don't need to provide another text alternative.

| Success criteria | How to conform to the criteria | Practical resource |
| --- | --- | --- |
| 1.2.1 Provide alternatives for pre-recorded audio-only and video-only content (A) | A transcript should be provided for prerecorded audio-only media, and a transcript or audio description should be provided for prerecorded video-only media (i.e., silent video). | See Audio transcripts for transcript information. No audio description tutorial is available yet. |
| 1.2.2 Provide captions for web-based video (A) | You should provide captions for video presented on the web (e.g., HTML video). This is for the benefit of people who can't hear the audio part of the video. | See Video text tracks for HTML video captions, and Other multimedia content for other technologies. See also Add your own subtitles & closed captions (YouTube). |
| 1.2.3 Provide text transcript or audio description for web-based video (A) | You should provide text transcripts or audio descriptions for video presented on the web (e.g., HTML video. This is for the benefit of people who can't see the visual part of the video, and don't get the full content from the audio alone. | See Audio transcripts for transcript information. No audio description tutorial is available yet. |
| 1.2.4 Provide captions for live audio (AA) | You should provide synchronized captions for all live multimedia that contains audio (e.g., video conferences, live audio broadcasts). |  |
| 1.2.5 Provide audio descriptions for prerecorded video (AA) | Audio descriptions should be provided for prerecorded video, but only where the existing audio does not convey the full meaning expressed by the video. |  |
| 1.2.6 Provide sign language equivalent to prerecorded audio (AAA) | An equivalent sign language video should be provided for any prerecorded content containing audio. |  |
| 1.2.7 Provide extended video with audio descriptions (AAA) | Where audio descriptions cannot be provided (see 1.2.5) due to video timing issues (e.g., there are no suitable pauses in the content in which to insert the audio descriptions), an alternative version of the video should be provided that includes inserted pauses (and audio descriptions). |  |
| 1.2.8 Provide an alternative for prerecorded media (AAA) | For all content that features video, a descriptive text transcript should be provided, for example a script of the movie you are watching. This is for the benefit of hearing-impaired viewers who cannot hear the content. | See Audio transcripts for transcript information. |
| 1.2.9 Provide a transcript for live audio (AAA) | For any live audio content being broadcast, a descriptive text should be provided, for example a script of the play or musical you are listening to. This is for the benefit of hearing-impaired viewers who cannot hear the content. | See Audio transcripts for transcript information. |

**Note:** Also see the WCAG description for Guideline 1.2: Time-based Media: Provide alternatives for time-based media.

Guideline 1.3 — Create content that can be presented in different ways
----------------------------------------------------------------------

This guideline refers to the ability of content to be consumed by users in multiple ways, accommodating their differing needs.

| Success criteria | How to conform to the criteria | Practical resource |
| --- | --- | --- |
| 1.3.1 Info and relationships (A) |
 Any content structure—or visual relationship made between content—can
 also be determined programmatically, or be inferred from text
 description. The main situations in which this is relevant are:
 * Text labels and the form elements they describe. These are
 associated unambiguously using the `<label>`
 element, which can be picked up by screen readers, etc.
* Image alt text. Content images should have text available that
 clearly describes the image's contents, which can be
 programmatically associated with it (e.g., `alt` text),
 or otherwise is easy to associate (e.g., describes it and is sat
 right next to it). This should mean that the full meaning can still
 be inferred even if you can't see the image.
* Lists. If the order of list items is important, use an ordered list
 (`<ol>`).
 | The whole of

HTML: A good basis for accessibility
 is packed with information about this, but you should particularly
 refer to
 Good semantics,
 UI controls, and
 Text alternatives.
  |
| 1.3.2 Meaningful content sequence (A) |
 A sensible, logical reading order should be easy to determine for any
 content, even if it is visually presented in an unusual way. The order
 should be made obvious by use of correct semantic elements (e.g.,
 headings, paragraphs), with CSS being used to create any unusual layout
 styles, irrespective of the markup.
  |
 Again, refer to
 HTML: A good basis for accessibility.
  |
| 1.3.3 Sensory characteristics (A) |
 Instructions for operating controls or understanding content do not
 rely on a single sense. This may prove inaccessible to people with a
 disability related to that sense, or a device that does not support
 that sense. So, for example:
 * "Click the round button to continue"The button should be
 clearly labelled so that it is obvious that it is the button you
 need to press. If there are multiple buttons, make sure they are all
 clearly labelled to distinguish their function.
* "Listen to the audio instructions for guidance"This is
 obviously problematic—audio will be inaccessible to those with
 hearing impairments, whereas text can be read, but also spoken by a
 screen reader if required.
* "Swipe from the right-hand side of the screen to reveal the menu"Some
 users might not be able to swipe the screen, either due to
 disability or because their device does not support touch. An
 alternative should be provided, such as a keyboard shortcut or
 button that can be activated by keyboard or other means.

**Note:** Conveying instructions solely by color is
 related, but covered in a different guideline — 1.4.1.

 |  |
|
 1.3.4 Orientation (AA)
 *added in 2.1* |
 Content does not restrict its view and operation to a single display
 orientation, such as portrait or landscape, unless a specific display
 orientation is essential.
  | Understanding Orientation |
| 1.3.5 Identify Input Purpose (AA) *added in 2.1* |
 Follow the list of
 53 input fields
 to programmatically identify the purpose of a field.
  | Understanding Identify Input Purpose |
| 1.3.6 Identify Purpose (AAA) *added in 2.1* |
 In content implemented using markup languages, the purpose of user
 interface components, icons, and regions can be programmatically
 determined.
  | Understanding Identify Purpose |

**Note:** Also see the WCAG description for Guideline 1.3: Adaptable: Create content that can be presented in different ways without losing information or structure.

Guideline 1.4: Make it easier for users to see and hear content including separating foreground from background
---------------------------------------------------------------------------------------------------------------

This guideline relates to making sure core content is easy to discern from backgrounds and other decoration. The classic example is color (both color contrast and use of color to convey instructions), but it applies in other situations too.

| Success criteria | How to conform to the criteria | Practical resource |
| --- | --- | --- |
| 1.4.1 Use of color (A) |
 Color should not be solely relied upon to convey information. For
 example, in forms, you should never mark required fields purely with a
 color (like red). Instead (or as well as), something like an asterisk
 with a label of "required" would be more appropriate.
  |
 See
 Color and color contrast
 and
 Multiple labels.
  |
| 1.4.2 Audio controls (A) |
 For any audio that plays for longer than three seconds, provide
 accessible controls to play and pause the audio/video, and mute/adjust
 volume.
  |
 Use native `<button>`s to provide accessible keyboard
 controls, as shown in
 Video player styling basics.
  |
| 1.4.3 Minimum contrast (AA) |
 The color contrast between background and foreground content should be
 at a minimum level to ensure legibility:
 * Text and its background should have a contrast ratio of at least
 4.5:1.
* Heading (or just larger) text should have a ratio of at least 3:1.
 Larger text is defined as at least 18pt, or 14pt bold.
 |
 See
 Color and color contrast.
  |
| 1.4.4 Resize text (AA) |
 The page should be readable and usable when the text size is doubled.
 This means that designs should be responsive, so that when the text size
 is increased, the content is still accessible.
  |  |
| 1.4.5 Images of text (AA) |
 Images should NOT be used to present content where text would do the
 job. For example, if an image is mostly textual, it could be represented
 using text as well as images.
  |  |
| 1.4.6 Enhanced contrast (AAA) | This follows, and builds on, criterion 1.4.3.* Text and its background should have a contrast ratio of at least
 7:1.
* Heading (or just larger) text should have a ratio of at least 4.5:1.
 Larger text is defined as at least 18pt, or 14pt bold.
 |
 See
 Color and color contrast.
  |
| 1.4.7 Low or no background audio (AAA) |
 Prerecorded audio recordings that primarily feature speech should have
 minimal background noise, so the content can be easily understood.
  |  |
| 1.4.8 Visual presentation (AAA) | For text content presentation, the following should be true:* Foreground and background colors should be user-selectable.
* Text blocks should be no wider than 80 characters (or glyphs), for
 maximum readability.
* Text should not be fully justified (e.g., `text-align: justify;`).
* Line height should be at least 1.5 times the text size within
 paragraphs (e.g., `line-height: 1.5;`), and at least 2.25
 times the text size between paragraphs (e.g., `padding: 2.25rem;`).
* When the text size is doubled, the content should not need to be
 scrolled.
 |  |
| 1.4.9 Images of text (No Exception) (AAA) |
 Text should not be presented as part of an image unless it is purely
 decoration (i.e., it does not convey any content) or cannot be presented
 in any other way.
  |  |
| 1.4.10 Reflow (AA) *added in 2.1* | * No horizontal scrolling for left-to-right languages (like English)
 or right-to-left languages (like Arabic)
* No vertical scrolling for top-to-bottom languages (like Japanese)
* Except for parts of the content which require two-dimensional layout
 for usage or meaning (like a large data table)
 | Understanding Reflow |
| 1.4.11 Non-Text Contrast(AA) *added in 2.1* |
 Minimum color contrast ratio of 3:1 for user interface components and
 graphical objects.
  | Understanding Non-Text Contrast |
| 1.4.12 Text Spacing (AA) *added in 2.1* |
 No loss of content or functionality occurs when the following styles
 are applied:
 * Line height (line spacing) to at least 1.5 times the font size
* Spacing following paragraphs to at least 2 times the font size
* Letter spacing (tracking) to at least 0.12 times the font size
* Word spacing to at least 0.16 times the font size
 | Understanding Text Spacing |
| 1.4.13 Content on Hover or Focus (AA) *added in 2.1* |
 While additional content may appear and disappear in coordination with
 hover and keyboard focus, this success criterion specifies three
 conditions that must be met:
 * dismissible (can be closed/removed)
* hoverable (the additional content does not disappear when the
 pointer is over it)
* persistent (the additional content does not disappear without user
 action)
 | Understanding Content on Hover or Focus |

**Note:** Also see the WCAG description for Guideline 1.4: Distinguishable: Make it easier for users to see and hear content including separating foreground from background.

See also
--------

* WCAG
    1. Perceivable
    2. Operable
    3. Understandable
    4. Robust