Info and Examples for Accessibility Insights

/info-examples


Interactive `<area>` elements (those with a valid `href` or which have been made focusable and interactive by use of the `tabindex` attribute and scripting) must have alternative text.

## Why it matters

An image map is a single image with multiple selectable areas. People with good vision can infer the purpose of each clickable area from its visual aspects. People who use screen readers or other assistive technologies rely on alternative text to communicate the purpose of each area.

## How to fix

Provide alternative text for each `<area>` element using ONE of the following methods.

Good

-   `title` attribute

Better

-   `aria-label`

Best

-   `aria-labelledby` attribute
-   `alt` attribute

## Example

<PassFailGrid>
<FailSection>

An image map of a business's locations is comprised of three `<area>` elements, each representing a business location.
The `<area>` elements do not have any alternative text. When an assistive technology user selects an `<area>`, its `href` value might (or might not) be announced. In any case, the `href` value isn't helpful.

</FailSection>
<FailExample example={`<p>Select a location to see our business hours:</p>
<img src="locations.png" width="800" height="400" alt="Map of business locations" usemap="#locations-map">
<map name="locations-map">
[<area shape="rect" coords="0,0,200,400" href="location1.htm">
<area shape="rect" coords="0,0,400,400" href="location2.htm">
<area shape="rect" coords="0,0,600,400" href="location3.htm">]
</map>`} />
<PassSection>

Each `<area>` element has an `alt` attribute that identifies its corresponding business location. All users have the information they need to make an informed selection.

</PassSection>
<PassExample example={`<p>Select a location to see our business hours:</p>
<img src="locations.png" width="800" height="400" alt="Map of business locations" usemap="#locations-map">
<map name="locations-map">
<area shape="rect" coords="0,0,200,400" [alt="Corporate headquarters"] href="location1.htm">
<area shape="rect" coords="0,0,400,400" [alt="Elm Street store"] href="location2.htm">
<area shape="rect" coords="0,0,600,400" [alt="Maple Street store"] href="location3.htm">
</map>`} />
</PassFailGrid>

## About this rule

This rule passes if ANY of the following is true:

-   Element has a non-empty `alt` attribute
-   Element has an `aria-labelledby` attribute that references an element or elements containing text
-   Element has a non-empty `aria-label` attribute
-   Element has a non-empty `title` attribute

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html">
        Understanding Success Criterion 4.1.2: Name, Role, Value
    </HyperLink>
</Links>


/info-examples/web/area-alt


Elements must use only ARIA attributes allowed for their implicit or explicit ARIA role.

## Why it matters

An ARIA `role` attribute can be added to various HTML elements to instruct assistive technologies to expose the element as something other than its native HTML element type. For example, an `<a>` element with `role="button"` is to be exposed as a button, not a link.  **Note:** modifying an element's role will only change how it is exposed to assistive technology. Any additional functional changes to an element (to either add expected behaviors, or supress native ones), must be separately made by web developers, typically via scripting.

Some ARIA _property_ and _state_ attributes are allowed only for certain ARIA roles.
When an assistive technology encounters a mismatch between an element's role and its state or property attributes, it might ignore attributes or respond in an unexpected way.
As a result, people who use assistive technologies might find the element difficult or impossible to use.

## How to fix

1. Identify the [ARIA role](https://www.w3.org/TR/wai-aria/#roles_categorization) that best identifies the element’s purpose, function, or both.
1. Examine the element in the [Chrome](https://developers.google.com/web/tools/chrome-devtools/accessibility/reference#pane) or [Edge](https://docs.microsoft.com/en-us/microsoft-edge/devtools-guide/elements/accessibility) accessibility pane to verify that it has the correct role attribute.
1. Use only ARIA _state_ and _property_ attributes that are allowed for the given role.
1. Make sure the value of each ARIA _property_ attribute is an accurate and valid value.
1. Make sure the value of each ARIA _state_ attribute updates as needed to reflect the element’s current state.

## Example

<PassFailGrid>
<FailSection>

This `<button>` element has an ARIA role attribute (`role="option"`). This role overrides the implicit `button` role, and instead communicates to assistive technologies to expose the `<button>` as a selectable item in a listing of options (i.e., `role="listbox"`).
However, the element also has an ARIA state attribute (`aria-pressed="true"`). This attribute is allowed for buttons, but is not a valid attribute for options. Because browsers may not expose incorrect attributes for roles, and some assistive technologies ignore mismatched ARIA attributes, users likely won't know whether this custom option is selected.

</FailSection>
<FailExample example={`<button [role="option" aria-pressed="true"] id="available">Available items</button>`} />
<PassSection>

Instead, use the correct ARIA state attribute (`aria-selected`) for the `option` role. Set to `true` in the selected state, and `false` when not selected.
The attribute's value is updated through scripting (not shown) to ensure it correctly communicates the current state to assistive technologies.

</PassSection>
<PassExample example={`<button role="option" [aria-selected="true"] id="available">Available items</button>`} />
</PassFailGrid>

## About this rule

This rule passes if ALL of the following are true:

-   ARIA attribute is used correctly for the implicit or explicit role of the element
-   ARIA attribute is widely supported by browsers and assistive technologies

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/parsing.html">Understanding Success Criterion 4.1.1: Parsing</HyperLink>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html">
        Understanding Success Criterion 4.1.2: Name, Role, Value
    </HyperLink>
    <HyperLink href="https://www.w3.org/TR/wai-aria/#roles_categorization">
        Accessible Rich Internet Applications (WAI-ARIA) 1.2: Categorization of Roles
    </HyperLink>
    <HyperLink href="https://www.w3.org/TR/html-aria/">ARIA in HTML: ARIA Roles, States, and Properties allowed per HTML element</HyperLink>
</Links>


/info-examples/web/aria-allowed-attr


Elements must use only ARIA roles appropriate for that element.  

## Why it matters 

An [ARIA role](https://www.w3.org/TR/wai-aria/#roles_categorization)  attribute can be added to an element to instruct assistive technologies to expose the element as something other than its native HTML element type. For example, an `<a>` element with `role="button"` is to be exposed as a button, not a link. 

Some ARIA roles are only appropriate to specify on certain elements. The reason for this is that some HTML elements have have what's referred to as "strong native semantics" - meaning that these elements have implicit ARIA semantics and features which can contradict, or cause uncertain behaviors for AT when developers specify ARIA roles on elements which do not share these native semantics. As a result, people who use assistive technologies might find the element difficult or impossible to use, **or** the explicitly set role may be entirely ignored to mitigate the contradictory semantics the developer has specified.  

## How to fix 
1. Examine the element in the [Chrome](https://developer.chrome.com/docs/devtools/#pane) or [Edge](https://learn.microsoft.com/en-us/archive/microsoft-edge/legacy/developer/) accessibility pane to verify that it has the correct role attribute. 

2. As necessary, review the [ARIA in HTML specification](https://w3c.github.io/html-aria/#docconformance) to see which roles are allowed on specific HTML elements.

3. Identify the [ARIA role](https://www.w3.org/TR/wai-aria/#roles_categorization) that best identifies the element’s function.  

4. Assign a valid [ARIA role](https://www.w3.org/TR/wai-aria/#roles_categorization) if needed.  
_Note: Some ARIA roles, while technically valid, are not widely supported by assistive technologies._

## Example

<PassFailGrid>
<FailSection>

This button has an `article` role which is not appropriate as buttons are interactive elements and articles are not. As such, people who use assistive technologies will not be able to effectiely interact with it, as its functionality will be obscured to them. 

</FailSection>
<FailExample example={`<button role="article" >I really am a button</button>  `} />
<PassSection>

Removing the `role=”article”` from the button ensures everyone can correctly interact with the element.  

</PassSection>
<PassExample example={`<button >I am a button</button> `} />
</PassFailGrid>

## About this rule 

This rule passes if ALL of the following are true: 
- Elements with explicit role attributes have values that are both valid ARIA roles, and the role is allowed on the element to which it is specified.  
- The role is widely supported in screen readers and other assistive technologies.

## More Examples
[Accessible Rich Internet Applications (WAI-ARIA) 1.2: Categorization of Roles](https://www.w3.org/TR/wai-aria/#roles_categorization) 

[ARIA in HTML: ARIA Roles, States, and Properties allowed per HTML element](https://www.w3.org/TR/html-aria/)

[Understanding Success Criterion 4.1.2: Name, Role, Value](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html)

[Understanding Success Criterion 1.3.1: Info and Relationships](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships)


/info-examples/web/aria-allowed-role


ARIA buttons, links, and menuitems must have accessible names.

## Why it matters

ARIA buttons and links are custom controls corresponding respectively to HTML `<button>`, and `<a>` elements with valid `href` attributes. There is no `<menuitem>` element in HTML as it has been deprecated.
An accessible name is a word or phrase coded in a way that assistive technologies can associate it with a specific user interface object. Assistive technologies can then refer to the object by name, not just by type.
When an ARIA button, link, or menuitem doesn't have an accessible name, people who use assistive technologies will have no way of knowing its purpose.

## How to fix

For each element with `"role="button"`, `role="link"`, or `role="menuitem"`, provide an accessible name using one of the following methods.

Good

-   `title` attribute

Better

-   `aria-label` attribute
-   `aria-labelledby` attribute

Best

-   Inner text that’s available to assistive technologies (_not_ marked with `display: none` or `aria-hidden="true"`)

## Example

<PassFailGrid>
<FailSection>

This ARIA button, based on an `<a>` element, displays an icon of a speaker to communicate the button's function. Because purely visual content is not accessible to people who use assistive technologies, they can't determine the button's purpose.

</FailSection>
<FailExample example={`<a tabindex="0" role="button" id="mute" aria-pressed="false">
<svg aria-hidden="true" focusable="false">
<use xlink:href="images/mute.svg#icon-sound">
</use>
</svg>
</a>
`} />
<PassSection>

Visible inner text is added to the `<a>` element, giving the button an accessible name. Its purpose is communicated to everyone.

</PassSection>
<PassExample example={`<a tabindex="0" role="button" id="mute" aria-pressed="false">[Mute]
<svg aria-hidden="true" focusable="false">
<use xlink:href="images/mute.svg#icon-sound">
</use>
</svg>
</a>
`} />
</PassFailGrid>

## About this rule

This rule passes if ANY of the following is true:

-   Element has inner text that is visible to screen readers
-   Element has an `aria-labelledby` attribute that references an element or elements containing text
-   Element has a non-empty `aria-label` attribute
-   Element has a non-empty `title` attribute

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html">
        Understanding Success Criterion 4.1.2: Name, Role, Value
    </HyperLink>
</Links>


/info-examples/web/aria-command-name


Elements with ARIA roles must be checked so that they’re used properly as intended with content.

## Why it matters

Using ARIA attributes when they aren’t expected to be used can result in confusing behavior for assistive technology.  Using ARIA specifications makes it so people with disabilities can use those technologies and properly get the intended meaning of the content.

## How to fix
For checkboxes you can do two things:  
-	Make sure that `aria-checked` is removed, and an HTML checkbox can be used by setting its `indeterminate` property.  
-	Replace the native HTML checkbox with a different element.
  
Note: Make sure the HTML checkbox is provided with a role and is keyboard accessible.  

For `tr` elements and where the role is a `row`, you may need to change the role of the parent `table` or `grid` to a `treegrid`.  

## Example
<PassFailGrid>
<FailSection>

The `aria-checked` rule is listed as `true` and that makes it so that element isn't changed when the checkbox is activated.  Also the `row` elements for the ARIA attributes are used as a part of a `table` and should be used as a `treegrid`. 

</FailSection>
<FailExample example={`<input type="checkbox" [aria-checked="true"]>

[<div role="table">]
        <div role="row" aria-expanded="false">...</div>
        <div role="row" aria-posinset="1">...</div>
        <div role="row" aria-setsize="10">...</div>
        <div role="row" aria-level="1">...</div>
</div> `} />

<PassSection>

The `aria-checked label` was removed for the checkbox and was changed to a different element.  The parent element is a `treegrid` element for the ARIA `row` elements  

</PassSection>
<PassExample example={`{<input type="checkbox" checked}>

[<div role="treegrid">]
        <div role="row" aria-expanded="false">...</div>
        <div role="row" aria-posinset="1">...</div>
        <div role="row" aria-setsize="10">...</div>
        <div role="row" aria-level="1">...</div>
</div> `} />
</PassFailGrid>

## About this rule
This is when the rule passes for `aria-checked`:
- It’s not used on an HTML input element where a type is a checkbox
-	Browsers ignore `aria-checked`

This is when the rule passes for 'row' elements:
-	`aria-posinsert`, `aria-setsize`, `aria-expanded`, and `aria-level` for example are only used when `row` is a part of `treegrid`

## More examples

<Links>
  <HyperLink href="https://dequeuniversity.com/rules/axe/4.8/aria-conditional-attr">ARIA attributes must be used as specified for the element’s role</HyperLink>
  
  <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html">4.1.2 Name, Role, Value</HyperLink>
</Links>


/info-examples/web/aria-conditional-attr


All values corresponding to ARIA roles must not be deprecated or abstract.

## Why it matters
Using deprecated ARIA roles will make it so those elements aren’t recognized, and it won’t be correctly processed by screen readers or other assistive technology.  As a result, people may not be able to access essential information.

## How to fix

Consider using a `list` role instead, as it is the most equivalent role to the deprecated `directory` role.

## Example
<PassFailGrid>
<FailSection>

A `div` element has been given the role of `directory`, which is a deprecated role and should not be used by developers.

</FailSection>
<FailExample example={`[<div role="directory]">
  </div>`} />

<PassSection>

The `div` is meant to represent a list of content, so rather than the deprecated `directory` role, it is given a valid role of `list`

</PassSection>
<PassExample example={`[<div role="list"]>
  </div>`} />
</PassFailGrid>

## About this rule

This rule passes if any of the values assigned to ARIA role attribute aren’t deprecated or abstract.  Deprecated roles are roles which the ARIA spec no longer recommends that authors use, and abstract roles are specifically for user agent implementation, and must never used by web authors.

## More examples

<Links>
    <HyperLink href="https://dequeuniversity.com/rules/axe/4.8/aria-deprecated-role">Depreciated ARIA roles must not be used</HyperLink>

    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html">4.1.2 Name, Role, Value</HyperLink>
</Links>


/info-examples/web/aria-deprecated-role


The attribute `aria-hidden="true"` must not be used on the `<body>` element.

## Why it matters

In some browsers, the attribute `aria-hidden="true"` hides an element and all its children from assistive technologies.
Users can still use the keyboard to navigate to any focusable child elements in the `<body>`, but their content is inaccessible to people who use assistive technologies. For example, screen readers are silent.

## How to fix

1. Remove `aria-hidden="true"` from the `<body>` element.
1. Use `aria-hidden="true"` only on elements whose content is decorative or redundant from the perspective of people who use assistive technologies.
   Note that adding `aria-hidden="false"` to an element whose parent has `aria-hidden="true"` would not reveal it to assistive technologies.

## Example

<PassFailGrid>
<FailSection>

A web page includes a modal dialog. In an attempt to hide the underlying page content when the dialog is open, the attribute `aria-hidden="true"` is added to the `<body>` element.
As a result, all page content – including the modal dialog – is hidden from assistive technology users.

</FailSection>
<FailExample example={`<body class="has-dialog" [aria-hidden="true"]>
…
<button class="action-button">Sign in</button>
…`} />
<PassSection>

The attribute `aria-hidden="true"` is never applied to the `<body>` element.
Instead, when the dialog is open, elements outside the dialog are removed from the tab order

</PassSection>
<PassExample example={`<body class="has-dialog">
…
<button class="action-button" [tabindex="-1"]>Sign in</button>
…
`} />
</PassFailGrid>

## About this rule

This rule passes if:

-   No `aria-hidden` attribute is present on the document `<body>` element

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html">
        Understanding Success Criterion 4.1.2: Name, Role, Value
    </HyperLink>
</Links>


/info-examples/web/aria-hidden-body


Elements with `aria-hidden="true"` must not contain focusable elements.

## Why it matters

In some browsers, the attribute `aria-hidden="true"` hides an element and all its children from assistive technologies.
Users can still use the keyboard to navigate to any focusable child elements, but their content is inaccessible to people who use assistive technologies. For example, screen readers are silent. (An element is focusable if it can receive input focus via scripting, mouse interaction, or keyboard tabbing.)

## How to fix

Make sure elements with `aria-hidden="true"` do not contain focusable elements using one or more of the following methods.

-   Use `aria-hidden="true"` only on elements whose content is decorative or redundant from the perspective of people who use assistive technologies.
-   Restructure the code so the focusable elements are not children of the hidden element.
-   Where appropriate, make the child elements non-focusable (by applying the `disabled` attribute) or non-tabbable (by applying `tabindex="-1"`).
-   Where appropriate, hide elements from all users by applying `hidden`, `display:none`, or `visibility:hidden` attributes.

## Example

<PassFailGrid>
<FailSection>

An alert is positioned off-screen and marked with `aria-hidden="true"` until it’s needed. However, the alert contains an **OK** button that remains focusable even when the alert is hidden.
Keyboard users can tab to the button, but they can’t to tell what it is.

</FailSection>
<PassSection>

When the alert is positioned off-screen, its `OK` button is marked with `tabindex="-1"`.
Keyboard users encounter the button only when the alert is on-screen.

</PassSection>
</PassFailGrid>

## About this rule

This rule passes if ANY of the following are true:

-   Element with `aria-hidden="true"` contains no focusable elements
-   Element with `aria-hidden="true"` contains only focusable elements that are disabled or not tabbable

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html">
        Understanding Success Criterion 4.1.2: Name, Role, Value
    </HyperLink>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html">
        Understanding Success Criterion 1.3.1: Info and Relationships
    </HyperLink>
</Links>


/info-examples/web/aria-hidden-focus


ARIA input fields must have accessible names.

## Why it matters

An ARIA input field is a custom control that allows users to provide text input. ARIA input fields are identified by the following ARIA roles:

-   combobox
-   listbox
-   searchbox
-   slider
-   spinbutton
-   textbox

An accessible name is a word or phrase coded in a way that assistive technologies can associate it with a specific user interface object.
Assistive technologies can then refer to the object by name, not just by type. Unlike a standard HTML control, an ARIA input field requires additional markup to ensure it has an accessible name that conveys its purpose to users of assistive technologies.

## How to fix

Provide an accessible name for each ARIA input field using ONE of the following methods.

Good

-   `title`

Better

-   `aria-label`

Best

-   `aria-labelledby`

## Example

<PassFailGrid>
<FailSection>

Although visible text precedes this listbox, the text is not programmatically associated with the listbox.
As a consequence, the listbox does not have an accessible name. People who use assistive technologies don’t know the purpose of the listbox.

</FailSection>
<FailExample example={`<span>Select a service level:</span>
[<ul id="option_list" tabindex="0" role="listbox">]
<li id="service1" role="option">Level 1</li>
<li id="service2" role="option">Level 2</li>
<li id="service3" role="option">Level 3</li>
</ul>
`} />
<PassSection>

An `aria-labelledby` attribute is used to make the visible text into an accessible name. Everyone knows its purpose.

</PassSection>
<PassExample example={`<span [id="select_level"]>Select a service level:</span>
<ul id="option_list" tabindex="0" role="listbox" [aria-labelledby="select_level"]>
<li id="service1" role="option">Level 1</li>
<li id="service2" role="option">Level 2</li>
<li id="service3" role="option">Level 3</li>
</ul>
`} />
</PassFailGrid>

## About this rule

This rule passes if:

-   ANY of the following are true:
    -   Element has an `aria-labelledby` attribute that references elements that are visible to screen readers
    -   Element has a non-empty `aria-label` attribute
    -   Element has a non-empty `title` attribute
-   AND the following is true:
    -   There is no mismatch between the element’s `<label>` and its accessible name

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html">
        Understanding Success Criterion 4.1.2: Name, Role, Value
    </HyperLink>
</Links>


/info-examples/web/aria-input-field-name


ARIA meters must have accessible names.

## Why it matters

An ARIA meter is a custom control corresponding to the HTML `<meter>` element. A meter represents either a scalar value within a known range, or a fractional value. For example, a meter might represent the unused portion of total storage capacity.
An accessible name is a word or phrase coded in a way that assistive technologies can associate it with a specific user interface object. Assistive technologies can then refer to the object by name, not just by type.
When an ARIA meter doesn't an accessible name, people who use assistive technologies have no way of knowing its purpose.

## How to fix

For each element with `role="meter"`, provide an accessible name using one of the following methods.

Good

-   `title` attribute

Better

-   `aria-label` attribute

Best

-   `aria-labelledby` attribute referencing visible text

## Example

<PassFailGrid>
<FailSection>

A `<div>` element is coded to function as an ARIA meter. A `<label>` element is used in attempt to give the meter an accessible name. Although a `<label>` can be used with a `<meter>` element, its use with `<div>` elements is not supported, and so no programmatic association is made between the `<label>` and the `<div>`. Because the ARIA meter does not have an accessible name, people who use assistive technologies can't tell its purpose.

</FailSection>
<FailExample example={`[<label for "disk-usage-meter">]Disk Usage[</label>]
<[div id="disk-usage-meter"] role="meter" aria-valuenow="90" aria-valuemin="0" aria-valuemax="100">
<svg width="100" height="100" class="fill"  aria-hidden="true" version="1.1" xmlns="http://www.w3.org/2000/svg">
<rect x="0" y="0" width="100%" height="100%" fill="currentColor">
</rect>
</svg>
</div>
`} />
<PassSection>

The `<label>` element is replaced with a `<p>` element, and a programmatic association is created by an aria-labelledby attribute on the `<div>`. The ARIA meter has an accessible name that's available to all users.

</PassSection>
<PassExample example={`[<p id="disk-usage-label">]Disk Usage[</p>]
<div role="meter" aria-valuenow="90" aria-valuemin="0" aria-valuemax="100" [aria-labelledby="disk-usage-label"]>
<svg width="100" height="100" class="fill"  aria-hidden="true" version="1.1" xmlns="http://www.w3.org/2000/svg">
<rect x="0" y="0" width="100%" height="100%" fill="currentColor">
</rect>
</svg>
</div>
`} />
</PassFailGrid>

## About this rule

This rule passes if ANY of the following is true:

-   Element has an `aria-labelledby` attribute that references elements that are visible to screen readers
-   Element has a non-empty `aria-label` attribute
-   Element has a non-empty `title` attribute

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html">
        Understanding Success Criterion 1.1.1: Non-text Content
    </HyperLink>
</Links>


/info-examples/web/aria-meter-name


ARIA progressbars must have accessible names.

## Why it matters

An ARIA progressbar is a custom control corresponding to the HTML `<progress>` element. A progressbar represents progress on a task that takes a long time to complete.
An accessible name is a word or phrase coded in a way that assistive technologies can associate it with a specific user interface object. Assistive technologies can then refer to the object by name, not just by type.
When an ARIA progressbar doesn't an accessible name, people who use assistive technologies have no way of knowing its purpose.

## How to fix

For each element with `role="progressbar"`, provide an accessible name using one of the following methods.

Good

-   `title` attribute

Better

-   `aria-label` attribute

Best

-   `aria-labelledby` attribute referencing visible text

## Example

<PassFailGrid>
<FailSection>

A `<div>` element is coded to function as an ARIA progressbar. A `<label>` element is used in attempt to give the progressbar an accessible name. Although a `<label>` can be used with a `<progress>` element, its use with `<div>` elements is not supported, and so no programmatic association is made between the `<label>` and the `<div>`. Because the ARIA progressbar does not have an accessible name, people who use assistive technologies can't tell its purpose.

</FailSection>
<FailExample example={`[<label for "progressbar">]Creating your video[</label>]
<[div id="progressbar"] role="progressbar" aria-valuenow="90" aria-valuemin="0" aria-valuemax="100">
<svg width="100" height="100" class="fill"  aria-hidden="true" version="1.1" xmlns="http://www.w3.org/2000/svg">
<rect x="0" y="0" width="100%" height="100%" fill="currentColor">
</rect>
</svg>
</div>
`} />
<PassSection>

The `<label>` element is replaced with a `<p>` element, and a programmatic association is created by an aria-labelledby attribute on the `<div>`. The ARIA meter has an accessible name that's available to all users.

</PassSection>
<PassExample example={`[<p id="progressbar-label">]Disk Usage[</p>]
<div role="meter" aria-valuenow="90" aria-valuemin="0" aria-valuemax="100" [aria-labelledby="progressbar-label"]>
<svg width="100" height="100" class="fill"  aria-hidden="true" version="1.1" xmlns="http://www.w3.org/2000/svg">
<rect x="0" y="0" width="100%" height="100%" fill="currentColor">
</rect>
</svg>
</div>
`} />
</PassFailGrid>

## About this rule

This rule passes if ANY of the following is true:

-   Element has an `aria-labelledby` attribute that references elements that are visible to screen readers
-   Element has a non-empty `aria-label` attribute
-   Element has a non-empty `title` attribute

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html">
        Understanding Success Criterion 1.1.1: Non-text Content
    </HyperLink>
</Links>


/info-examples/web/aria-progressbar-name


Elements with implicit or explicit ARIA roles (e.g., `<p>` or `<div role="paragraph">`) must not be provided ARIA attributes which are listed as prohibited for use with specified role, as identified in the ARIA specifications.

## Why it matters

Using prohibited ARIA attributes with specific roles can result in important information not being communicated to people using assistive technologies.  In certain situations it can also result in wrong or unexpected information being communicated to them.

## How to fix
If the information that is meant to be conveyed by the attribute is important, then instead of removing the prohibited attribute you can do one of three things:
-	Change the role to one on which the attribute is not prohibited (so long as the new role is appropriate for the element/content that is being presented to the user)
-	Remove the attribute and instead provide the information as text in the page
-	Move the attribute to a different element that does support it

## Example
<PassFailGrid>
<FailSection>

The `aria-label` attribute is used on a paragraph element (which has an implicit `paragraph` role) for "Shipping Instructions.  This is a text-based role which prohibits author naming (e.g., use of `aria-label` and `aria-labelledby`).    

</FailSection>
<FailExample example={`<p [aria-label="Shipping instructions:"] ></p>
    <h3 id="shipping">Shipping instructions:</h3>
    <div [aria-labelledby="shipping]">...</div>` } />

<PassSection>

The `aria-label` and `aria-labelledby` attributes aren't used on a text-based role.  

</PassSection>
<PassExample example={`<p>[Shipping instructions:]</p>
    <div>Shipping instructions:</div>
    <h3>Shipping instructions:</h3><div>...</div>`} />
</PassFailGrid>

## About this rule

This is an example of when the rule passes:
-`aria-label` and `aria-labelledby` attributes aren’t used on `presentation` and `none` roles, `generic` roles or equivalent elements (e.g., a `<div>` has an implicit `generic` role) on text-based roles such as `paragraph`, `code`, `insertion`, or `strong`.

## More examples

<Links>
  <HyperLink href="https://dequeuniversity.com/rules/axe/4.8/aria-prohibited-attr">Elements must only use permitted ARIA attributes</HyperLink>
  
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html">4.1.2 Name, Role, Value</HyperLink>
</Links>


/info-examples/web/aria-prohibited-attr


Required ARIA attributes must be provided.

## Why it matters

An ARIA _role_ attribute can be added to an element to instruct assistive technologies to treat the element as something other than its native HTML element type.
For example, an `<a>` element with `role="button"` is to be treated as a button, not a link.

Some ARIA _role_ attributes require additional ARIA attributes to communicate the control’s _properties_ or current _state_. People who use assistive technologies might find it difficult or impossible to use an element that’s missing a required ARIA attribute.

## How to fix

1. Identify the [ARIA role](https://www.w3.org/TR/wai-aria/#roles_categorization) that best identifies the element’s function.
1. Examine the element in the [Chrome](https://developers.google.com/web/tools/chrome-devtools/accessibility/reference#pane) or [Edge](https://docs.microsoft.com/en-us/microsoft-edge/devtools-guide/elements/accessibility) accessibility pane to verify that it has the correct _role_ attribute.
1. Apply any ARIA _state_ and _property_ attributes that are required for the given role.
1. Make sure the value of each ARIA _property_ attribute is correct.
1. Make sure the value of each ARIA _state_ attribute updates as needed to reflect the element’s current state.

For a list of roles and their required attributes, see [ARIA in HTML: ARIA Roles, States, and Properties](https://www.w3.org/TR/html-aria/#aria-table).

## Example

<PassFailGrid>
<FailSection>

This `<div>` element ha an ARIA _role_ attribute ( `role="checkbox"` ) that correctly identifies it to assistive technologies as a checkbox. However, the `aria-checked` _state_ attribute required for that role is missing.
People who use assistive technologies can’t tell whether the checkbox is checked.

</FailSection>
<FailExample example={`<div [role="checkbox"] tabindex="0">Keep me signed in</div>
`} />
<PassSection>

The `aria-checked` attribute has been added to the element.
The attribute’s value is updated through scripting (not shown) to ensure it always communicates the correct current state to assistive technologies.

</PassSection>
<PassExample example={`<div role="checkbox" [aria-checked="false"] tabindex="0">Keep me signed in</div>`} />
</PassFailGrid>

## About this rule

This rule passes if:

-   All ARIA attributes required for the given role are present

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/parsing.html">Understanding Success Criterion 4.1.1: Parsing</HyperLink>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html">
        Understanding Success Criterion 4.1.2: Name, Role, Value
    </HyperLink>
    <HyperLink href="https://www.w3.org/TR/html-aria/">ARIA in HTML: ARIA Roles, States, and Properties</HyperLink>
</Links>


/info-examples/web/aria-required-attr


Certain ARIA roles must contain particular children.

## Why it matters

An ARIA _role_ attribute can be added to an element to instruct assistive technologies to treat the element as something other than its native HTML element type.
For example, a `<ul>` element with `role="listbox"` is to be treated as a listbox control, not as a static list.

Some ARIA "parent" roles have [Required Owned Elements](https://www.w3.org/TR/wai-aria/#mustContain). These "parent" roles identify composite controls that always include only managed controls, identified by "child" roles.
For example, `role="listbox"` identifies a composite control that manages a set of managed controls identified by `role="option"`.
People who use assistive technologies might find it difficult or impossible to use a composite control if its managed controls lack the required child role or if it contains unexpected types of children.

## How to fix

1. Identify the [ARIA role](https://www.w3.org/TR/wai-aria/#roles_categorization) that best identifies the element’s function.
1. In the [Chrome](https://developers.google.com/web/tools/chrome-devtools/accessibility/reference#pane) or [Edge](https://docs.microsoft.com/en-us/microsoft-edge/devtools-guide/elements/accessibility) accessibility pane, examine the element serving as the _managing_ control to verify it has the correct "parent" _role_ attribute.
1. Identify the elements serving as _managed_ controls and add the appropriate "child" roles to them.
1. Remove any child elements of the _managing_ control which are not serving as _managed_ controls.
1. Apply any ARIA _state_ and _property_ attributes that are required for the given roles.
1. Make sure the value of each ARIA _property_ attribute is correct.
1. Make sure the value of each ARIA _state_ attribute updates as needed to reflect the element’s current state.

For details about composite widgets and their required roles, see [WAI-ARIA Authoring Practices 1.1: Design Patterns and Widgets](https://www.w3.org/TR/wai-aria-practices-1.1/#aria_ex).

## Example

<PassFailGrid>
<FailSection>

This code functions together as a list control. The _managing_ `<div>` element has the correct "parent" role (`listbox`), but the _managed_ `<div>` elements are missing the required "child" role (`option`). Additionally, the _managing_ `<div>` element has a child element that should not be present (`h3`).

</FailSection>
<FailExample example={`<div [role="listbox"] aria-labelledby="size"   
id="rg1">
<h3 id="size">T-shirt size:</h3>
<div tabindex="0">Small</div>
<div tabindex="-1">Medium</div>
<div tabindex="-1">Large</div>
</div>
`} />
<PassSection>

The children of the `listbox` parent which represent listbox-managed controls are marked with `role="option"`.
In addition, an attribute required by the `listitem` role (`aria-selected`) has been added to each list item. These attribute values are updated through scripting (not shown) to ensure they always communicate the correct current state to assistive technologies. 

</PassSection>
<PassExample example=
{`<h3 id="size">T-shirt size:</h3>
<div role="listbox" aria-labelledby="size"  >
<div [role="option" aria-selected="false"] tabindex="0">Small</div>
<div [role="option" aria-selected="true"] tabindex="-1">Medium</div>
<div [role="option" aria-selected="false"] tabindex="-1">Large</div>
</div>
`} />
</PassFailGrid>

## About this rule

This rule passes if ALL of the following are true:

- At least one child has an ARIA role which is one of the parent ARIA role's [Required Owned Elements](https://www.w3.org/TR/wai-aria/#mustContain).
- All children either:
  - have an ARIA role which is one of the parent ARIA role's [Required Owned Elements](https://www.w3.org/TR/wai-aria/#mustContain), OR
  - Are not present in the browser's accessibility tree

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html">
        Understanding Success Criterion 1.3.1: Info and Relationships
    </HyperLink>
</Links>


/info-examples/web/aria-required-children


Certain ARIA roles must be contained by particular parent elements.

## Why it matters

An ARIA _role_ attribute can be added to an element to instruct assistive technologies to treat the element as something other than its native HTML element type.
For example, an `<li>` element with `role="option"` is to be treated as a selectable option in a listbox control, not as a static list item.

Some ARIA "child" roles identify managed controls that are always part of a larger composite control, identified by a "parent" role.
For example, `role="option"` identifies a child control that is managed by a parent control identified by `role="listbox"`. People who use assistive technologies might find it difficult or impossible to use a child control if its managing control lacks the required parent role.

## How to fix

1. Identify the [ARIA role](https://www.w3.org/TR/wai-aria/#roles_categorization) that best identifies the element’s function.
1. In the [Chrome](https://developers.google.com/web/tools/chrome-devtools/accessibility/reference#pane) or [Edge](https://docs.microsoft.com/en-us/microsoft-edge/devtools-guide/elements/accessibility) accessibility pane, examine the elements serving as the _managed_ controls to verify they have the correct "child" _role_ attributes.
1. Identify (or add) the element serving as the _managing_ control and add the appropriate "parent" role to it.
1. Apply any ARIA _state_ and _property_ attributes that are required for the given roles.
1. Make sure the value of each ARIA _property_ attribute is correct.
1. Make sure the value of each ARIA _state_ attribute updates as needed to reflect the element’s current state.

For details about composite widgets and their required roles, see [WAI-ARIA Authoring Practices 1.1: Design Patterns and Widgets](https://www.w3.org/TR/wai-aria-practices-1.1/#aria_ex).

## Example

<PassFailGrid>
<FailSection>

This code functions together as a menu (composite) control. The managed `<a>` elements have the correct "child" roles ( `menuitem` ), but the managing `<ul>` element is missing the required "parent" role ( `menu` or `menubar` ).
Because assistive technologies can’t identify this code as a menu, some users don’t know how to interact with it.

</FailSection> 
<FailExample example={`[<ul id="myaccount">]
<li>
<a [role="menuitem"] href="#" tabindex="0">Profile</a>
<li>
<a [role="menuitem"] href="#" tabindex="0">Preferences     </a>
</li>
</ul>
`} />
<PassSection>

The parent of the `menuitem` children is marked with `role="menu"`. Assistive technologies can inform users that the managing control is a menu.
In addition, the menu has been given an accessible name by adding an `aria-label` attribute to the parent element. All `<li>` elements should be marked with `role="none"` to remove the implied `listitem` role.

</PassSection>
<PassExample example={`<ul id="myaccount" [role="menu" aria-label="My Account"]>
<li [role="none"]>
<a role="menuitem" href="#" tabindex="0">Profile</a>
<li [role="none"]>
<a role="menuitem" href="#" tabindex="0">Preferences     </a>
</li>
</ul>
`} />
</PassFailGrid>

## About this rule

This rule passes if:

-   Required ARIA parent is present

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html">
        Understanding Success Criterion 1.3.1: Info and Relationships
    </HyperLink>
</Links>


/info-examples/web/aria-required-parent


The `aria-roledescription` attribute must be used only on elements with a supported role. This rule has been deprecated for axe-core 4.7.0 release and has been disabled. A revised rule may be released in a future version of axe-core.

## Why it matters

The `aria-roledescription` attribute is used to override how assistive technologies report an element’s role. For example, assistive technologies typically report a `<button>` element (or a `<div>` with `role="button"` ) as a "button".
If `aria-roledescription="slider button"` were added to either element, assistive technologies would report it instead as a "slider button".

Assistive technologies report an element’s role only when the role is semantic (has inherent meaning). For example, they inform users when they encounter links, buttons, or images, but not when they encounter semantically neutral elements, such as `<span>` or `<div>` or `<p>` elements.
The `aria-roledescription` changes only _how_ an element’s role is reported, not necessarily _whether_ it’s reported. An assistive technology might not announce a semantically neutral element, even if it has an `aria-roledescription` attribute.
As a result, people who use assistive technologies might not discover such an element exists.

## How to fix

Use `aria-roledescription` only on elements that have an explicit or implicit ARIA role.

-   An _implicit_ ARIA role is derived from the element itself. For example, a `<button>` element has an implicit role of button.
    For a list of HTML elements and their implicit roles, see [ARIA in HTML](https://www.w3.org/TR/html-aria/). (Elements noted as having "No corresponding role" have no implicit ARIA role.)
-   You can add an _explicit_ ARIA role using the `role` attribute. For example, adding `role="button"` to a `<div>` element changes its role to button.

## Example

<PassFailGrid>
<FailSection>

This custom control is coded on a semantically neutral `<div>` element, and no explicit role has been applied.
Although scripting (not shown) causes the element to function as a button, assistive technologies might not report the element to users.

</FailSection>
<FailExample example={`<[div] tabindex="0" [aria-roledescription="download button"]>Download</div>
`} />
<PassSection>

An explicit ARIA role is applied using `role="button"`. Assistive technologies announce the element because it has a semantic role.
The `aria-roledescription` attribute instructs assistive technologies to identify the element to users as a "download button."

</PassSection>
<PassExample example={`<div [role="button"] tabindex="0" aria-roledescription="download button">Download</div>`} />
</PassFailGrid>

## About this rule

This rule passes if:

-   `aria-roledescription` is used on an element with a semantic role

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html">
        Understanding Success Criterion 4.1.2: Name, Role, Value
    </HyperLink>
    <HyperLink href="https://www.w3.org/TR/html-aria/">ARIA in HTML</HyperLink>
</Links>


/info-examples/web/aria-roledescription


ARIA roles must have valid values.

## Why it matters

An ARIA `role` attribute can be added to an element to instruct assistive technologies to treat the element as something other than its native HTML element type.
For example, an `<a>` element with `role="button"` will be treated as a button, not as a link.

When an assistive technology encounters an element whose `role` attribute has an invalid value, it might ignore the element or respond to it in an unexpected way.
As a result, people who use assistive technologies might find the element difficult or impossible to detect or use.

## How to fix

Provide a valid value for the `role` attribute:

-   Make sure the value is spelled correctly.
-   Make sure the role value exists. (For example, a common mistake is to specify the invalid role `"footer"` when the valid role is `"contentinfo"`.)
-   Make sure the role is not abstract.

For a list of valid ARIA roles, see [Accessible Rich Internet Applications (WAI-ARIA) 1.1: Categorization of Roles](https://www.w3.org/TR/wai-aria-1.1/#roles*categorization).
Note that some ARIA roles, while technically _valid_, are not widely _supported_ by assistive technologies. This rule will fail when such roles are used.

## Example

<PassFailGrid>
<FailSection>

The children of this `radiogroup` have invalid `role` attribute values.
Assistive technologies can’t report their roles and might not report the elements at all.

</FailSection>
<FailExample example={`<div role="radiogroup" aria-labelledby="size" id="rg1">
<h3 id="size">T-shirt size:</h3>
<div [role="radiobutton"] aria-checked="false" tabindex="0">Small</div>
<div [role="radiobutton"] aria-checked="false" tabindex="-1">Medium</div>
<div [role="radiobutton"] aria-checked="false" tabindex="-1">Large</div>
</div>
`} />
<PassSection>

The children have valid `role` attribute values. Assistive technologies can report the elements as radio buttons.

</PassSection>
<PassExample example={`<div role="radiogroup" aria-labelledby="size" id="rg1">
<h3 id="size">T-shirt size:</h3>
<div [role="radio"] aria-checked="false" tabindex="0">Small</div>
<div [role="radio"] aria-checked="false" tabindex="-1">Medium</div>
<div [role="radio"] aria-checked="false" tabindex="-1">Large</div>
</div>
`} />
</PassFailGrid>

## About this rule

This rule passes if ALL of the following are true:

-   ARIA role is valid
-   ARIA role is not an abstract role
-   The role is widely supported in screen readers and other assistive technologies

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html">
        Understanding Success Criterion 1.3.1: Info and Relationships
    </HyperLink>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html">
        Understanding Success Criterion 4.1.2: Name, Role, Value
    </HyperLink>
</Links>


/info-examples/web/aria-roles


ARIA toggle fields must have accessible names.

## Why it matters

An ARIA toggle field is a custom control that allows users to toggle its checked value.
ARIA toggle fields are identified by the following ARIA `role` attributes:

-   checkbox
-   menuitemcheckbox
-   menuitemradio
-   radio
-   switch

An accessible name is a word or phrase coded in a way that assistive technologies can associate it with a specific user interface object.
Assistive technologies can then refer to the object by name, not just by type.
Unlike a standard HTML control, an ARIA toggle field requires additional markup to ensure it has an accessible name that conveys its purpose to users of assistive technologies.

## How to fix

Provide an accessible name for each ARIA toggle field using ONE of the following methods.

Good

-   `title` attribute

Better

-   `aria-label` attribute
-   `aria-labelledby` attribute

Best

-   Inner text that’s available to assistive technologies (_not_ marked with `display: none` or `aria-hidden="true"` )
-   `<label>` element (applies only to controls based on form elements)

## Example

<PassFailGrid>
<FailSection>

This code (together with scripting that isn't shown) functions as a switch. A `<label>` element is used in an attempt to give the switch an accessible name. However, the `<label>` element is valid HTML only when used with form elements, so no programmatic association has been made between the `<span>` and `<label>` elements.
As a result, the switch has no accessible name, and people who use assistive technologies don't know its purpose.

</FailSection>
<FailExample example={`[<label for="dark-theme">]Dark theme</label>
<[span id="dark-theme"] type role="switch" aria-checked="false" tabindex="0"></span>
`} />
<PassSection>

The `<label>` element is changed to a `<p>` with an `id`, and the `<span>` is given an `aria-labelledby` attribute that refers to the `id` of the `<p>`.
A programmatic association between the `<span>` and `<p>` elements is successfully created, so the switch has an accessible name.
Assistive technologies can tell users that the switch toggles the dark theme.

</PassSection>
<PassExample example={`[<p id="dark-label">]Dark theme</p>
<span id="dark-theme" role="switch" aria-checked="false" tabindex="0" [aria-labelledby="dark-label"]></span>
`} />
</PassFailGrid>

## About this rule

This rule passes if:

-   ANY of the following are true:

    -   Element has a non-empty `aria-label` attribute
    -   Element has an `aria-labelledby` attribute that references elements that are visible to screen readers
    -   Element has a non-empty `title` attribute
    -   Element has text that is visible to screen readers

-   AND the following is true:
    -   There is no mismatch between the element’s `<label>` and its accessible name

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html">
        Understanding Success Criterion 1.3.1 Info and Relationships
    </HyperLink>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html">
        Understanding Success Criterion 4.1.2: Name, Role, Value
    </HyperLink>
</Links>


/info-examples/web/aria-toggle-field-name


ARIA tooltips must have accessible names.

## Why it matters

An ARIA tooltip is a contextual popup with text describing an interface element. The tooltip typically becomes visible when the mouse hovers over, or focus is received by, the owning element.
An accessible name is a word or phrase coded in a way that assistive technologies can associate it with a specific user interface object. Assistive technologies can then refer to the object by name, not just by type.
When an ARIA tooltip doesn't an accessible name, people who use assistive technologies have no way of knowing its purpose.

## How to fix

For each element with `role="tooltip"`, provide an accessible name using one of the following methods.

Good

-   `title` attribute

Better

-   `aria-label` attribute
-   `aria-labelledby` attribute referencing visible text

Best

-   Visible inner text that's available to assistive technologies (not marked with `display:none` or `aria-hidden="true"`)

## Example

<PassFailGrid>
<FailSection>

The `<p>` element is intended to serve as a tooltip for a button. However, through an oversight, the `<p>` element is empty. The tooltip won't be visible to any user. As a result, only people who can see the icon can tell the purpose of the button.

</FailSection>
<FailExample example={`<button type="button" aria-describedby="description">
<span role="img" aria-label="Settings">⚙️</span>
</button>
[<p id="description" role="tooltip"></p>]
`} />
<PassSection>

Text is added to the `<p>` element, giving it an accessible name. Everyone can tell that the button allows you to edit your settings.

</PassSection>
<PassExample example={`<button type="button" aria-describedby="description">
<span role="img" aria-label="Settings">⚙️</span>
</button>
<p id="description" role="tooltip">[Edit your settings]</p>
`} />
</PassFailGrid>

## About this rule

This rule passes if ANY of the following is true:

-   Element has inner text that is visible to screen readers
-   Element has an `aria-labelledby` attribute that references elements that are visible to screen readers
-   Element has a non-empty `aria-label` attribute
-   Element has a non-empty `title` attribute

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html">
        Understanding Success Criterion 4.1.2: Name, Role, Value
    </HyperLink>
</Links>


/info-examples/web/aria-tooltip-name


ARIA attributes must have valid values.

## Why it matters

When an assistive technology encounters an element with an invalid ARIA attribute value, it might ignore the attribute or respond to it in an unexpected way.

As a result, people who use assistive technologies might find the element difficult or impossible to use.

## How to fix

Provide a valid value for each ARIA attribute:

-   Make sure you are using the correct type of value. (For example, some attributes allow only "true" or "false" values, while others allow the value to remain undefined.)
-   Make sure the value is spelled correctly.
-   Consider whether the attribute has a default value that must be modified in order to be valid in the current context.
-   If the attribute references an ID, make sure the ID exists on the page.

For details about all ARIA attributes, including their allowed values, see [Accessible Rich Internet Applications (WAI-ARIA) 1.1: Definitions of States and Properties](https://www.w3.org/TR/wai-aria-1.1/#state_prop_def).

## Example

<PassFailGrid>
<FailSection>

This radio button has an `aria-checked` attribute with an invalid value of `"no"`.
Because assistive technologies are likely to ignore the invalid value, some users won't know whether the radio button is checked.

</FailSection>
<FailExample example={`<div role="radio" [aria-checked="no"] tabindex="0">Small</div>
`} />
<PassSection>

The `aria-checked` attribute has a valid value of `"false"`.
Assistive technologies can inform users that the radio button is currently unchecked.

</PassSection>
<PassExample example={`<div role="radio" [aria-checked="false"] tabindex="0">Small</div>
`} />
</PassFailGrid>

## About this rule

This rule passes if the following is true:

-   ARIA attribute values are valid

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/parsing.html">Understanding Success Criterion 4.1.1: Parsing</HyperLink>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html">
        Understanding Success Criterion 4.1.2: Name, Role, Value
    </HyperLink>
</Links>


/info-examples/web/aria-valid-attr-value


ARIA attributes must have valid names.

## Why it matters

When an assistive technology encounters an element with an invalid ARIA attribute name, it might ignore the attribute or respond to it in an unexpected way.
As a result, people who use assistive technologies might find the element difficult or impossible to use.

## How to fix

Provide a valid name for each ARIA attribute:

-   Make sure you are using the correct attribute name.
-   Make sure the attribute name is spelled correctly.

For details about all ARIA attributes, see [Accessible Rich Internet Applications (WAI-ARIA) 1.1: Definitions of States and Properties](https://www.w3.org/TR/wai-aria-1.1/#state_prop_def).

## Example

<PassFailGrid>
<FailSection>

This toggle button has an invalid ARIA attribute name.
Because assistive technologies are likely to ignore the attribute, some users won't know the button's state.

</FailSection>
<FailExample example={`<a tabindex="0" role="button" id="toggle" [aria-on]="true">Mute</a>
`} />
<PassSection>

The toggle button has a valid ARIA attribute name.
Assistive technologies can inform users that the button is currently pressed.

</PassSection>
<PassExample example={`<a tabindex="0" role="button" id="toggle" [aria-pressed="true"]>Mute</a>
`} />
</PassFailGrid>

## About this rule

This rule passes if:

-   ARIA attribute name is valid

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/parsing.html">Understanding Success Criterion 4.1.1: Parsing</HyperLink>
</Links>


/info-examples/web/aria-valid-attr


The `autocomplete` attribute must be used correctly.

## Why it matters

The HTML `autocomplete` attribute communicates the purpose of a form field specifically, consistently, and unambiguously to browsers and assistive technologies.

Autocomplete, when used correctly, enables browsers to suggest a form field’s value based on previous user input. Autocomplete makes it faster and easier for everyone to fill out forms.

Browsers can’t accurately suggest the value of an input field with a missing or invalid `autocomplete` attribute.
As a result, people will find it more burdensome to provide the expected input, especially people with cognitive disabilities.

## How to fix

For form fields which require data specifically related to user information, provide a valid `autocomplete` attribute value:

-   Make sure you are using the correct attribute value. (For example, `"family-name"` is valid, while `"last-name"` is not.)
-   Make sure the value is spelled correctly.
-   Make sure the value is allowed for the field type.

## Example

<PassFailGrid>
<FailSection>

This input field has an invalid `autocomplete` attribute value of `"first-name"`.
Browsers can't suggest a value, so users have to enter the value manually.

</FailSection>
<FailExample example={`<div>
<label for="fname">First Name</label>
<input id="fname" type="text" [autocomplete="first-name"]>
</div>
`} />
<PassSection>

The input field has a valid `autocomplete` attribute value of `"given-name"`.
Browsers can suggest a value for the field.

</PassSection>
<PassExample example={`<div>
<label for="fname">First Name</label>
<input id="fname" type="text" [autocomplete="given-name"]>
</div>
`} />
</PassFailGrid>

## About this rule

This rule passes if ALL of the following are true:

-   The `autocomplete` attribute is correctly formatted
-   The `autocomplete` value is appropriate for the input type

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/identify-input-purpose.html">
        Understanding Success Criterion 1.3.5: Identify Input Purpose
    </HyperLink>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Techniques/html/H98">Using HTML 5.2 autocomplete attributes</HyperLink>
</Links>


/info-examples/web/autocomplete-valid


Inline text spacing must be adjustable using custom stylesheets.

## Why it matters

People with low vision or dyslexia can find it difficult to read closely spaced text. An external CSS style sheet can be used to adjust text spacing and thereby improve the reading experience.
However, using `!important` in an inline CSS style causes external stylesheets to be ignored.

## How to fix

Remove `!important` from these inline style attributes:

-   `line-height`
-   `letter-spacing`
-   `word-spacing`

## Example

<PassFailGrid>
<FailSection>

An inline `line-height` style uses `!important` to enforce the specified value.
As a consequence, users can't increase the spacing using an external stylesheet. Some people find the text difficult to read.

</FailSection>
<FailExample example={`<p [style="line-height: 1.5 !important;]"> We the People of the United States, in Order to form a more perfect Union, 
establish Justice, insure domestic Tranquility, provide for the common defense, promote the general Welfare, 
and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America.</p>
`} />
<PassSection>

With `!important` removed, external stylesheets can adjust the `line-height` value. Users can choose the line spacing that works best for them.

</PassSection>
<PassExample example={`<p [style="line-height: 1.5]">We the People of the United States, in Order to form a more perfect Union, 
establish Justice, insure domestic Tranquility, provide for the common defense, promote the general Welfare, 
and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America.</p>
`} />
</PassFailGrid>

## About this rule

This rule passes if:

-   No inline styles that affect text spacing use `!important`

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/text-spacing.html">
        Understanding Success Criterion 1.4.12: Text Spacing
    </HyperLink>
</Links>


/info-examples/web/avoid-inline-spacing


The `<blink>` element is deprecated and must not be used.

## Why it matters

Text that blinks (alternates between visible and invisible states) can be distracting, especially for people with cognitive disabilities.
Blinking text can be difficult to read, especially for people with low vision or reading disabilities. And a blinking UI control can be difficult to activate, especially for people with limited dexterity.

## How to fix

1. Remove `<blink>` elements.
2. Consider using `<strong>` or `<em>` elements to emphasize important text.

## Example

<PassFailGrid>
<FailSection>

This paragraph contains a `<blink>` element. Its text content alternates between visibility and invisibility.
Some users will find it distracting or difficult to read.

</FailSection>
<FailExample example={`<p>This item is [<blink>New!</blink>]</p>
`} />
<PassSection>

The `<blink>` element has been replaced by a `<strong>` element.
Browsers and assistive technologies can communicate to users that the content is important.

</PassSection>
<PassExample example={`<p>This item is [<strong>New!</strong>]</p>
`} />
</PassFailGrid>

## About this rule

This rule passes if:

-   No `<blink>` element is visible

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/pause-stop-hide.html">
        Understanding Success Criterion 2.2.2: Pause, Stop, Hide
    </HyperLink>
</Links>


/info-examples/web/blink


All `<button>` elements must have accessible names.

## Why it matters

An accessible name is a word or phrase coded in a way that assistive technologies can associate it with a specific user interface object. Assistive technologies can then refer to the object by name, not just by type.
When a button doesn’t have an accessible name, people who use assistive technologies have no way of knowing its purpose.

## How to fix

For each `<button>` element, provide an accessible name using one of the following methods.

Good

-   `title` attribute

Better

-   `aria-label` attribute
-   `aria-labelledby` attribute referencing visible text

Best

-   Inner text that’s available to assistive technologies (_not_ marked with `display: none` or `aria-hidden="true"`)

## Example

<PassFailGrid>
<FailSection>

This button contains an image of binoculars to visually convey its purpose, but it doesn't have an accessible name.
People who use assistive technologies can't determine its purpose.

</FailSection>
<FailExample example={`<button id="find"><img src="find.jpg></button>
`} />
<PassSection>

Visible inner text gives the button an accessible name. Its purpose is communicated to everyone

</PassSection>
<PassExample example={`<button id="find"><img src="find.jpg>[Find]</button>
`} />
</PassFailGrid>

## About this rule

This rule passes if ANY of the following is true:

-   Element has inner text that is visible to screen readers
-   Element has an `aria-labelledby` attribute that references an element or elements containing text
-   Element has a non-empty `aria-label` attribute
-   Element has a non-empty `title` attribute
-   Element’s default semantics were overridden with `role="presentation"` or `role="none"` **and** the element was made disabled by use of the `disabled` attribute

Use caution when applying `role="presentation"` or `role="none"` to a `<button>` element.
These roles instruct assistive technologies to disregard the element’s implicit role without hiding its content from users. However, per ARIA's [Presentational Roles Conflict Resolution](https://www.w3.org/TR/wai-aria-1.2/#conflict_resolution_presentation_none), user agents MUST ignore the `presentation` or `none` role when used on a focuable element, such as a `<button>`. This is true even if the button were to be provided a `tabindex=-1`, as the element would still be focusable, though it would _not_ be in the page's tab order.  If one needs to truly hide the semantics and functionality of a `<button>` element, it would likely be easiest to use a different element instead.

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html">
        Understanding Success Criterion 4.1.2: Name, Role, Value
    </HyperLink>
    <HyperLink href="https://www.w3.org/TR/wai-aria-1.2/#conflict_resolution_presentation_none">
       Accessible Rich Internet Applications (WAI-ARIA): 1.2 Presentational Roles Conflict Resolution
    </HyperLink>
    <HyperLink href="https://www.w3.org/TR/using-aria/">Using ARIA: Use of Role=presentation or Role=none</HyperLink>
</Links>


/info-examples/web/button-name


Web pages must allow keyboard users to bypass repeated blocks of content.

## Why it matters

Web pages typically begin with blocks of content that repeat across multiple pages, such as banners and site navigation menus.
A person who uses a mouse can visually skim past that repeated content and access a link or other control within the primary content with a single click.

Similarly, a bypass mechanism allows keyboard users to navigate directly to the page’s main content.
Otherwise, reaching the primary content could require dozens of keystrokes. People with limited mobility could find this task difficult or painful, and people who use screen readers could find it tedious to listen as each repeated element is announced.

## How to fix

Provide a mechanism that allows keyboard users to bypass repeated blocks of text using one of the following methods.

Good

-   Landmark regions

Better

-   Headings

Best

-   Skip link

## Example

<PassFailGrid>
<FailSection>

A web page has no mechanism for users to bypass the banner content that appears at the top of the page.
It has no skip link, no headings, and no landmarks.

Keyboard users have to tab through numerous links in the site banner and navigation menus to get to the page's primary content.

</FailSection>
<FailExample example={`…
<html>
<head>
<style>
body {background-color: powderblue; …
</style>
</head>
<body>
<div class="sitebanner">…</div>
<div class="menubar">…</div>
<div class="main">…
`} />
<PassSection>

A skip link is added immediately after the page's `<body>` tag. Styling makes the skip link visible only when it has focus.
Mouse users are unaware of it, but all keyboard users can take advantage of it.
(Note that assistive technology users would still benefit from the addition of headings and landmarks.)

</PassSection>
<PassExample example={`…
<html>
<head>
<style>
body {background-color: powderblue; …
[#skip a {display: block; position: absolute; left: -999px; top: -999px;}
#skip a:focus {left: 0; top: 0; padding: 6px; background: #fff; border:1px solid #990000;}]
</style>
</head>
<body>
[<div id="skip">
<a href="#content">Skip to main content</a>
</div>]
<div class="sitebanner">…</div>
<div class="menubar">…</div>
<div class="main" [id="content"]>…
`} />
</PassFailGrid>

## About this rule

This rule passes if ANY of the following is true:

-   Valid skip link found
-   Page has a header
-   Page has a landmark region

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/bypass-blocks.html">
        Understanding Success Criterion 2.4.1: Bypass Blocks
    </HyperLink>
</Links>


/info-examples/web/bypass


Text elements must have sufficient contrast against the background.

## Why it matters

Most people find it easier to read text when it has a sufficiently high contrast against its background.
People with visual disabilities, low vision, limited color perception, or [presbyopia](https://en.wikipedia.org/wiki/Presbyopia) are likely to find text unreadable when contrast is too low.

## How to fix

Provide sufficient contrast for text elements.

A minimum contrast ratio of 3:1 is required for large text, defined as:

-   18pt (24 CSS pixels)
-   OR bold 14pt (19 CSS pixels)

A minimum contrast ratio of 4.5:1 is required for smaller text.

## Example

<PassFailGrid>
<FailSection>

In this page, `<h1>` elements are styled to have a foreground `color` of `#ee66cc` and a `font-size` of `48px`.
The font size qualifies the heading text as large. The contrast ratio of the text color against the page's white background is 2.843:1.
Because the minimum contrast ratio for large text is 3:1, the `<h1>` elements have insufficient contrast.
Some people will find the text difficult to read.

</FailSection>
<FailExample example={`<style>
…
h1 {[color: #ee66cc; font-size=48px]}
…
</style>
`} />
<PassSection>

The font color specified for `<h1>` elements provides a contrast of 3.762:1, which is sufficient for large text.
Most people will find it legible.

</PassSection>
<PassExample example={`<style>
…
h1 {[color: #ee22bb;] font-size=48px}
…
</style>
`} />
</PassFailGrid>

## About this rule

This rule passes if:

-   Element has sufficient contrast

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html">
        Understanding Success Criterion 1.4.3: Contrast (Minimum)
    </HyperLink>
</Links>


/info-examples/web/color-contrast


A `<dl>` element must directly contain only properly ordered `<dt>` and `<dd>` groups, `<script>`, or `<template>` elements.

## Why it matters

A definition list is a list of terms (words or phrases), and their definitions.
A definition list can contain only certain element types, and it requires a specific structure.

When an assistive technology encounters a definition list that’s poorly structured or contains invalid elements, it might respond in an unexpected way.
As a result, people who use assistive technologies might find it difficult to interpret the list.

## How to fix

Make sure each `<dl>` element is properly structured:

1. Each `<dl>` element must contain only `<dt>` , `<dd>` , `<script>` , and `<template>` elements.
2. Each `<dl>` element must contain one or more `<dt>` elements.
3. Each `<dt>` element must contain one or more `<dd>` elements.

## Example

<PassFailGrid>
<FailSection>

This definition list includes two `<img>` elements that aren't contained in `<dt>` or `<dd>` elements.
Assistive technologies can't determine whether the image is part of a term or its definition. They might present the list in a way that confuses users.

</FailSection>
<FailExample example={`<dl>
<dt>Coffee</dt>
[<img src="coffee.JPG" width="50" height="50" alt="A coffee plant with large green leaves and small red berries>]
<dd>A beverage prepared from the roasted seeds of various Coffea species.</dd>
<dt>Tea</dt>
[<img src="Tea.jpg" width="50" height="50" alt=
"A tea plant with small green leaves and white blossoms">]
<dd>A beverage prepared from the cured leaves of Camellia sinensis.</dd>
</dl>
`} />
<PassSection>

Each `<img>` element is contained within a `<dt>` element. Assistive technologies can correctly present the structure of the definition list.

</PassSection>
<PassExample example={`<dl>
[<dt>Coffee]
<img src="coffee.JPG" width="50" height="50" alt="A coffee shrub with large green leaves and small red berries">
[</dt>]
<dd>A beverage prepared from the roasted seeds of various Coffea species.</dd>
[<dt>Tea]
<img src="Tea.jpg" width="50" height="50" alt="A tea plant with small green leaves and white blossoms">
[</dt>]
<dd>A beverage prepared from the cured leaves of Camellia sinensis.</dd>
</dl>
`} />
</PassFailGrid>

## About this rule

This rule passes if:

-   When not empty, the `<dl>` element has both `<dt>` and `<dd>` elements
-   `<dl>` element has only direct children that are allowed inside `<dt>` or `<dd>` elements

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html">
        Understanding Success Criterion 1.3.1: Info and Relationships
    </HyperLink>
</Links>


/info-examples/web/definition-list


All `<dt>` and `<dd>` elements must be contained by a `<dl>` element.

## Why it matters

A definition list is a list of terms (words or phrases), and their definitions.
The `<dt>` and `<dd>` elements must be contained by a `<dl>` element.

When an assistive technology encounters a definition list that’s poorly structured, it might respond in an unexpected way.
As a result, people who use assistive technologies might find it difficult to interpret the list.

## How to fix

Contain all `<dt>` and `<dd>` elements in a `<dl>` element.

## Example

<PassFailGrid>
<FailSection>

These terms and definitions are not contained in a `<dl>` element. Assistive technologies might not present them as part of a definition list.

</FailSection>
<FailExample example={`<h3>Glossary</h3>
[<dt>Coffee</dt>
<dd>A beverage prepared from the roasted seeds of various Coffea species.</dd>
<dt>Tea</dt>
<dd>A beverage prepared from the cured leaves of Camellia sinensis.</dd>]
`} />
<PassSection>

The terms and definitions are contained in a `<dl>` element. Assistive technologies can present the list correctly.

</PassSection>
<PassExample example={`<h3>Glossary</h3>
[<dl>]
<dt>Coffee</dt>
<dd>A beverage prepared from the roasted seeds of various Coffea species.</dd>
<dt>Tea</dt>
<dd>A beverage prepared from the cured leaves of Camellia sinensis.</dd>
[</dl>]
`} />
</PassFailGrid>

## About this rule

This rule passes if:

-   `<dt>` or `<dd>` element has a parent `<dl>` element

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html">
        Understanding Success Criterion 1.3.1: Info and Relationships
    </HyperLink>
</Links>


/info-examples/web/dlitem


A web page must contain a `<title>` element that describes its topic or purpose.

## Why it matters

Typically, the first thing a user learns about a web page is its title. The title is displayed in the browser tab and in search engine results, and it’s announced by assistive technologies as soon as a user navigates to a page.
A descriptive page title helps everyone, especially users of assistive technologies, determine whether a page contains information relevant to their current needs.

## How to fix

Include a non-empty `<title>` element in the `<head>` section.

## Example

<PassFailGrid>
<FailSection>

This web page is missing the `<title>` element. Users can't whether the page contains relevant information until they examine it.

</FailSection>
<FailExample example={`<head>
<meta charset="UTF-8">
<link rel="stylesheet" type="text/css" href="https://mycompany.com/StyleSheets/home">
</head>
`} />
<PassSection>

The page's `<head>` section includes a descriptive `<title>` element.
Everyone has a quick way to judge whether the page contains relevant information.

</PassSection>
<PassExample example={`<head>
[<title>How to Contact My Company</title>]
<meta charset="UTF-8">
<link rel="stylesheet" type="text/css" href="https://mycompany.com/StyleSheets/home">
</head>
`} />
</PassFailGrid>

## About this rule

This rule passes if:

-   Document has a non-empty `<title>` element

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/page-titled.html">
        Understanding Success Criterion 2.4.2: Page Titled
    </HyperLink>
</Links>


/info-examples/web/document-title


Active, focusable elements must have unique `id` values.

## Why it matters

When multiple active, focusable elements share the same `id` attribute, both scripting (such as JavaScript) and assistive technologies are likely to act only on the first and ignore the others.
As a consequence, both functionality and accessibility can be degraded. (An element is _focusable_ if it can receive input focus via scripting, mouse interaction, or keyboard tabbing. It’s _active_ if it is not marked as `disabled`.)

## How to fix

Provide a unique `id` value for each active, focusable element.

## Example

<PassFailGrid>
<FailSection>

This web page has two search features, each with its own submit button.
Both buttons have the same `id` value. Scripting and assistive technologies might confuse the two buttons, with unpredictable results.

</FailSection>
<FailExample example={`<form id="site-search" role="search">
<p id="site-search-label">Search this site</p>
<input type="search" id="site-search-field" aria-labelledby="site-search-label" size="50">
<input type="submit" [id="search-submit"] value="Search">
</form>
…
<form id="page-search" role=" search">
<p id="page-search-label">Search this page</p>
<input type="search" id="page-search-field" aria-labelledby="page-search-label" size="50">
<input type="submit" [id="search-submit"] value="Search">
</form>
`} />
<PassSection>

Each submit button has a unique `id` value. Scripting and assistive technologies reliably treat them as separate entities.

</PassSection>
<PassExample example={`<form id="site-search" role="search">
<p id="site-search-label">Search this site</p>
<input type="search" id="site-search-field" aria-labelledby="site-search-label" size="50">
<input type="submit" [id="site-search-submit"] value="Search">
</form>
…
<form id="page-search" role=" search">
<p id="page-search-label">Search this page</p>
<input type="search" id="page-search-field" aria-labelledby="page-search-label" size="50">
<input type="submit" [id="page-search-submit"] value="Search">
</form>
`} />
</PassFailGrid>

## About this rule

This rule passes if:

-   Document has no active elements that share the same `id` attribute value

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/parsing.html">Understanding Success Criterion 4.1.1: Parsing</HyperLink>
</Links>


/info-examples/web/duplicate-id-active


Static elements must have unique `id` values.

## Why it matters

Duplicate `id` values are a common, easily fixed validation error that can cause both scripting (such as JavaScript) and assistive technologies to behave unexpectedly. Duplicate `id` values can degrade both functionality and accessibility.

## How to fix

Provide a unique `id` value for each element.

## Example

<PassFailGrid>
<FailSection>

Two static elements have the same `id` values. Scripting and assistive technologies might confuse the two elements, with unpredictable results.

</FailSection>
<FailExample example={`<form [id="search"] role="search">
<p id="site-search-label">Search this site</p>
…
<form [id="search"] role=" search">
<p id="page-search-label">Search this page</p>
`} />
<PassSection>

The elements have unique `id` values. Scripting and assistive technologies reliably treat them as separate entities.

</PassSection>
<PassExample example={`<form [id="site-search"] role="search">
<p id="site-search-label">Search this site</p>
…
<form [id="page-search"] role=" search">
<p id="page-search-label">Search this page</p>
`} />
</PassFailGrid>

## About this rule

This rule passes if:

-   Document has no static elements that share the same id attribute value

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/parsing.html">Understanding Success Criterion 4.1.1: Parsing</HyperLink>
</Links>


/info-examples/web/duplicate-id


`<frame>` and `<iframe>` elements with a negative tabindex (e.g. `tabindex="-1"`) must not have focusable content.

## Why it matters

`<frame>` and `<iframe>` elements with a negative tabindex are not keyboard focusable.
If there are interactive interface components inside them, people who rely on a keyboard (or a keyboard alternate), including those who are blind or have low vision or hand tremors, won't be able to access those components.

## How to fix

Remove the negative `tabindex` attribute from all `<frame>` and `<iframe>` elements that contain focusable content.

## Example

<PassFailGrid>
<FailSection>

An `<iframe>` contains interactive elements. Because the `<iframe>` has a negative tabindex, keyboard users can't access those elements.

</FailSection>
<FailExample example={`<iframe src="/interactive-form.html" [tabindex="-1"]>
…
</iframe>
`} />
<PassSection>

The `tabindex="-1"` attribute is removed from the `<iframe>`. All users can access the interactive elements inside the `<iframe>`.

</PassSection>
<PassExample example={`<iframe src="/interactive-form.html">
…

</iframe> `} />
</PassFailGrid>

## About this rule

This rule passes if ANY of the following is true:

-   `<frame>` and `<iframe>` elements with a negative tabindex (like `tabindex="-1"`) don't have focusable descendants.
-   `<frame>` and `<iframe>` elements with focusable descendants don't have a negative tabindex.

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/keyboard.html">Understanding Success Criterion 2.1.1: Keyboard</HyperLink>
</Links>


/info-examples/web/frame-focusable-content


A `<frame>` or `<iframe>` element must have an accessible name.

## Why it matters

A `<frame>` or `<iframe>` is used to embed one HTML document within another.
An accessible name is a word or phrase coded in a way that assistive technologies can associate it with a specific user interface object. Assistive technologies can then refer to the object by name, not just by type.

People with good vision can glance at a `<frame>` or `<iframe>` element to get a good idea of its content. People who use assistive technologies rely on the frame’s accessible name to determine whether it contains information relevant to their current needs.

## How to fix

For each `<frame>` or `<iframe>` element, provide an accessible name using ONE of the following methods.

Good

-   `title` attribute

Better

-   `aria-label` attribute

Best

-   `aria-labelledby` attribute

## Example

<PassFailGrid>
<FailSection>

This `<iframe>` element doesn't have an accessible name.
Assistive technology users won't have any idea what information the frame contains unless they navigate into its content.

</FailSection>
<FailExample example={`<iframe src="//articles/2019-11-14_new_characters.htm" frameborder="0" width="100%" height="32px" scrolling="no" allowtransparency="true">
…
</iframe>
`} />
<PassSection>

The `<iframe>` has a `title` attribute that gives it an accessible name.
Assistive technology users can judge from the name whether the frame is likely to have useful content.

</PassSection>
<PassExample example={`<iframe src="//articles/2019-11-14_new_characters.htm" [title="Introducing our new characters"] frameborder="0" width="100%" height="32px" scrolling="no" allowtransparency="true">
…
</iframe>
`} />
</PassFailGrid>

## About this rule

This rule passes if ANY of the following is true:

-   Element has a non-empty `aria-label` attribute
-   Element has an `aria-labelledby` attribute that references elements that are visible to screen readers
-   Element has a non-empty `title` attribute
-   Element’s default semantics were overridden with `role="presentation"` or `role="none"`

Use caution when applying `role="presentation"` or `role="none"` to a `<frame>` or `<iframe>` element. These roles instruct assistive technologies to disregard the element’s implicit role without hiding its content from users. If a `<frame>` or `<iframe>` has inner text, adding a `role` of `presentation` or `none` will cause it to be reported to users as a text string with no semantic context. For more information, see [Using ARIA: Use of Role=presentation or Role=none](https://www.w3.org/TR/using-aria/#presentation).

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html">
        Understanding Success Criterion 4.1.2: Name, Role, Value
    </HyperLink>
</Links>


/info-examples/web/frame-title


An `<html>` element must have a `lang` attribute.

## Why it matters

When a web page’s primary language is programmatically identified, browsers and assistive technologies can render the text more accurately; screen readers can use the correct pronunciation; visual browsers can display the correct characters; media players can show captions correctly; and automated translation is enabled.

All users find it easier to understand the page’s content.

## How to fix

1. Identify the page’s primary language.
2. Choose the corresponding a language code from the [IANA Language Subtag Registry](http://www.iana.org/assignments/language-subtag-registry)
3. Add a `lang` attribute to the `<html>` element using the correct language tag for the value that represents the primary language of the page.
4. If a `lang` attribute is already specified, make sure its value is spelled correctly.

## Example

<PassFailGrid>
<FailSection>

The content of a web page is written in Spanish. The `<html>` element doesn't have a `lang` attribute, so the browser assumes the primary language is English.
As a consequence, screen readers don't use the correct pronunciation, and users have a hard time understanding the content.

</FailSection>
<FailExample example={`<html>
`} />
<PassSection>

The `<html>` element has a `lang` attribute. It correctly identifies the primary language of the page as Spanish.
Screen reader users find the Spanish content easier to understand because it's pronounced correctly.

</PassSection>
<PassExample example={`<html [lang="es"]>
`} />
</PassFailGrid>

## About this rule

This rule passes if:

-   The `<html>` element has a `lang` attribute with a non-empty value.

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/language-of-page.html">
        Understanding Success Criterion 3.1.1: Language of Page
    </HyperLink>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Techniques/html/H57">Using language attributes on the html element</HyperLink>
    <HyperLink href="https://www.w3.org/International/articles/language-tags/">Language tags in HTML and XML</HyperLink>
    <HyperLink href="http://www.iana.org/assignments/language-subtag-registry">IANA Language Subtag Registry</HyperLink>
</Links>


/info-examples/web/html-has-lang


The `lang` attribute of an `<html>` element must have a valid value.

## Why it matters

When a web page’s primary language is programmatically identified, browsers and assistive technologies can render the text more accurately; screen readers can use the correct pronunciation; visual browsers can display the correct characters; media players can show captions correctly; and automated translation is enabled.

All users find it easier to understand the page’s content.

## How to fix

Provide a valid `lang` attribute value:

1. Identify the page’s primary language.
2. Choose the corresponding a language code from the [IANA Language Subtag Registry](http://www.iana.org/assignments/language-subtag-registry)
3. Make sure the value is spelled correctly.

## Example

<PassFailGrid>
<FailSection>

The content of a web page is written in Spanish. The `<html>` element has the wrong `lang` attribute for Spanish.
As a consequence, screen readers don't use the correct pronunciation, and users struggle to understand the content.

</FailSection>
<FailExample example={`<html [lang="sp"]>
`} />
<PassSection>

The `<html>` element has the correct `lang` attribute. It correctly identifies the primary language of the page as Spanish.
Screen reader users find the content easier to understand because it's pronounced correctly.

</PassSection>
<PassExample example={`<html [lang="es"]>
`} />
</PassFailGrid>

## About this rule

This rule passes if:

-   The `<html>` element’s `lang` attribute has a valid value

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/language-of-page.html">
        Understanding Success Criterion 3.1.1: Language of Page
    </HyperLink>
    <HyperLink href="https://www.w3.org/International/articles/language-tags/">Language tags in HTML and XML</HyperLink>
    <HyperLink href="http://www.iana.org/assignments/language-subtag-registry">IANA Language Subtag Registry</HyperLink>
</Links>


/info-examples/web/html-lang-valid


The `lang` and `xml:lang` attributes of an element must have the same value.

## Why it matters

When a web page’s primary language is programmatically identified, browsers and assistive technologies can render the text more accurately; screen readers can use the correct pronunciation; visual browsers can display the correct characters; and media players can show captions correctly.
All users find it easier to understand the page’s content.

All HTML web pages must have a `lang` attribute on the `<html>` element and additional `lang` attributes on any elements whose content is in a different language.
XHTML web pages and polyglot pages must also provide `xml:lang` attributes on those same elements.

When a single element has both `lang` and `xml:lang` attributes, the two values must match exactly.
When the two attributes have different values, the user experience is unpredictable.

## How to fix

For XHTML 1.x pages, or polyglot pages served as text/html:

1. Use both the `lang` attribute and the `xml:lang` attribute each time you specify the language.
2. Provide identical values for both attributes.

## Example

<PassFailGrid>
<FailSection>

The content of a web page is written primarily in Spanish.
The `<html>` element's `lang` attribute correctly identifies the primary language as Spanish, but its `xml:lang` attribute identifies it as English.

</FailSection>
<FailExample example={`<html [lang="es" xml:lang="en"]>
`} />
<PassSection>

Both the `lang` attribute and the `xml:lang` attribute correctly identify the primary language of the page as Spanish.
Screen reader users find the content easier to understand because it's pronounced correctly.

</PassSection>
<PassExample example={`<html [lang="es" xml:lang="es"]>
`} />
</PassFailGrid>

## About this rule

This rule passes if:

-   `Lang` and `xml:lang` attributes have identical values

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/language-of-page.html">
        Understanding Success Criterion 3.1.1: Language of Page
    </HyperLink>
    <HyperLink href="https://www.w3.org/International/questions/qa-when-xmllang.en">xml:lang in XML document schemas</HyperLink>
    <HyperLink href="https://www.w3.org/International/questions/qa-choosing-language-tags">Choosing a Language Tag</HyperLink>
</Links>


/info-examples/web/html-xml-lang-mismatch


An `<img>` element must have alternative text.

## Why it matters

Because assistive technologies can’t interpret an image directly, they rely on alternative text to communicate the image's meaning to users.
If an image has (non-empty) alternative text, the image is identified as meaningful, and its alternative text is presented to the user.
If an image has an empty `alt` attribute, the image is identified as decorative and ignored.
If an image has no alternative text at all, the image is presumed to be meaningful, and its filename is likely to be presented to the user.

## How to fix

1. Determine whether the image is meaningful or decorative:
    - An image is _meaningful_ if it conveys information that isn’t available through other page content.
    - An image is _decorative_ if it could be removed from the page with _no_ impact on meaning or function.
2. If the `<img>` element is decorative, provide an empty `alt` attribute ( `alt=""` ).
3. If the `<img>` element is meaningful, provide descriptive alternative text using one of the following methods:

    Good

    - `title` attribute

    Better

    - `aria-label`
    - `aria-labelledby` attribute

    Best

    - `alt` attribute

For tips on writing good text alternatives, see [Providing short text alternative for non-text content that serves the same purpose and presents the same information as the non-text content](https://www.w3.org/WAI/WCAG21/Techniques/general/G94).

## Example

<PassFailGrid>
<FailSection>

This image has no alternative text.
Assistive technologies identify the image by its file name, which isn't descriptive. Some users will have no idea what the image conveys.

</FailSection>
<FailExample example={`[<img src="191121131947-28-oak-ed-strike-1121-large-tease.jpg">]
`} />
<PassSection>

An `alt` attribute describes the image in a way that assistive technology users can easily understand.

</PassSection>
<PassExample example={`<img src="191121131947-28-oak-ed-strike-1121-large-tease.jpg" [alt="Teachers striking in front of the School District Headquarters"]>
`} />
</PassFailGrid>

## About this rule

This rule passes if ANY of the following is true:

1. Element has an `alt` attribute
2. Element has an `aria-labelledby` attribute that references elements that are visible to screen readers
3. Element has a non-empty `aria-label` attribute
4. Element has a non-empty `title` attribute
5. Element’s default semantics were overridden with `role="presentation"` or `role="none"`

Use caution when applying `role="presentation"` or `role="none"` to an `<img>` element. These roles instruct assistive technologies to disregard the element’s implicit role without hiding its content from users. If an `<img>` has inner text, adding a `role` of `presentation` or `none` will cause it to be reported to users as a text string with no semantic context.
For more information, see [Using ARIA: Use of Role=presentation or Role=none](https://www.w3.org/TR/using-aria/#presentation).

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html">
        Understanding Success Criterion 1.1.1: Non-text Content
    </HyperLink>

    <HyperLink href="https://www.w3.org/WAI/WCAG21/Techniques/general/G94">
        Providing short text alternative for non-text content that serves the same purpose and presents the same information as the non-text
        content
    </HyperLink>

</Links>


/info-examples/web/image-alt


{/* Contain details of needs review rules and automated checks rules */}


Info and Examples for Accessibility Insights for Web

/info-examples/web


Input buttons must have accessible names.

## Why it matters

An input button is an `<input>` element whose `type` is `button` , `reset` , or `submit`.
An accessible name is a word or phrase coded in a way that assistive technologies can associate it with a specific user interface object. Assistive technologies can then refer to the object by name, not just by type.

When an input button doesn’t have an accessible name, people who use assistive technologies have no way of knowing its specific purpose.

## How to fix

Provide an accessible name for each input button using one of the following methods.

Good

-   `title` attribute

Better

-   Non-empty `value` attribute
-   No `value` attribute (applies only if `type` is `submit` or `reset` ; causes the `type` value to be reported as the accessible name)
-   `aria-label` attribute

Best

-   `aria-labelledby` attribute

## Example

<PassFailGrid>
<FailSection>

CSS (not shown) is used to display an image on this input button. People with good vision can infer the button's purpose from the image.
However, because the button doesn’t have an accessible name, assistive technology users can't determine its purpose.

</FailSection>
<FailExample example={`<input type="button" id="new-account"  />
`} />
<PassSection>

An `aria-label` attribute provides an accessible name for the input button. Everyone can tell what the button does.

</PassSection>
<PassExample example={`<input type="button" id="new-account" [aria-label="Create my account"] />
`} />
</PassFailGrid>

## About this rule

This rule passes if ANY of the following is true:

-   Element has a non-empty `aria-label` attribute
-   Element has an `aria-labelledby` attribute that references elements that are visible to screen readers
-   Element has a non-empty `title` attribute
-   Element has a non-empty `value` attribute
-   Element with type `submit` or `reset` does not have a value attribute
-   Element’s default semantics were overridden with `role="presentation"` or `role="none"`

Use caution when applying `role="presentation"` or `role="none"` to an input button.
These roles instruct assistive technologies to disregard the element’s implicit role without hiding its content from users. If an input button has inner text, adding a `role` of `presentation` or `none` will cause it to be reported to users as a text string with no semantic context. For more information, see [Using ARIA: Use of Role=presentation or Role=none](https://www.w3.org/TR/using-aria/#presentation).

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html">
        Understanding Success Criterion 4.1.2: Name, Role, Value
    </HyperLink>
</Links>


/info-examples/web/input-button-name


Image buttons must have alternative text.

## Why it matters

An image button is an `<input>` element with `type="image"`.
Alternative text is a word or phrase that (1) is coded in a way that assistive technologies can associate it with a specific non-text object, and (2) conveys the same information as the non-text object.

Because assistive technologies can’t interpret an image directly, they rely on alternative text to communicate the image button’s purpose. When an image button doesn’t have alternative text, people who use assistive technologies have no way of knowing its purpose.

## How to fix

Provide alternative text that describes the input button’s purpose using one of the following methods:

Good

-   `title` attribute

Better

-   `aria-label` attribute
-   `aria-labelledby` attribute

Best

-   `alt` attribute

For tips on writing good text alternatives, see [Providing short text alternative for non-text content that serves the same purpose and presents the same information as the non-text content](https://www.w3.org/WAI/WCAG21/Techniques/general/G94).

## Example

<PassFailGrid>
<FailSection>

This image button has no alternative text. People who use assistive technologies can't determine its purpose.

</FailSection>
<FailExample example={`<input type="image" src="envelope.png" name="new" height="50" width="150">
`} />
<PassSection>

An `alt` attribute describes the image button's purpose. Everyone can tell what the button does.

</PassSection>
<PassExample example={`<input type="image" src="envelope.png" name="new" [alt="Create a new message"] height="50" width="150">
`} />
</PassFailGrid>

## About this rule

This rule passes if ANY of the following is true:

-   Element has a non-empty `alt` attribute
-   Element has a non-empty `aria-label` attribute
-   Element has an `aria-labelledby` attribute that references elements that are visible to screen readers
-   Element has a non-empty `title` attribute

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html">
        Understanding Success Criterion 1.1.1: Non-text Content
    </HyperLink>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Techniques/general/G94">
        Providing short text alternative for non-text content that serves the same purpose and presents the same information as the non-text
        content
    </HyperLink>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html">
        Understanding Success Criterion 4.1.2: Name, Role, Value
    </HyperLink>
</Links>


/info-examples/web/input-image-alt


An element's visible text must be included in its accessible name.

## Why it matters

Anyone who uses speech-based interaction benefits when UI components' accessible names match their visible text. Sighted people who can't use a mouse or keyboard might use speech input. When a UI component's accessible name matches its visible text, speech input users can activate them by speaking their visible text. People with low vision might use text-to-speech when they visit a new page to get an overview of the content. Such users might be confused if the accessible names they hear don’t match the text they see on the screen. People with cognitive challenges might find it especially difficult to remember speech commands that are different from what's visible on the screen.

## How to fix

Good

-   Make sure the element's accessible name contains its visible text.

Better

-   Make sure the element's accessible name begins with its visible text.

Best

-   Make sure the element's accessible name exactly matches its visible label.

## Example

<PassFailGrid>
<FailSection>

A shopping site has a link with visible text that says, "Shop now," An `aria-label` attribute gives the link a more detailed accessible name: "Shop our complete line of children's outerwear." People who use speech-to-text are likely to find the mismatch confusing. People who use text-to-speech won't be able to activate the link by speaking the visible text.

</FailSection>
<FailExample example={`…
<a href="/children/outerwear/landing.htm" aria-label="Shop our complete line of children's outerwear.">Shop now</a>
`} />
<PassSection>

The visible text label is changed to "Shop children's outerwear" and the `aria-label` attribute is removed. Everyone sees and hears the same text.

</PassSection>
<PassExample example={`…
<a href="/children/outerwear/landing.htm">Shop children's outerwear</a>
`} />
</PassFailGrid>

## About this rule

This rule passes if the element's accessible name is or contains an exact match of its visible text.

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/label-in-name.html">
        Understanding Success Criterion 2.5.3: Label in Name
    </HyperLink>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Techniques/general/G208">
        Including the text of the visible label as part of the accessible name
    </HyperLink>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Techniques/general/G211">Matching the accessible name to the visible label</HyperLink>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Techniques/failures/F96">
        Failure due to the accessible name not containing the visible label text
    </HyperLink>
</Links>


/info-examples/web/label-content-name-mismatch


Form controls must have accessible names.

## Why it matters

A form control is an interactive HTML element used for user input. Form controls include buttons, checkboxes, text fields, color pickers, and more.

An accessible name is a word or phrase coded in a way that assistive technologies can associate it with a specific user interface object. Assistive technologies can then refer to the object by its name, not just by type (role).

When a form control doesn't have an accessible name, people who use assistive technologies have no way of knowing its specific purpose.

## How to fix

For each `<input>` or `<textarea>` element, provide an accessible name using one of the following methods.

Good

-   `title` attribute
-   `placeholder` attribute

Better

-   `aria-label` attribute
-   `aria-labelledby` attribute

Best

-   Explicit `<label>` element
-   Implicit (wrapped) `<label>` element

## Example

<PassFailGrid>
<FailSection>

This `<textarea>` element is preceded by descriptive text in a `<p>` element, but the two elements are not programmatically associated to convey this information to assistive technologies.
People who use assistive technologies can use the keyboard or speech commands to navigate to the `<textarea>`, but because it has no name, they won't know its purpose.

</FailSection>
<FailExample example={`
<p>Shipping instructions:</p><textarea rows="4" cols="50"></textarea>
`} />
<PassSection>

An `aria-labelledby` attribute indicates to assistive technologies that the `<p>` element serves as a label for the `<textarea>` element.
The purpose of the `<textarea>` is communicated to all users.

</PassSection>
<PassExample example={`<label [for="ship-instr">Shipping instructions:</label>]
<textarea rows="4" cols="50" [id="ship-instr"]></textarea>
`} />
</PassFailGrid>

## About this rule

This rule passes if ANY of the following is true:

-   Element has a non-empty `aria-label` attribute
-   Element has an `aria-labelledby` attribute that references a non-empty element or elements which provide its accessible name
-   Element has a non-empty `title` attribute
-   Element has an explicit `<label>` that is not hidden
-   Element has an implicit (wrapped) `<label>`
-   Element has a non-empty `placeholder` attribute
-   Element is not focusable (i.e., `disabled`) and its default semantics are overridden with `role="presentation"` or `role="none"`

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/labels-or-instructions.html">
        Understanding Success Criterion 3.3.2: Labels or Instructions
    </HyperLink>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html">
        Understanding Success Criterion 4.1.2: Name, Role, Value
    </HyperLink>
</Links>


/info-examples/web/label


Links must be visually distinguished from surrounding text through styling or contrast.

## Why it matters

Links embedded in text are most visible when they have distinct styling or sufficient contrast with the surrounding text.

-   Styling can make an embedded link discernable if it changes the shape of the text, for example by adding an underline or border or switching to a different font.
-   Contrast can make an embedded link discernable if the link text is sufficiently darker or lighter than surrounding text.

An embedded link with no styling and insufficient contrast can be difficult to discern, especially for people with low vision or limited color vision.


## How to fix

Implement one or both of the following:

Good

-   Adjust the color of the link text and/or the surrounding text to provide a contrast ratio of at least 3:1.

Better

-   Provide a distinct style for the link text, such as an underline, a border, or a different font.

## Example

<PassFailGrid>
<FailSection>

In this page, paragraph text is styled to be black, and links are styled to be blue. Links embedded in paragraphs have an inadequate contrast ratio of 2.4:1 with the surrounding text. Moreover, the links' default underline has been removed by setting the `text-decoration` attribute to `none`. Because of these styling choices, some people will have difficulty seeing the embedded links.

</FailSection>
<FailExample example={`
<style>
[p {color: #000000}
a:link {text-decoration: none; color: #0000FF}]
...
</style>
`} />
<PassSection>

In this page, all embedded links are contained in `<p>` elements. The styling specifies that _links in paragraphs_ will have an underline. Links in other elements, such as tables or lists, are not underlined. Everyone will find it easier to see the embedded links.

</PassSection>
<PassExample example={`
<style>
p {color: #000000}
[p a:link {text-decoration: underline; color: #0000FF}]
a:link {text-decoration: none; color: #0000FF}
...
</style>
`} />
</PassFailGrid>

## About this rule

Instances need review if ALL of the following are true:

-   Link has no distinct style
-   Link's contrast ratio with surrounding tet is less than 3:1

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/use-of-color.html">
        Understanding Success Criterion 1.4.1 Use of Color
    </HyperLink>
</Links>


/info-examples/web/link-in-text-block


Links must have accessible names.

## Why it matters

An accessible name is a word or phrase coded in a way that assistive technologies can associate it with a specific user interface object. Assistive technologies can then refer to the object by name, not just by type. When a link doesn’t have an accessible name, people who use assistive technologies have no way of knowing its purpose.

## How to fix

For each link, provide an accessible name using one of the following methods.

Good

-   `aria-label` attribute

Better

-   `aria-labelledby` attribute

Best

-   Link text that’s available to assistive technologies (_not_ marked with `display: none` or `aria-hidden="true"` )

Each link’s accessible name should concisely describe its unique purpose.

## Example

<PassFailGrid>
<FailSection>

This link at a gourmet foods website contains an image of a coffee cup, but it has no accessible name.
People who use assistive technologies can't determine its purpose.

</FailSection>
<FailExample example={`<a href="https://mycompany.com/coffee.htm"><img src="//4/45/coffee.jpg" height="25" width="25"></a>
`} />
<PassSection>

An `aria-label` attribute provides an accessible name that describes the link's purpose.
Everyone can tell what the link does.

</PassSection>
<PassExample example={`<a href="https://mycompany.com/coffee.htm"><img src="//4/45/coffee.jpg" height="25" width="25" [aria-label="Browse our coffee products"]></a
`} />
</PassFailGrid>

## About this rule

This rule passes if ANY of the following are true:

-   Element has a non-empty `aria-label` attribute
-   Element has an `aria-labelledby` attribute that references elements that are visible to screen readers
-   Element has text that is visible to screen readers

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/link-purpose-in-context.html">
        Understanding Success Criterion 2.4.4: Link Purpose (In Context)
    </HyperLink>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html">
        Understanding Success Criterion 4.1.2: Name, Role, Value
    </HyperLink>
</Links>


/info-examples/web/link-name


A `<ul>`, `<ol>` or `<menu>` element must directly contain only `<li>` , `<script>` or `<template>` elements.

## Why it matters

In a properly structured list, all _content_ is contained within list items. _Content_ includes text and other HTML elements.
Certain _non-content_ elements are also allowed.

When an assistive technology encounters a list that’s poorly structured or contains disallowed elements, it might respond in an unexpected way.
As a result, people who use assistive technologies might find it difficult to interpret the list.

## How to fix

For each ordered or unordered list ( `<ol>`, `<ul>` or `<menu>` element):

-   Make sure all list content is contained within `<li>` elements.
-   Don’t use a `role` attribute to override the native semantics of a `<li>` element.
-   If you include any other HTML elements, enclose them within `<li>` elements.

## Example

<PassFailGrid>
<FailSection>

This unordered list has one `<li>` element whose `role` has been changed to `heading`.
As a result, assistive technologies do not recognize the element as a list item, but rather as a heading, which is not allowed in a list.
The disallowed content breaks the expected list structure; it isn't clear how assistive technologies should interpret this code.

</FailSection>
<FailExample example={`
<h2>Beverages</h2>
<ul>
<li [role="heading"] aria-level="3">Included</li>
<li>Coffee</li>
<li>Tea</li>
<li>Soda</li>
</ul>
`} />
<PassSection>

The heading content is removed from the list, and instead marked up as an `<h3>` element that appears before the unordered list in the DOM.
Now, all content within the list is contained within `<li>` elements. Assistive technologies can interpret the list consistently.

</PassSection>
<PassExample example={`
<h2>Beverages</h2>
[<h3>Included</h3>]
<ul>
<li>Coffee</li>
<li>Tea</li>
<li>Soda</li>
</ul>
`} />
</PassFailGrid>

## About this rule

This rule passes if:

-   List ( `<ul>`, `<ol>` or `<menu>` element) has as direct children only `<li>` , `<script>` , or `<template>` elements

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html">
        Understanding Success Criterion 1.3.1: Info and Relationships
    </HyperLink>
</Links>


/info-examples/web/list


All `<li>` elements must be contained by a `<ul>`, `<ol>`, or `<menu>` parent element.

## Why it matters

In a properly structured list, all list items ( `<li>` elements) are contained by a `<ul>`, `<ol>`, or `<menu>` parent element.

When an assistive technology encounters a list that’s poorly structured, it might respond in an unexpected way.
As a result, people who use assistive technologies might find it difficult to interpret the list.

## How to fix

All `<li>` elements must be contained by a `<ul>`, `<ol>`, or `<menu>` parent element.

For each list item (`<li>` element):

-   Enclose the `<li>` element in a `<ul>`, `<ol>`, or `<menu>` element (or in a parent element with `role="list"`).
-   Don’t use a `role` attribute to override the native list semantics of the `<ul>`, `<ol>`, or `<menu>` element.

## Example

<PassFailGrid>
<FailSection>

These list elements are not contained in a `<ul>`, `<ol>`, or `<menu>` parent element.
Assistive technologies will not interpret the `<li>` elements as being part of a single list. 
Some assistive technologies may not even interpret the content as list items at all.

</FailSection>
<FailExample example={`
<h2>Beverages</h2>
[<li>Coffee</li>
<li>Tea</li>
<li>Soda</li>]
`} />
<PassSection>

The list items are contained in a `<ul>` element.
Assistive technologies can interpret the list consistently.

</PassSection>
<PassExample example={`
<h2>Beverages</h2>
[<ul>]
<li>Coffee</li>
<li>Tea</li>
<li>Soda</li>
[</ul>]
`} />
</PassFailGrid>

## About this rule

This rule passes if:

-   List item has a `<ul>`, `<ol>`, `<menu>` or `role="list"` parent element

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html">
        Understanding Success Criterion 1.3.1: Info and Relationships
    </HyperLink>
</Links>


/info-examples/web/listitem


The `<marquee>` element is deprecated and must not be used.

## Why it matters

A `<marquee>` element is used to display text that moves horizontally or vertically across the screen.

Moving text can be distracting, especially for people with attention deficits or cognitive disabilities.
Moving text also can be difficult to read, especially for people with low vision or reading disabilities.
And a UI control that moves can be difficult to activate, especially for people with limited dexterity.

## How to fix

1. Remove `<marquee>` elements.
2. Avoid coding text to move across the screen.

## Example

<PassFailGrid>
<FailSection>

An important date is displayed in a `<marquee>` element that moves across the top of this web page.
The moving text is distracting and difficult to read.

</FailSection>
<FailExample example={`
<body>
[<marquee>Last day to order is tomorrow!</marquee>]
`} />
<PassSection>

The `<marquee>` element has been swapped for a static element.
Styling (not shown) makes the text visually prominent.

</PassSection>
<PassExample example={`
<body>
[<p>Last day to order is tomorrow!</p>]
`} />
</PassFailGrid>

## About this rule

This rule passes if:

-   No `<marquee>` element is visible

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/pause-stop-hide.html">
        Understanding Success Criterion 2.2.2: Pause, Stop, Hide
    </HyperLink>
</Links>


/info-examples/web/marquee


A `<meta>` element must not have an `http-equiv="refresh"` attribute.

## Why it matters

Using `http-equiv="refresh"` in a `<meta>` element causes a web page to refresh automatically at a specified time interval.

An automatic page refresh can be disorienting.
If a refresh causes input focus to move unexpectedly back to its original state, it can be especially frustrating for people who use screen readers and other keyboard users.

## How to fix

Remove `http-equiv="refresh"` from all `<meta>` elements. If a page refresh is required:

-   Implement the refresh using a script
-   AND provide a mechanism for users to turn off, extend, or adjust the timing of the page refresh.

## Example

<PassFailGrid>
<FailSection>

A news page uses `<meta http-equiv="refresh" content="60">` to refresh the page automatically every 60 seconds.
Users have no mechanism to turn off, extend, or adjust the timing of the refresh.
Most users find the refresh annoying; for some, it makes the page unusable.

</FailSection>

<PassSection>

Scripting is used to update specific content rather than refreshing the entire page.
Users are given the option of updating manually rather than automatically.
Everyone finds the page easier to use.

</PassSection>

</PassFailGrid>

## About this rule

This rule passes if:

-   No `<meta>` element contains `http-equiv="refresh"`

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/timing-adjustable.html">
        Understanding Success Criterion 2.2.1: Timing Adjustable
    </HyperLink>
</Links>


/info-examples/web/meta-refresh


## Why it matters

Using `content="user-scalable=no"` in a `<meta name="viewport">` element disables zooming in some browsers.
Users are forced to view the text at the specified size.

Most people find it easier to read text when it is sufficiently large.
People with visual disabilities, low vision, or limited color perception are likely to find text unreadable when it’s too small.

## How to fix

Remove `content="user-scalable=no"` from all `<meta>` elements.

## Example

<PassFailGrid>
<FailSection>

A news page is coded in a way that browser zooming causes some content to extend beyond the screen's viewport.
In an attempt to address that problem, a `<meta>` element is configured to disable browser zooming.

As a result, text is always displayed at the specified size. However, some users now find some text difficult to read because it is too small.

</FailSection>
<FailExample example={`
<meta name="viewport" [content="user-scalable=no"]>
`} />
<PassSection>

The `<meta>` element is reconfigured to (1) set the width of the page to match the screen width of the device, and (2) set the initial zoom level of the page.
Everyone can zoom the text to a readable size, and the content stays within the viewport.

</PassSection>
<PassExample example={`
<meta name="viewport" [content="width=device-width, initial-scale=1.0"]>
`} />
</PassFailGrid>

## About this rule

This rule passes if:

-   No `<meta>` element contains `content="user-scalable=no"`

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/resize-text.html">
        Understanding Success Criterion 1.4.4: Resize text
    </HyperLink>
</Links>


/info-examples/web/meta-viewport


Custom ARIA input fields must communicate their _complete_ names to assistive technologies.

## Why it matters

Every custom input field must have an accessible name that communicates its specific purpose.

A custom ARIA input field might be based on an element (such as `<div>`) that isn't supported by `<label>` elements. Browsers will not associate a `<label>` element with any element that is not a [labelable element](https://html.spec.whatwg.org/multipage/forms.html#category-label) in HTML. This is true even if the element's role were to be changed to match the implicit ARIA role of a labelable element. For instance, while an `<input type="text">` is a labelable element, a `<div role="textbox">` is not. As a result, if a `<label>` element references an unsupported element, its text will not be used to name the referenced custom input field, and thus will not be exposed available to assistive technologies. If such a `<label>` contains a meaningful part of the custom input field's name, people who use assistive technologies won't know its complete name. They might find it difficult to distinguish among elements with similar names.

## How to check

Inspect the element using the [Accessibility pane in the browser Developer Tools](https://developer.chrome.com/blog/new-in-devtools-65/#a11y-pane) to verify that the field's accessible name is complete without the associated `<label>`.

If the element's accessible name is complete without the associated `<label>` text, then no changes are needed.

## How to fix  

Provide the complete accessible name using ONE of the following methods:

Good

-   `title` attribute

Better

-   `aria-label` attribute

Best

-   `aria-labelledby` attribute

## Example

<PassFailGrid>
<FailSection>

A `<div>` functions as a slider. Part of its name is contained only in a `<label>` element. Because `<div>` elements aren't supported by `<label>` elements, assistive technologies won't have access to, and thus won't announce the `<label>` text. Assistive technology users won't know they're being asked for a shirt size.

</FailSection>
<FailExample example={`[<label for="field1">]Shirt size</label>
<div id="field1" role="slider" aria-label="women's">...</div>`} />
<PassSection>

The element's complete name is provided using an `aria-labelledby` attribute. Everyone will understand what they are selecting.

</PassSection>
<PassExample example={`[<p id="field1label">]Women's shirt size</p>
<div id="field1" role="slider" [aria-labelledby=
"field1label"]>...</div>`} />
</PassFailGrid>

## About this rule

Instances need review if ALL of the following are true:

-   Element has one of the following role attribute values:
    -   `combobox`
    -   `listbox`
    -   `searchbox`
    -   `slider`
    -   `spinbutton`
    -   `textbox`
-   Element has an accessible name provided by an `aria-label`, `aria-labelledby`, or `title` attribute
-   Element's `id` is referenced by a `<label>` element
-   Element's type is not [labelable](https://html.spec.whatwg.org/multipage/forms.html#category-label)
-   `<label>` contains text that isn't included in the element's accessible name

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html">
        Understanding Success Criterion 4.1.2 Name, Role, Value
    </HyperLink>
</Links>


/info-examples/web/needs-review/aria-input-field-name


Text elements must have sufficient contrast.

## Why it matters

Most people find it easier to read text when it has a sufficiently high contrast against its background.

People with visual disabilities, low vision, limited color perception, or [presbyopia](https://en.wikipedia.org/wiki/Presbyopia) are likely to find text unreadable when contrast is too low.

## How to check

Use [Accessibility Insights for Windows](https://go.microsoft.com/fwlink/?linkid=2075365) (or the [Colour Contrast Analyser](https://developer.paciellogroup.com/resources/contrastanalyser/) if you're testing on a Mac) to manually verify that the text has sufficient contrast against the background. If the background is an image or gradient, test an area where contrast appears to be lowest.

If the text has sufficient contrast against all areas of the background, then no changes are needed.

If the element is an icon or other non-text content, then this requirement does not apply.

For detailed test instructions, go to **Assessment** > **Adaptable content** > **Contrast**.

## How to fix

If the text has a contrast ratio of 1:1 and is intended to be hidden, mark the element with `aria-hidden="true"`.

If the text is intended to be visible, adjust its foreground color and/or background color to provide sufficient contrast.

-   A minimum contrast ratio of 3:1 is required for large text, defined as:

    -   18pt (24 CSS pixels)
    -   OR bold 14pt (19 CSS pixels)

-   A minimum contrast ratio of 4.5:1 is required for smaller text.

## Example

<PassFailGrid>
<FailSection>

A small amount of white text is centered over a large background image. Portions of the text don't have sufficient contrast against the background. Some people will find the text difficult to read.

</FailSection>
<PassSection>

An overlay is used to darken the background image in the area beneath the white text. Where the image has no text, it retains its original colors. The darker background provides sufficient contrast with all portions of the text. Most people will find the text legible.

</PassSection>
</PassFailGrid>

## About this rule

Instances need review if ANY of the following are true:

-   Element's background color can't be determined (for example, because of an image or gradient)
-   Element's foreground color can't be determined (for example, because of transparency)
-   Element's foreground and background have a 1:1 contrast ratio
-   Element is overlapped or obscured by another element
-   Element content is very short or contains non-text characters

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html">
        Understanding Success Criterion 1.4.3 Contrast (Minimum)
    </HyperLink>
</Links>


/info-examples/web/needs-review/color-contrast


An element referenced by a label or ARIA attribute must have a unique `id` value.

## Why it matters

Labels and ARIA relationship attributes (such as `aria-controls`, `aria-labelledby`, and `aria-owns`) depend on unique `id` values to identify specific UI components. When multiple elements in a web page share the same `id` value, assistive technologies are likely to recognize only the first, and ignore others.

## How to check

Make sure each ID value assigned to an ARIA attribute or a label element (via its `for` attribute) is different.  In other words, make sure ID values that need to be referenced by ARIA attributes or label elements aren't used more than once in the same document, application, or web page.   

## How to fix

For each element referenced by a label or ARIA attribute, provide a unique `id` value.

## Example

<PassFailGrid>
<FailSection>

A web page has separate controls for searching across the site or searching within the current page. Each control is labelled by a `<p>` element through an `aria-labelledby` attribute.
But both `<p>` elements have the same `id` value. When interpreting these `aria-labelledby` attributes, assistive technologies use the first element that matches the specified `id` value. As a result, both search fields are reported as "Search this site."
Assistive technology users would not know that the second search field is actually for searching within the page.

</FailSection>
<FailExample example={`<form id="site-search" role="search">
<p [id="search-label"]>Search this site</p>
<input type="search" id="site-search-field" [aria-labelledby="search-label"] size="50">
<input type="submit" id="site-search-submit" value="Search">
</form>
…
<form id="page-search" role=" search">
<p [id="search-label"]>Search this page</p>
<input type="search" id="page-search-field" [aria-labelledby="search-label"] size="50">
<input type="submit" id="page-search-submit" value="Search">
</form>
`} />
<PassSection>

The `<p>` elements referenced by the `aria-labelledby` attributes have unique `id` values.
Assistive technologies report the correct label for each control.

</PassSection>
<PassExample example={`<form id="site-search" role="search">
<p [id="site-search-label"]>Search this site</p>
<input type="search" id="site-search-field" [aria-labelledby="site-search-label"] size="50">
<input type="submit" id="site-search-submit" value="Search">
</form>
…
<form id="page-search" role=" search">
<p [id="page-search-label"]>Search this page</p>
<input type="search" id="page-search-field" [aria-labelledby="page-search-label"] size="50">
<input type="submit" id="page-search-submit" value="Search">
</form>
`} />
</PassFailGrid>

## About this rule

This rule passes if:

-   Document has no elements referenced by ARIA or labels that share the same id attribute value

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/parsing.html">Understanding Success Criterion 4.1.1: Parsing</HyperLink>
</Links>


/info-examples/web/needs-review/duplicate-id-aria

/info-examples/web/needs-review/label-content-name-mismatch


Links must be visually distinguished from surrounding text through styling or contrast.

## Why it matters

Links embedded in text are most visible when they have distinct styling or sufficient contrast with the surrounding text.

-   Styling can make an embedded link discernable if it changes the shape of the text, for example by adding an underline or border or switching to a different font.
-   Contrast can make an embedded link discernable if the link text is sufficiently darker or lighter than surrounding text.

An embedded link with no styling and insufficient contrast can be difficult to discern, especially for people with low vision or limited color vision.

## How to check

Manually verify that the link text has one or both of the following:

-   A contrast ratio of at least 3:1 compared to surrounding text
-   A visual style (such as underline, bold, or italics) that gives it shape that's different from surrounding text.

To measure contrast, use [Accessibility Insights for Windows](https://go.microsoft.com/fwlink/?linkid=2075365) (or the [Colour Contrast Analyser](https://developer.paciellogroup.com/resources/contrastanalyser/) if you're testing on a Mac).

If the link text has sufficient contrast and/or a distinct visual style, then no changes are needed.

## How to fix

Implement one or both of the following:

Good

-   Adjust the color of the link text and/or the surrounding text to provide a contrast ratio of at least 3:1.

Better

-   Provide a distinct style for the link text, such as an underline, a border, or a different font.

## Example

<PassFailGrid>
<FailSection>

In this page, paragraph text is styled to be black, and links are styled to be blue. Links embedded in paragraphs have an inadequate contrast ratio of 2.4:1 with the surrounding text. Moreover, the links' default underline has been removed by setting the `text-decoration` attribute to `none`. Because of these styling choices, some people will have difficulty seeing the embedded links.

</FailSection>
<FailExample example={`
<style>
[p {color: #000000}
a:link {text-decoration: none; color: #0000FF}]
...
</style>
`} />
<PassSection>

In this page, all embedded links are contained in `<p>` elements. The styling specifies that _links in paragraphs_ will have an underline. Links in other elements, such as tables or lists, are not underlined. Everyone will find it easier to see the embedded links.

</PassSection>
<PassExample example={`
<style>
p {color: #000000}
[p a:link {text-decoration: underline; color: #0000FF}]
a:link {text-decoration: none; color: #0000FF}
...
</style>
`} />
</PassFailGrid>

## About this rule

Instances need review if ALL of the following are true:

-   Link has no distinct style
-   Link's contrast ratio with surrounding tet is less than 3:1

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/use-of-color.html">
        Understanding Success Criterion 1.4.1 Use of Color
    </HyperLink>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html">
        Understanding Success Criterion 1.4.3 Contrast (Minimum)
    </HyperLink>
</Links>


/info-examples/web/needs-review/link-in-text-block


`<p>` elements must not be styled to look like headings.  

## Why it matters 

Headings are used to convey the structure and hierarchy of the content displayed on the page. Headings should be denoted by the use of `<h1>` through `<h6>` elements in hierarchical order. When these headings are improperly ordered or `<p>` elements are styled to look like headings, the heading structure isn’t defined in a way that assistive technologies can recognize. As a result, screen reader users won’t be able to use the navigational structure within a page.  

## How to fix 
Good:  
- Make sure that `<p>` elements are not styled to serve as headings. 

Better:
- Re-implement headings using the appropriate heading tags (`<h1>` through `<h6>`) or use `role=”heading”` and `aria-level` attributes on the element which is visually styled to serve as a heading. 

## Example

<PassFailGrid>
<FailSection>

A page on cooking techniques uses a `<p>` element with a bold style to serve as the primary heading of the page. The `<p>` element might look like a heading, but it will not be communicated to screen readers as a heading.  

</FailSection>
<FailExample example={` <html xmlns="http://www.thisIsATestSite.org/1800/xhtml"> 

                <head> 

                <title>Cooking techniques</title> 

                </head> 

                <body> 

                <p><b>Cooking techniques</b></p> 

                ... some text here ... 

                <h2>Cooking with oil</h2> 

                ... text of the section ... 

                <p><b> Sautéeing </b></p> 
`} />
<PassSection>

A page on cooking techniques uses a `<h1>` element for the primary heading, and `<h2>` and `<h3>` elements to introduce the major sections. This structure of the document can be communicated to screen readers. 

</PassSection>
<PassExample example={`<html xmlns=" http://www.thisIsATestSite.org/1800/xhtml"> 

                <head> 

                <title>Cooking techniques</title> 

                </head> 

                <body> 

                <h1>Cooking techniques</h1> 

                ... some text here ... 

                <h2>Cooking with oil</h2> 

                ... text of the section ... 

                <h3>Sautéeing</h3> 
`} />
</PassFailGrid>


## About this rule 

This rule passes if the following are true: 
- paragraph elements do not use italic, bold, or font size to give the appearance of headings. 

## More examples 

    [Understanding Success Criterion 1.3.1: Info and Relationships](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html)

    [More information on Headings](https://www.w3.org/WAI/tutorials/page-structure/headings/)

    [Organizing a page using headings](https://www.w3.org/WAI/WCAG21/Techniques/general/G141)

    [Using h1-h6 to identify headings](https://www.w3.org/WAI/WCAG21/Techniques/html/H42)

    [Providing heading elements at the beginning of each section of content](https://www.w3.org/WAI/WCAG21/Techniques/html/H69)

    [Using standard text formatting conventions for headings](https://www.w3.org/WAI/WCAG21/Techniques/text/T3)


/info-examples/web/needs-review/p-as-heading


A header cell in a data table must not have missing data cells.

## Why it matters

People with good vision typically read a data table by visually scanning its rows or columns of data. They can easily skip over a missing data cell and continue through the rest.

People who use assistive technologies a read data table by navigating through its rows or columns using a keyboard. When they encounter a missing data cell, they might not realize there's any content beyond it. Even if they do, they can't skip over the missing data cell; instead, they have to navigate around it. They are likely to have difficulty interpreting the table.

## How to check

Examine the row or column header in the context of the table to verify that it has no data cells.

If the header _has no data cells_, then no changes are required. (The missing cells will not disrupt keyboard navigation.)

## How to fix

If a row or column header _has at least one data cell_, then ensure that ALL of the following are true:

-   The header has a full set (row or column) of related data cells. (It's ok if cells are empty.)
-   All of the data cells are programmatically related to the header.

## Example

<PassFailGrid>
<FailSection>

In this table, the third column is missing one data cell. Assistive technology users who attempt to navigate down that column using a keyboard might conclude incorrectly that the column has no additional cells.

</FailSection>
<FailExample example={`
<table>
<thead>
<tr>
<th scope="col">Item</th>
<th scope="col">Pounds</th>
</tr>
</thead>
<tbody>
<tr>
<th>Apples</th>
<td>12</td>
</tr>
[<tr>
<th>Bananas</th>
</tr>]
<tr>
<th>Oranges</th>
<td>16</td>
</tr>
<tr>
<th>Pears</th>
<td>6</td>
</tr>
</tbody>
</table>
`} />
<PassSection>

The missing data cell has been added, though it remains empty. All users can infer that the cell has no data, and they can easily access the remaining cells in the column.

</PassSection>
<PassExample example={`
<table>
<thead>
<tr>
<th scope="col">Item</th>
<th scope="col">Pounds</th>
</tr>
</thead>
<tbody>
<tr>
<th>Apples</th>
<td>12</td>
</tr>
<tr>
<th>Bananas</th>
[<td></td>]
</tr>
<tr>
<th>Oranges</th>
<td>16</td>
</tr>
<tr>
<th>Pears</th>
<td>6</td>
</tr>
</tbody>
</table>
`} />
</PassFailGrid>

## About this rule

Instances need review if ALL of the following are true:

-   Element is a header cell (`<th>` or has `role="columnheader"` or `role="rowheader"`)
-   Header cell is missing one or more programmatically related data cells.

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html">
        Understanding Success Criterion 1.3.1 Info and Relationships
    </HyperLink>
</Links>


/info-examples/web/needs-review/th-has-data-cells


Interactive controls must not have focusable descendants.

## Why it matters

Certain interactive controls such as `button`, `checkbox`, `img`, `scrollbar`or `slider` can't have interactive children.
Assistive technologies, such as screen readers, might ignore or respond unexpectedly to such nested controls.

## How to fix

Ensure interactive controls don't have focusable descendants by separating nested interactive components or styling a single element.

## Example

<PassFailGrid>
<FailSection>

An element with `role="button"` has a link as part of the text. Screen readers will not read the link.

</FailSection>
<FailExample example={`<div role ="button"> <a href=foo.bar>Download or click here to learn more</a></div>
`} />
<PassSection>

The link is now outside the button. All users can interact with the button and the link.

</PassSection>
<PassExample example={`<div role ="button">Download</div>
 <a href=foo.bar>Learn more about your download</a>`} />
</PassFailGrid>

## About this rule

This rule passes if:

-   There are no focusable elements nested in controls that don't allow interactive children

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html">
        Understanding Success Criterion 4.1.2: Name, Role, Value
    </HyperLink>
</Links>


/info-examples/web/nested-interactive


An `<object>` element must have alternative text.

## Why it matters

An `<object>` element is used to embed multimedia content in a web page. It can also be used to embed one web page inside another.

Alternative text is a word or phrase that (1) is coded in a way that assistive technologies can associate it with a specific non-text object, and (2) conveys the same information as the non-text object.

Because assistive technologies can’t interpret objects directly, they rely on alternative text to communicate the meaning of non-text content to users.

## How to fix

For each `<object>` element, provide alternative text using one of the following methods.

Good

-   `title` attribute

Better

-   `aria-label` attribute

Best

-   `aria-labelledby` attribute

For tips on writing good text alternatives, see [Providing short text alternative for non-text content that serves the same purpose and presents the same information as the non-text content](https://www.w3.org/WAI/WCAG21/Techniques/general/G94).

## Example

<PassFailGrid>
<FailSection>

This `<object>` element doesn't have alternative text.
Assistive technology users won't have any idea what information the object contains unless they interact with it.

</FailSection>
<FailExample example={`
<object type="application/pdf" data="/media/beeth_fe.pdf" width="250" height="200">
</object>	
`} />
<PassSection>

The `<object>` element uses an `aria-label` attribute to provide alternative text.
Assistive technology users can judge from the name whether the object is likely to have useful content.

</PassSection>
<PassExample example={`
<object type="application/pdf" data="/media/beeth_fe.pdf" width="250" height="200" [aria-label="Sheet music for Beethoven's "Für Elise"]>
</object>
`} />
</PassFailGrid>

## About this rule

This rule passes if ANY of the following is true:

-   Element has a non-empty `aria-label` attribute
-   Element has an `aria-labelledby` attribute that references elements that are visible to screen readers
-   Element has a non-empty `title` attribute
-   Element’s default semantics were overridden with `role="presentation"` or `role="none"`

Important: Use caution when applying `role="presentation"` or `role="none"` to an `<object>` element.
These roles instruct assistive technologies to disregard the element’s implicit role without hiding its content from users.
If an `<object>` element with a `role` of `presentation` or `none` has inner text, it will be reported to users as a text string with no semantic context. For more information, see [Using ARIA: Use of Role=presentation or Role=none](https://www.w3.org/TR/using-aria/#presentation).

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html">
        Understanding Success Criterion 1.1.1: Non-text Content
    </HyperLink>

    <HyperLink href="https://www.w3.org/WAI/WCAG21/Techniques/general/G94">
        Providing short text alternative for non-text content that serves the same purpose and presents the same information as the non-text
        content
    </HyperLink>

</Links>


/info-examples/web/object-alt


The use of role="none" or role="presentation" on HTML elements must not conflict with the implicit functionality of the element, and must not be in conflict with other specified global ARIA attributes.  

## Why it matters
An [ARIA role](https://www.w3.org/TR/wai-aria/#roles_categorization) attribute can be added to an element to instruct assistive technologies to treat the element as something other than its native HTML element type. For example, an `<a>` element with `role="button"` is to be treated as a button, not a link. 

Assistive technologies will often report an element’s role when the role has semantics important to accessibility. For example, they inform users when they encounter links, buttons, headings, or images. However, they generally ignore exposing properties of semantically neutral (generic) elements, such as `<span>` or `<div>` elements.  

The `role=“presentation”` or `role=“none”` attributes instruct assistive technologies to disregard the element’s implicit role without hiding its content from users. However, in some cases HTML elements will not respect a role="none" or role="presentation". Generally this occurs when an element has implicit behaviors or explicit properties which are important to accessibility, and they conflict with the specified presentational roles. As a result, the roles are ignored and users will continue to be able to interact with the element as if the specified `role` was not present.

## How to fix
For each element with `role="none"` or `role="presentation"`: 
- Make sure it doesn’t have a global ARIA attribute. 
- Make sure it's not focusable. 

**Note:** an element with `tabindex="-1"` is removed from the web page's tabbing order. It is, however, still focusable.


## Example

<PassFailGrid>
<FailSection>

The element `<article>` has a global ARIA attribute of `aria-label` in addition to the `role="presentation"`, and because of its `tabindex` attribute, it is also a focusable element. This causes a failure due to conflict between the global ARIA attribute, the element being focusable, and the presentational role.  

</FailSection>
<FailExample example={`<article tabindex="-1" aria-label="I am a global aria-attribute" role="presentation"> `} />
<PassSection>

The element `<article>` has an empty ARIA attribute of `aria-label=""` in addition to the `role="presentation"`. Its `tabindex` attribute has been removed. Now, the element's implicit `article` role is not reported to the browser's accessibility tree, because the conflicting properties which were important to accessibility (named element and being focusable) have been removed.  

</PassSection>
<PassExample example={`<article" aria-label="" role="presentation">`} />
</PassFailGrid>

## About this rule 

This rule passes if ALL of the following are true: 
- all elements with `role=“none”` or `role=“presentation”` do not have a global ARIA attribute. 
- all elements with `role=“none”` or `role=“presentation”` are not focusable.  


## More examples 
    [Using ARIA: Use of Role=presentation or Role=none](https://www.w3.org/TR/using-aria/#presentation)

    [Understanding Success Criterion 1.3.1: Info and Relationships](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships)

    [Understanding Success Criterion 4.1.2: Name, Role, Value](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html)


/info-examples/web/presentation-role-conflict


Elements with `role="img"` must have alternative text.

## Why it matters

The attribute `role="img"` is used to identify the container for a collection of elements that together form a single meaningful image.

Alternative text is a word or phrase that (1) is coded in a way that assistive technologies can associate it with a specific non-text object, and (2) conveys the same information as the non-text object.

Because assistive technologies can’t interpret images directly, they rely on alternative text to communicate the meaning of non-text content to users.

## How to fix

For each element with `role="img"` :

1. Determine whether the image as a whole is meaningful or decorative:

-   An image is _meaningful_ if it conveys information that isn’t available through other page content.
-   An image is _decorative_ if it could be removed from the page with _no_ impact on meaning or function.

2. If the image is meaningful, provide alternative text using one of the following attributes:

-   `aria-label`
-   `aria-labelledby`
-   `title`

3. If the image is decorative, replace `role="img"` with `role="presentation"` or `role="none"`.

For tips on writing good text alternatives, see [Providing short text alternative for non-text content that serves the same purpose and presents the same information as the non-text content](https://www.w3.org/WAI/WCAG21/Techniques/general/G94)

## Example

<PassFailGrid>
<FailSection>

This `<div>` is correctly identified as the container for an image (composed of ASCII characters), but it has no alternative text.
Assistive technologies can't tell users anything about the image's meaning.

</FailSection>
<FailExample example={`
[<div role="img">(ㆆ _ ㆆ)</div>]
`} />
<PassSection>

An `aria-label` attribute allows assistive technologies to describe the image to users.

</PassSection>
<PassExample example={`
<div role="img" [aria-label="scared face"]>(ㆆ _ ㆆ)</div>
`} />
</PassFailGrid>

## About this rule

This rule passes if ANY of the following is true:

-   Element has a non-empty `aria-label` attribute
-   Element has an `aria-labelledby` attribute that references elements that are visible to screen readers
-   Element has a non-empty `title` attribute

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html">
        Understanding Success Criterion 1.1.1: Non-text Content
    </HyperLink>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Techniques/general/G94">
        Providing short text alternative for non-text content that serves the same purpose and presents the same information as the non-text
        content
    </HyperLink>
</Links>


/info-examples/web/role-img-alt


Elements with scrollable content must be accessible by keyboard.

## Why it matters

When a page includes content in a scrollable element, all users must be able to scroll any hidden content into view. Mouse users can scroll such content by clicking the scrollbar associated with the scrollable element. However, it isn’t possible activate a scrollbar using a keyboard, because a scrollbar can’t receive input focus. Instead, focus must be moved either to the scrollable element itself or to a child element within the scrollable element. Then the content can be scrolled using the keyboard’s arrow keys. Thus, scrollable content is keyboard accessible only if the scrollable element is focusable or contains a focusable element. (An element is focusable if it can receive input focus via scripting, mousing, or keyboard tabbing.)

## How to fix

For each element with the `overflow` property set to `auto` or `scroll` , make sure the element itself is focusable or contains a focusable element.

-   Some scrollable elements (such as `<input type="text">` are natively focusable.
-   Elements that are not natively focusable (such as `<div>` elements) can be made focusable by adding the attribute `tabindex="0"`.

## Example

<PassFailGrid>
<FailSection>

The content in the `<div>` is scrollable, but neither the `<div>` itself nor any of its content is tabbable.
As a result, keyboard users can't operate the scrollbar to see all of the content.

</FailSection>
<FailExample example={`
<h3>Severability</h3>
<div [style="height: 50px; overflow: auto;]">If any provision of these terms is found to be unenforceable or invalid under any applicable law, such unenforceability or invalidity shall not render these terms unenforceable or invalid as a whole, and such provisions shall be deleted without affecting the remaining provisions herein.</div>
`} />
<PassSection>

The attribute `tabindex="0"` makes the `<div>` tabbable.
Keyboard users can tab to the `<div>` and then use operate the scrollbar by using arrow keys.

</PassSection>
<PassExample example={`
	<h3>Severability</h3>
<div style="height: 50px; overflow: auto;" [tabindex="0"]>If any provision of these terms is found to be unenforceable or invalid under any applicable law, such unenforceability or invalidity shall not render these terms unenforceable or invalid as a whole, and such provisions shall be deleted without affecting the remaining provisions herein.</div>
`} />
</PassFailGrid>

## About this rule

This rule passes if ANY of the following is true:

-   Scrollable element is focusable
-   Scrollable element contains focusable elements

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/keyboard.html">Understanding Success Criterion 2.1.1: Keyboard</HyperLink>
</Links>


/info-examples/web/scrollable-region-focusable


All `<select>` elements must have accessible names.

## Why it matters

A `<select>` element is an HTML control for selecting among a set of options.
An accessible name is a word or phrase coded in a way that assistive technologies can associate it with a specific user interface object. Assistive technologies can then refer to the object by name, not just by type.
When a `<select>` element doesn't an accessible name, people who use assistive technologies have no way of knowing its purpose.

## How to fix

For each `<select>` element, provide an accessible name using one of the following methods.

Good

-   `title` attribute

Better

-   `aria-label` attribute
-   `aria-labelledby` attribute referencing visible text

Best

-   Explicit `<label>` element
-   Implicit (wrapped) `<label>` element

## Example

<PassFailGrid>
<FailSection>

This `<select>` element doesn't have an accessible name. Instead, the first option—configured as a placeholder—is used to communicate the control's purpose. Although some people might correctly infer the purpose of the control, the implementation is potentially confusing to any user.

</FailSection>
<FailExample example={`<select name="flavorchoices">
<option value="0">[Flavor:]</option>
<option value="1">Apple</option>
<option value="2">Cherry</option>
<option value="3">Grape</option>
<option value="4">Lemon</option>
<option value="5">Watermelon</option>
</select>
`} />
<PassSection>

The `<select>` element is provided an accessible name using a `<label>` element. All users can tell that the control allows them to select a flavor.

</PassSection>
<PassExample example={`[<label for="flavor">]Flavor:</label>
<select [id="flavor"] name="flavorchoices">
<option value="0">Apple</option>
<option value="1">Cherry</option>
<option value="2">Grape</option>
<option value="3">Lemon</option>
<option value="4">Watermelon</option>
</select>
`} />
</PassFailGrid>

## About this rule

This rule passes if ANY of the following are true:

-   Element has an `aria-labelledby` attribute referencing an element that is visible to screen readers
-   Element has a non-empty `aria-label` attribute
-   Element has a non-empty `title` attribute
-   Element has an explicit `<label>` element
-   Element has an implicit (wrapped) `<label>` element

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html">
        Understanding Success Criterion 4.1.2: Name, Role, Value
    </HyperLink>
</Links>


/info-examples/web/select-name


Server-side image maps must not be used.

## Why it matters

Server-side image maps work by passing mouse click coordinates to a server-side script, which then determines what was clicked.

Because server-side image maps require the use of a mouse, they are not accessible to people who use keyboards (including people who use screen readers) or speech commands.

## How to fix

Replace server-side image maps ( `<img ismap>` elements) with client-side image maps ( `<img usemap>` elements).

## Example

<PassFailGrid>
<FailSection>

A server-side image map requires users to select a business location using a mouse.
This image map is unusable by people who use a keyboard or speech commands.

</FailSection>
<FailExample example={`
<a href="/media/locations.map">
<img src="/media/locations.png" [ismap]>
</a>
`} />
<PassSection>

A client-side image map allows users to select a business location using a mouse, a keyboard, or a speech command.

</PassSection>
<PassExample example={`
<p>Select a business location to see our business hours:</p>
<img src="locations.png" width="800" height="400" alt="Map of business locations" [usemap]="#locations-map">
<map name="locations-map">
<area shape="rect" coords="0,0,200,400" alt="Corporate headquarters" href="location1.htm">
<area shape="rect" coords="0,0,400,400" alt="Elm Street store" href="location2.htm">
<area shape="rect" coords="0,0,600,400" alt="Maple Street store" href="location3.htm">
</map>
`} />
</PassFailGrid>

## About this rule

This rule passes if:

-   `<img>` with `ismap` attribute does not exist

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/keyboard.html">Understanding Success Criterion 2.1.1: Keyboard</HyperLink>
</Links>


/info-examples/web/server-side-image-map


All `<summary>` elements must have discernible text

## Why it matters

The `<summary>` HTML element represents a brief summary, caption, or legend for the rest of the content of its parent `<details>` element. Together, a `<summary>` and `<details>` element can be used to create a native HTML disclosure widget.
If a `<summary>` element does not have discernible text or an accessible name, a screen reader user cannot determine
the purpose of the element, nor what the disclosure widget is meant to represent.

## How to fix

For each `<summary>` element, provide discernible text using one of the following methods:

-   Provide inner text content that is available to assistive technologies (_not_ marked with `display: none` or `aria-hidden="true"`)
-   Provide a `title` attribute
-   Privide an `aria-label` attribute
-   Provide an `aria-labelledby` attribute referencing visible text
-   Only in the event a name cannot be determined, remove the `<summary>` element and the user agent will supply a localized "Details" string as the summary.

## Example

<PassFailGrid>
<FailSection>

This `<details>` element contains a `<summary>` element that does not have discernible text.

</FailSection>

<FailExample
    example={`<details>
[<summary></summary>]
<p>The <summary> HTML element represents a brief summary, caption, or legend for the rest of the content of its parent <details> element. Together, a <summary> and <details> element can be used to create a native HTML disclosure widget.</p>`}
/>

<PassSection>

Visible inner text gives the `<summary>` element a discernible text label and accessible name.

</PassSection>

<PassExample
    example={`<details>
[<summary>Summary Element</summary>]
<p>The <summary> HTML element represents a brief summary, caption, or legend for the rest of the content of its parent <details> element. Together, a <summary> and <details> element can be used to create a native HTML disclosure widget.</p>`}
/>

</PassFailGrid>

## About this rule

This rule passes if ANY of the following is true:

-   Element has inner text content that is visible to screen readers
-   Element has an `aria-labelledby` attribute that references an element or elements containing text
-   Element has a non-empty `aria-label` attribute
-   Element has a non-empty `title` attribute
-   The parent `<details>` element does not have a `<summary>` element

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html">
        Understanding Success Criterion 4.1.2: Name, Role, Value
    </HyperLink>
</Links>


/info-examples/web/summary-name


An `<svg>` element with an image or graphics role must have alternative text.

## Why it matters

An `<svg>` element is a container for images and graphics.
Alternative text is text that conveys the meaning of non-text content, such as icons, photos, illustrations, and graphs. Because assistive technologies can't interpret an image directly, they rely on alternative text to communicate the image's meaning to users.
When an `<svg>` element marked with `role="img"`, `role="graphics-document"`, or `role="graphics-symbol"` doesn't have alternative text, people who use assistive technologies have no way of knowing what it means.

## How to fix

For each `<svg>` element with `role="img"`, `role="graphics-document"`, or `role="graphics-symbol"`, provide an accessible name using one of the following methods.

Good

-   `title` attribute
-   child `<title>` element

Better

-   `aria-label` attribute

Best

-   `aria-labelledby` attribute

## Example

<PassFailGrid>
<FailSection>

This `<svg>` element contains a red circle and has a role attribute to indicate that it contains an image.
But because the `<svg>` element doesn't have alternative text, people who use assistive technologies won't know what image it represents.

</FailSection>
<FailExample example={`<svg role="img" width="100" height="100">
<circle cx="50" cy="50" r="40" fill="red">
</circle>
</svg>
`} />
<PassSection>

The `<svg>` element gets alternative text through an `aria-labelledby` element referencing visible text in a paragraph.
All users can tell that the image is a red circle.

</PassSection>
<PassExample example={`<p [id="circle"]>[A red circle]</p>
<svg role="img" width="100" height="100" [aria-labelledby="circle"]>
<circle cx="50" cy="50" r="40" fill="red">
</circle>
</svg>
`} />
</PassFailGrid>

## About this rule

This rule passes if:

-   ANY of the following are true:
    -   Element has an `aria-labelledby` attribute that references elements that are visible to screen readers
    -   Element has a non-empty `aria-label` attribute
    -   Element has a non-empty child `<title>` element
    -   Element has a non-empty `title` attribute

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html">
        Understanding Success Criterion 1.1.1: Non-text Content
    </HyperLink>
</Links>


/info-examples/web/svg-img-alt


The headers attribute in a `<table>` element must refer to a cell within the same table.

## Why it matters

In a table, a header cell and a data cell are programmatically related if they are coded in a way that assistive technologies can accurately determine their relationship.
When a data cell has a `headers` attribute that points to a cell in a different table, the programmatic relationship isn’t defined in a way that assistive technologies can recognize.
As a result, assistive technology users can’t tell which header cell goes with a given data cell.

## How to fix

For each `<td>` element, make sure the `headers` attribute points to a `<th>` element within the same table.
Note that the `headers` attribute is typically necessary only in extremely complex tables.

In most cases, using the `scope` attribute is sufficient and simpler to implement.
For details about accessible table markup, see [Tables – WAI Web Accessibility Tutorials](https://www.w3.org/WAI/tutorials/tables/).

## Example

<PassFailGrid>
<FailSection>

The code below includes two tables with the same column structure. The `headers` attributes in the second table reference `<th>` elements in the first table.
However, because assistive technologies expect a `headers` attribute to reference a cell within the same table, they might not identify any headers for the second table.

</FailSection>
<FailExample example={`
<table>
<caption>East Branch Members</caption>
<tr>
<th id="name">Name</th>
<th id="email">E-mail</th>
<th id="phone">Phone</th>
<th id="city">City</th>
</tr>
<tr>
<td [headers="name"]>Alexandra Gunderson</td>
<td [headers="email"]>alexg@company.com</td>
<td [headers="phone"]>1-234-5678</td>
<td [headers="city"]>Charlotte</td>
</tr>
…
</table>
<table>
<caption>West Branch Members</caption>
<tr>
<td headers="name">Mary Gonzales</td>
<td headers="email">mary@company.com</td>
<td headers="phone">1-234-5678</td>
<td headers="city">Portland</td>
</tr>
…
<td headers="name">Li Shen</td>
…
</table>
`} />
<PassSection>

`<th>` cells have been added to the second table.
Assistive technologies can correctly identify column headers for both tables.

</PassSection>
<PassExample example={`
<table>
<caption>East Branch Members</caption>
<tr>
<th id="name">Name</th>
<th id="email">E-mail</th>
<th id="phone">Phone</th>
<th id="city">City</th>
</tr>
<tr>
<td headers="name">Alexandra Gunderson</td>
<td headers="email">alexg@company.com</td>
<td headers="phone">1-234-5678</td>
<td headers="city">Charlotte</td>
</tr>
…
</table>
<table>
<caption>West Branch Members</caption>
<tr>
[<th id="name">Name</th>]
[<th id="email">E-mail</th>]
[<th id="phone">Phone</th>]
[<th id="city">City</th>]
</tr>
<tr>
<td headers="name">Mary Gonzales</td>
<td headers="email">mary@company.com</td>
<td headers="phone">1-234-5678</td>
<td headers="city">Portland</td>
</tr>
<td headers="name">Li Shen</td>
...
</table>
`} />
</PassFailGrid>

## About this rule

This rule passes if:

-   The `headers` attribute refers only to cells within the same table

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html">
        Understanding Success Criterion 1.3.1: Info and Relationships
    </HyperLink>
    <HyperLink href="https://www.w3.org/WAI/tutorials/tables/">Tables – WAI Web Accessibility Tutorials</HyperLink>
</Links>


/info-examples/web/td-headers-attr


A `<th>` element or element with `role="columnheader"` or `role="rowheader"` must have an associated `<td>` element.

## Why it matters

When people with good vision see a table with a row or column header that has no associated data cells, they can tell at a glance that the data is missing. People who use assistive technologies must explore a table deliberately to discover its contents; they are likely to have difficulty interpreting a table with missing data cells.

## How to fix

Make sure each `<th>` element has an associated data cell.
For details about accessible table markup, see [Tables – WAI Web Accessibility Tutorials](https://www.w3.org/WAI/tutorials/tables/).

## Example

<PassFailGrid>
<FailSection>

One header cell (`<th>` element) in this table has no associated data cells (`<td>` elements).
Assistive technology users are likely to find the table structure confusing.

</FailSection>
<FailExample example={`
<table>
<tr>
<td scope="col">Name</th>
<th scope="col">E-mail</th>
[<th scope="col">City</th>]
</tr>
<tr>
<td>Mary Gonzales</td>
<td>mary@company.com</td>
</tr>
<tr>
<td>Arvind Gupta</td>
<td>arvind@company.com</td>
</tr>
<tr>
<td>Selena Anders</td>
<td>selena@company.com</td>
</tr>
</table>
`} />
<PassSection>

All `<th>` elements have associated `<td>` elements.
The table structure is clear to everyone, and everyone can tell that some data cells are empty.

</PassSection>
<PassExample example={`
<table>
<tr>
<th scope="col">Name</th>
<th scope="col">E-mail</th>
<th scope="col">City</th>
</tr>
<tr>
<td>Mary Gonzales</td>
<td>mary@company.com</td>
[<td>Seattle</td>]
</tr>
<tr>
<td>Arvind Gupta</td>
<td>arvind@company.com</td>
[<td></td>]
</tr>
<tr>
<td>Selena Anders</td>
<td>selena@company.com</td>
[<td></td>]
</tr>
</table>
`} />
</PassFailGrid>

## About this rule

This rule passes if:

-   All table header cells are associated with data cells that exist

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html">
        Understanding Success Criterion 1.3.1: Info and Relationships
    </HyperLink>
    <HyperLink href="https://www.w3.org/WAI/tutorials/tables/">Tables – WAI Web Accessibility Tutorials</HyperLink>
</Links>


/info-examples/web/th-has-data-cells


The `lang` attribute must have a valid value.

## Why it matters

Sometimes a web page written in one language has a passage in a different language. When the language of such a passage is correctly identified (by a `lang` attribute on the containing element), browsers and assistive technologies can render the text more accurately; screen readers can use the correct pronunciation; visual browsers can display the correct characters; and media players can show captions correctly. All users find it easier to understand the content.

## How to fix

Provide a valid `lang` attribute value:

1. Identify the passage’s language.
2. Choose the corresponding language code from the [IANA Language Subtag Registry](http://www.iana.org/assignments/language-subtag-registry)
3. Make sure the value is spelled correctly.

## Example

<PassFailGrid>
<FailSection>

The default language of the page is English. A passage in Spanish has an invalid language attribute, so assistive technologies ignore it.
Screen readers announce the Spanish passage as if it were written in English, making it more difficult to understand.

</FailSection>
<FailExample example={`
<html lang="en-US>
…
<body>
…
<span id="original">The quick brown fox jumps over the lazy dog.</span>
…
<span id="translation" [lang="sp"]> El rápido zorro marrón salta sobre el perro perezoso.</span>
`} />
<PassSection>

The passage has the correct language attribute for Spanish.
Screen readers announce the passage using correct pronunciation, making it easier to understand.

</PassSection>
<PassExample example={`
<html lang="en-US>
…
<body>
…
<span id="original">The quick brown fox jumps over the lazy dog.</span>
…
<span id="translation" [lang="es"]> El rápido zorro marrón salta sobre el perro perezoso.</span>
`} />
</PassFailGrid>

## About this rule

This rule passes if:

-   The `lang` attribute has a valid value

## More examples

<Links>
    <HyperLink href="https://www.w3.org/WAI/WCAG21/Understanding/language-of-parts.html">
        Understanding Success Criterion 3.1.2: Language of Parts
    </HyperLink>
</Links>


/info-examples/web/valid-lang


Accessibility Insights for Android is no longer available for download. While existing installations remain functional, they will no longer receive updates (including security updates) going forward. [learn more](https://aka.ms/accessibility-insights-android/deprecated)

Release Notes for Accessibility Insights for Android

/docs/android/reference/releases


We have aggregated general FAQs here. Each tool has its dedicated FAQ sections:

- [FAQ for Accessibility Insights for Web](/docs/web/reference/faq/)
- [FAQ for Accessibility Insights for Windows](/docs/windows/reference/faq/)

## What does Accessibility Insights do with telemetry?

You have the option to opt into telemetry. When you do, Accessibility Insights collects anonymized data to identify the top accessibility issues found by users. This will help focus the accessibility tools and standards community to improve guidelines, rules engines, and features. [Read more about telemetry](/docs/general/telemetry/).

## How can I contribute to Accessibility Insights tools?

Accessibility Insights for Web and for Windows are open source on GitHub:

- [Go to the GitHub repository for Accessibility Insights for Web](https://github.com/microsoft/accessibility-insights-web)
- [Go to the GitHub repository for Accessibility Insights for Windows](https://github.com/microsoft/accessibility-insights-windows)

## Why can't I download Accessibility Insights for Android any more?

Accessibility Insights for Android is no longer available for download. While existing installations remain functional, they will no longer receive updates (including security updates) going forward. [learn more](https://aka.ms/accessibility-insights-android/deprecated)


/docs/general/faq


The Accessibility Insights team is committed to providing tools that are fast, easy to use, and accurate.

Teams who are new to Accessibility Insights sometimes see failures that appear to be false positives rather than legitimate accessibility issues. In most cases, investigation has revealed that Accessibility Insights has identified a legitimate accessibility issue. In the few cases where an actual false positive has been discovered, the Accessibility Insights team has quickly fixed it and deployed an update to ensure zero false positives.

We have two approaches to reported false positives:

## 1. Investigate and fix

For verified false positives, we will try to provide a fix as quickly as possible.

## 2. Clarify and build consensus

Sometimes it isn't immediately clear whether a failure is a false positive or a legitimate accessibility issue. In this case, Accessibility Insights has historically raised the issue to internal stakeholders to build consensus.

Building Accessibility Insights is an ongoing learning process for everyone involved. The Accessibility Insights team is committed not only to improving our tools, but also to collaborating with the people
who use them, consulting with accessibility experts across the community, and documenting key decisions.

To ask questions or to file issues:

-   [Help for Accessibility Insights for Web](/docs/web/reference/help/)
-   [Help for Accessibility Insights for Windows](/docs/windows/reference/help/)


/docs/general/quality


For support on individual Accessibility Insights tools and their respective documentation:

-   [Help for Accessibility Insights for Web](/docs/web/reference/help/)
-   [Help for Accessibility Insights for Windows](/docs/windows/reference/help/)


/docs/general/support


When you opt into telemetry, Accessibility Insights collects telemetry data, which we share back to the community, to have a better understanding on what accessibility issues are more common and how users are leveraging the tool to improve the overall accessibility of their websites and Windows applications.

By opting into telemetry, you help develop inclusive software and improve the existing tools. This data gives you a voice in the community and in the development of Accessibility Insights, and can influence the focus of the accessibility tools and the standards community to improve guidelines, rules engines, and features.

Accessibility Insights will share, via a blog post, regular reports on any trends observed, with the goal of bringing more clarity to the accessibility space for everyone.

While we appreciate the telemetry insight as it's very valuable, we also know and respect that not everyone wants to share this data, so we ask for your permission every time you install our tools in a new device and offer the ability to disable telemetry in the settings:

-   [Learn how to disable telemetry in Accessibility Insights for Web](/docs/web/reference/telemetry/)
-   [Learn how to disable telemetry in Accessibility Insights for Windows](/docs/windows/reference/telemetry/)

Finally, we want to reiterate that we take your privacy very seriously. All collected data is anonymized and has gone through a privacy review. If you want to learn more about what data we collect, our code is open source:

-   [Go to the GitHub repository for Accessibility Insights for Web](https://github.com/microsoft/accessibility-insights-web)
-   [Go to the GitHub repository for Accessibility Insights for Windows](https://github.com/microsoft/accessibility-insights-windows)


/docs/general/telemetry


## What is an assessment?

An assessment is a comprehensive process that measures compliance with [Web Content Accessibility Guidelines (WCAG) 2.2 Level AA](https://www.w3.org/WAI/WCAG22/quickref/?versions=2.2&levels=aaa) success criteria. The assessment process currently includes 24 tests, and each test covers one or more accessibility requirements.

There are three types of requirement:

-   **Automated** – the tool identifies instances and evaluates them automatically.
-   **Assisted** – the tool actively helps you identify or evaluate instances.
-   **Manual** – the tool provides instructions for identifying and evaluating instances.

Note: Completing an assessment requires you to use standard keyboard commands and to visually identify interactive interface elements.

## How to complete an assessment

### Get ready to test

1. In Chrome or the new Microsoft Edge, navigate to the page you want to test (aka the target page).
1. Open Accessibility Insights for Web:

    - Select the extension icon.

    or

    - Press Alt+Shift+K (Option+Shift+K for macOS) ([Customize this keyboard shortcut](/docs/web/reference/keyboard/)).

    or

    - Use these keyboard commands:

        Windows or Linux:

        1. Press Shift+Alt+T or F10 to set focus on the browser's address bar.
        1. Press the Left arrow to set focus on the Accessibility Insights for Web extension.
        1. Press the Space key to open the extension.

        MacOS:

        1. Press ⌘+L to set focus on the browser's address bar.
        1. Press the Tab key to set focus on the Accessibility Insights for Web extension.
        1. Press the Space key to open the extension.

    The Accessibility Insights for Web extension will open to the **Launch pad**.

    ![Four options are available in the Launch pad: FastPass, Quick Assess, Assessment, Ad hoc tools](/assets/web/getstarted/general/launch-pad.png)

1. In the **Launch pad**, select **Assessment**.

    A secondary browser window will open to an overview of the assessment process and results. At this point, the assessment is 100% incomplete, so no results are available.

    ![Target page and the overview displayed side-by-side](/assets/web/getstarted/assessment/overview-start.png)

### Run the automated checks

1. In the navigation pane, select **Automated checks**.

    Automated checks will run on your target page. Activate the visual helper to highlight failure instances in the target page.

2. Review the automated check results.

You can review the automated check results in the Accessibility Insights for Web page.

![Failures listed in the Accessibility Insights for Web page](/assets/web/getstarted/assessment/automated-checks-failed-rules.png)

##### Review results in the Accessibility Insights for Web page

By default, the Accessibility Insights for Web page shows:

-   The total number of failed instances
-   A list of any accessibility rules that were violated
-   The number of failed instances for each rule
-   A visual helper toggle that allows you to quickly show or hide failure highlighting in the target page

![Failed rules in the Accessibility Insights for Web page](/assets/web/getstarted/assessment/automated-checks-failed-rules.png)

A rule can be expanded to show information about its failed instances.
Rules can be expanded or collapsed:

-   All at once by using **Expand all / Collapse all**
-   Individually by clicking a rule, or by tabbing to it and pressing **Enter**

Expanding a rule:

-   Shows links to additional information about the rule, including why it matters, examples, and detailed instructions for fixing
-   Highlights its failed instances in the target page
-   Shows the failed instances in a list

Each failed instance includes:

-   Unique identifying information about the element that failed (for example, a CSS selector)
-   How to fix the detected issue
-   Additional information to help identify the element (some rules only)
-   Buttons to take action on the individual issue. You can:
    -   **File an issue** in your GitHub or Azure Boards repository.
    -   **Copy failure details** to your clipboard and paste them into the tool or document of your choice.

![Failed instances in the Accessibility Insights for Web page](/assets/web/getstarted/assessment/automated-checks-rule-expanded.png)

Selecting a failed instance highlights it in the target page. You can select multiple instances.
An instance can be selected or deselected by clicking it, or by tabbing to it and pressing **Enter**.

![One failed instance selected in the Accessibility Insights for Web page and highlighted in the target page](/assets/web/getstarted/fastpass/automated-checks-instance-selected.png)

### Complete the assisted and manual tests

Each of the remaining tests covers a set of related requirements. We recommend completing the tests and requirements in the order they appear in the navigation pane.

1.  In the navigation pane, collapse the list of automated checks by selecting **Automated checks**.

2.  Select the next test (**Keyboard**).

    The navigation pane will expand to show all of the test requirements.

3.  Optional: To learn more about the test:

    1. In the navigation pane, under the test name, select **Getting started**.

        The main pane will update to show introductory information about the test.

    1. In the main pane, next to the page title, select **Guidance <InfoIcon />**.

        A new browser tab will open with additional information about the test:

        - Why it matters
        - Do-and-don't design guidelines
        - Links to relevant WCAG success criteria, sufficient techniques, and common failures.

        ![Test guidance opened in a new browser tab.](/assets/web/getstarted/assessment/test-guidance.png)

4.  In the navigation pane, under **Keyboard**, select the first requirement (**Keyboard navigation**).

    The main pane will update to show test instructions for the selected requirement.

    ![Test instructions in the main pane](/assets/web/getstarted/assessment/how-to-test.png)

5.  Optional: To learn more about a requirement, select **Guidance <InfoIcon />**.

    A side panel will open with detailed information about the requirement:

    -   Why it matters
    -   From a user's perspective (where applicable). This is a contribution from the Design for People Guidelines.
    -   How to fix
    -   Examples
    -   Code snippets (where applicable)
    -   Links to relevant WCAG success criteria, sufficient techniques, and common failures.

    ![Requirement guidance in a side panel](/assets/web/getstarted/assessment/requirement-guidance.png)

6.  Read the instructions under **How to test**.

7.  Evaluate the instances and record your results.

    Some requirements in an assessment require you to manually identify the instances to evaluate. (All of the requirements in the **Keyboard** test require you to manually identify instances.)

    Some requirements automatically generate a list of instances to evaluate. (The first requirement that generates a list of instances is in the **Landmarks** test.)

    -   For manual requirements:

        1. Select **Pass** or **Fail** for the requirement.

            Tip: You can reset a requirement to its original indeterminate state by selecting **Undo** <UndoIcon />.

        1. If the requirement fails, add a failure instance. (If the requirement passes, no further input is needed.)

        ![Keyboard navigation requirement shows failed when one failure instance added](/assets/web/getstarted/assessment/manual-fail.png)

    -   For assisted requirements, select **Pass** or **Fail** for each instance.

        Tip: You can reset an instance to is original indeterminate state by selecting **Undo** <UndoIcon />.
        Tip: After you mark all the failures, you can pass the remaining instances by selecting **Pass unmarked instances**.

        ![Link function requirement shows failed when instance marked as failed](/assets/web/getstarted/assessment/assisted-fail.png)

8.  Select the next requirement, follow the instructions, and record your results.

9.  Repeat with the remaining tests.

10. When every requirement in every test is marked as **Pass** or **Fail**, your assessment is complete.

### View a summary of the assessment results

At any time, select **Overview** in the navigation pane.

![Overview showing results of a completed assessment](/assets/web/getstarted/assessment/overview-end.png)

### Share a detailed report of the assessment results

1. In command bar near the top of the page, select **Export result**.

    A dialog will open.

2. Optional: In the dialog, provide a description for the report.
3. Select **Export** and choose one of the options.

### To export as HTML

The HTML report groups results by the tests in Assessment and provides a summarized view of all the requirements and their state (_pass, fail_ or _incomplete_).

1. In the **Export** dialog, under the **Export** dropdown, select **Export as HTML**.

An HTML report will automatically download to your computer. Depending on your browser, the report might open automatically in a new browser tab, or you might have to open it manually.
![Report showing results of a completed assessment](/assets/web/getstarted/assessment/report.png)

### To export as JSON

The JSON report groups results by the Success Criteria and provides a list of all the requirements under each S.C.
The date for the JSON report is exported in ISO 8601 format and the report version is the same as the Accessibility Insights for Web extension version.

1. In the **Export** dialog, under the **Export** dropdown, select **Export as JSON**.

A JSON report will automatically download to your computer.

## Start Over

### Start a new assessment

Data collected in an assessment will persist until you start a new assessment.

1. In the command bar near the top of the page, select **Start over** > **Start over assessment**.

    Note: Depending on the width of your browser window, you might have to select the **More items** disclosure button to access **Start over**.

1. In the confirmation dialog, select **Start over**.

    All data in the assessment will be cleared, and you will automatically navigate to the assessment **Overview**.

### Start over a single test

Data collected in a specific test will persist until you start over the test (or start a new assessment).

1. Navigate to the test you want to start over.

1. In the command bar near the top of the page, select **Start over** > **Start over \<test name\>**.

    Note: Depending on the width of your browser window, you might have to select the **More items** disclosure button to access **Start over**.

1. In the confirmation dialog, select **Start over**.

    All data in the test will be cleared, and you will automatically navigate to the first requirement in the test you started over.

## Save and Load an in-progress assessment

At any time, you can save an in-progress assessment and load it later on.

### Save an assessment

1. In the command bar near the top of the page, select **Save assessment**.

    The assessment file (_a11ywebassessment_) will automatically download to your computer.

### Load an assessment

1. In the command bar near the top of the page, select **Load assessment**.

    A file explorer will open.

1. In the file explorer, select the assessment file you want to load.

    Note: Data collected in an assessment persists until you load or start a new assessment. If there is an in progress assessment already, a confirmation dialog will appear. Loading an assessment will clear all data in the local in-progress assessment.


Assessment in Accessibility Insights for Web

/docs/web/getstarted/assessment


## What is FastPass?

FastPass is a lightweight, _two-step_ process that helps developers identify common, high-impact accessibility issues in less than five minutes.

1. _Automated checks_ - the tool automatically checks for compliance with dozens of accessibility requirements. Our automated checks are powered by [axe-core](https://www.npmjs.com/package/axe-core).
1. _Assisted test for tab stops_ - the tool provides clear instructions, partial automation, and a visual helper that makes it easy to identify critical accessibility issues related to keyboard access, such as missing tab stops, keyboard traps, and incorrect tab order.
1. _Needs review_ - the tool provides instances that need to be reviewed by a human to determine whether they pass or fail. 

We recommend developers run a FastPass before every check-in of UI code.

Notes:

-   Completing a FastPass requires you to use standard keyboard commands and to visually identify interactive interface elements.
-   Automated checks can detect some common accessibility problems such as missing or invalid properties. But most accessibility problems can only be discovered through manual testing. The best way to evaluate web accessibility compliance is to complete an assessment.

## How to complete a FastPass

### Get ready to test

1.  In Chrome or the new Microsoft Edge, navigate to the page you want to test (aka the target page).
1.  Open Accessibility Insights for Web:

    -   Select the extension icon.

    or

    -   Press Alt+Shift+K (Option+Shift+K for macOS) ([Customize this keyboard shortcut](/docs/web/reference/keyboard/)).

    or

    -   Use these keyboard commands:

        -   Windows or Linux:

            1. Press Shift+Alt+T or F10 to set focus on the browser's tool bar.
            1. Press the Left Arrow key to set focus on the Accessibility Insights for Web extension.
            1. Press the Space key to open the extension.

        -   macOS:

            1. Press ⌘+L to set focus on the browser's tool bar.
            1. Press the Tab key to set focus on the Accessibility Insights for Web extension.
            1. Press the Space key to open the extension.

    The Accessibility Insights for Web extension will open to the **Launch Pad**.

    ![Four options available in the Launch pad: FastPass, Quick Assess, Assessment, Ad hoc tools](/assets/web/getstarted/general/launch-pad.png)

### Run automated checks

1. In the **Launch pad**, select **FastPass**.

    Automated checks will run on your target page. Individual failure instances will be highlighted directly in the target page, and the Accessibility Insights for Web page will open in a new browser window.

1. Review the automated check results.

    You can review the automated check results directly in the target page or in the Accessibility Insights for Web page.

![Failures highlighted on the target page and listed in the Accessibility Insights for Web page](/assets/web/getstarted/fastpass/automated-checks-start.png)

##### Review results in the Accessibility Insights for Web page

By default, the Accessibility Insights for Web page shows:

-   The total number of failed instances
-   A list of any accessibility rules that were violated
-   The number of failed instances for each rule
-   A visual helper toggle that allows you to quickly show or hide failure highlighting in the target page

![Failed rules in the Accessibility Insights for Web page](/assets/web/getstarted/fastpass/automated-checks-failed-rules.png)

A rule can be expanded to show information about its failed instances.
Rules can be expanded or collapsed:

-   All at once by using **Expand all / Collapse all**
-   Individually by clicking a rule, or by tabbing to it and pressing **Enter**

Expanding a rule:

-   Shows links to additional information about the rule, including why it matters, examples, and detailed instructions for fixing
-   Highlights its failed instances in the target page
-   Shows the failed instances in a list

Each failed instance includes:

-   The class name of the element that failed
-   How to fix the detected issue
-   Additional information to help identify the element (some rules only)
-   A disclosure button that reveals more actions to take on the failed instance. You can:
    -   **File an issue** in your GitHub or Azure Boards repository.
    -   **Copy failure details** to your clipboard and paste them into the tool or document of your choice.

![Failed instances in the Accessibility Insights for Web page](/assets/web/getstarted/fastpass/automated-checks-rule-expanded.png)

Selecting a failed instance highlights it in the target page. You can select multiple instances.
An instance can be selected or deselected by clicking it, or by tabbing to it and pressing **Enter**.

![One failed instance selected in the Accessibility Insights for Web page and highlighted in the target page](/assets/web/getstarted/fastpass/automated-checks-instance-selected.png)

##### Review results in the target page

Selecting a failure icon <ImportantIcon /> opens a dialog with the following information:

-   A description of the rule that failed
-   The rule name, which links to detailed information about the rule
-   The number of the relevant WCAG success criteria, which links to detailed information about the criterion
-   The path to the element that generated the failure
-   Three buttons:
    -   **Inspect HTML** takes you directly to the element's code. (You must open the Dev Tools panel to enable this button.)
    -   **Copy failure details** copies all of the details to your computer's clipboard.
    -   **File issue** allows you to easily [file an issue](/docs/web/getstarted/issuefiling/) on GitHub or Azure Boards.
-   Instructions for fixing the problem

![Failure details in a dialog on the target page](/assets/web/getstarted/fastpass/automated-checks-failure-in-target-page.png)

### Complete the assisted test for Tab stops

1. In the navigation pane, select **Tab stops**.
1. Refresh the target page to put it into its default state.
1. In **Tab stops**, turn on the **Show tab stops** toggle.

    An empty circle will highlight the element that has input focus. It might be necessary to tab once to move focus into the page.

    ![An empty circle highlighting the first tab stop in the target page](/assets/web/getstarted/fastpass/tab-stops-start.png)

1. Use standard keyboard commands to move input focus through all the interactive elements in the page:

    - Use the Tab key and Shift+Tab key to navigate between controls.
    - Use the arrow keys to navigate between the focusable elements within a composite control, such as the items in a menu.

    As you navigate away from each element, its place in the tab order will be displayed as a number.

1. As you navigate through the elements, look for these accessibility problems:

    - An interactive element can't be reached using the Tab or arrow keys.
    - An interactive element "traps" input focus and prevents navigating away.
    - An interactive element doesn't give a visible indication when it has input focus.
    - The focus order is inconsistent with the logical order that's communicated visually.
    - Input focus moves unexpectedly without the user initiating it.

#### Review the partial automation results in the Accessibility Insights for Web page

In some cases, the Tab stops test is able to automatically detect possible Tab stops issues.

A dialog will appear in the Tab stops page indicating that _Possible failures were auto-detected_ after you have completed the navigation through the elements and returned to the Accessibility Insights for Web page.

![Accessibility Insights for Web Tab stops page.There is a dialog that says: "Possible failures auto-detected. Review each finding to be sure it's valid. Add any more failures you discovered manually" ](/assets/web/getstarted/fastpass/Tabstops-dialog.png)

These possible issues are highlighted directly in the target page and described in the Accessibility Insights for Web page.

A possible Tab stops failure auto-detected will:

-   Mark the requirement as _Fail_
-   Add a failure instance for that rule

Each automatic failure instance includes:

-   A note that the issue was automatically detected and needs a human to review
-   A short description on why this element was added (e.g. _Unreachable element_)
-   The path to the element that generated the failure
-   An **Edit** button that allows you to edit the information on the failure instance
-   A **Delete** button that allows you to delete that instance

![The target page shows a circle with an x and a dotted line. In the Accessibility Insights Tab Stops page, the Keyboard Navigation requirement is marked as Fail and there is a failure instance that says the element was not reached using keyboard" ](/assets/web/getstarted/fastpass/tabstops-auto-detected.png)

_Note: Turning the visual helper on / off will show / hide the visualizations and previously found automatic instances. You can use the **Start Over** button to restart the Tab stops test_

#### Record your results

After reviewing any partial automation results, record your results by marking each requirement as **Pass** or **Fail**. Optionally, if you find any failures, you can add a failure instance by selecting the **+** **Add a failure instance** button.

![A number in a circle on top of each element in the tab order with arrows between the circles](/assets/web/getstarted/fastpass/tab-stops-end.png)

When you have completed the assisted test for Tab stops, your FastPass is complete.

### Optional: Evaluate instances that need review

Sometimes an automated check encounters an element coded in a way that it can't be evaluated automatically. For example, the color-contrast rule can't determine the contrast ratio of text that's superimposed on an image or gradient. Such instances need to be reviewed by a human to determine whether they pass or fail.

#### Show instances that need review

1. In the navigation pane, select **Needs review**.
1. In the command bar, select **Start over**. After a moment, any instances that need review will be displayed in the main panel.
1. Expand a rule to see its instances.
1. To determine whether an instance passes or fails, follow the **How to check** instructions.

![Needs review selected in the navigation pane, and instances that need review listed in the main panel](/assets/web/getstarted/fastpass/needs-review.png)

### Share a detailed report

1. In the command bar, select **Export result**.

    - Optional: Provide a description to include in the report.

1. Use the browser's download bar to open the report or view the file location.


FastPass in Accessibility Insights for Web

/docs/web/getstarted/fastpass


Accessibility Insights for Web makes it easy to file issues directly from automated check failures.

## How to file issues

### Configure your issue filing service

1.  Open Accessibility Insights for Web:

    -   Select the extension icon.

    or

    -   Press Alt+Shift+K (Option+Shift+K for macOS) ([Customize this keyboard shortcut](/docs/web/reference/keyboard/)).

    or

    -   Use these keyboard commands:

        -   Windows or Linux:

            1. Press Shift+Alt+T or F10 to set focus on the browser's tool bar.
            1. Press the Left Arrow key to set focus on the Accessibility Insights for Web extension.
            1. Press the Space key to open the extension.

        -   macOS:

            1. Press ⌘+L to set focus on the browser's tool bar.
            1. Press the Tab key to set focus on the Accessibility Insights for Web extension.
            1. Press the Space key to open the extension.

    The Accessibility Insights for Web extension will open to the **Launch Pad**.

    ![The Launch pad open with the mouse hovering over the Settings button](/assets/web/getstarted/issuefiling/launch-pad-settings-button.png)

1.  Open **Settings**:

    -   Use the mouse:

        1. Click **Manage settings** <SettingsIcon />.
        1. In the menu, Click **Settings**.

    or

    -   Use these keyboard commands:

        1. Use the Tab key to navigate to **Manage settings** <SettingsIcon />.
        1. Press the Enter key to open the menu.
        1. Press the Enter key again to select **Settings.**

    A **Settings** panel will open in a new browser window.

#### To configure GitHub issue filing

1. In the **Settings** panel, under **Issue filing**, select **GitHub**.
1. Enter the URL of your GitHub repository's **Issues** tab. Example: https://github.com/owner/repo/issues
1. Close the **Settings** panel (X icon).

or

1. Use the Tab key to set focus on the currently selected **Issue filing** option. If needed, use the Up arrow or Down arrow key to select **GitHub**.
1. Tab to the **Enter your GitHub issues URL** box, then enter the URL. Example: https://github.com/owner/repo/issues
1. Tab to the **Close Settings Panel** button, then press the Enter key.

![Accessibility Insights for Web with the Settings panel open. Under Issue filing, GitHub is selected.](/assets/web/getstarted/issuefiling/settings-github.png)

#### To configure Azure Boards issue filing

1. In the **Settings** panel, under **Issue filing**, select **Azure Boards**.
1. Enter the URL of your Azure Boards project. Example: https://dev.azure.com/org/project
1. Select the field where you want issue details to appear:

    1. If your project tracks _bugs_, select **Repro steps**.
    1. If your project tracks _issues_, select **Description**.

1. Close the **Settings** panel.

or

1. Use the Tab key to set focus on the currently selected **Issue filing** option. If needed, use the Up arrow or Down arrow key to select **Azure Boards**.
1. Tab to the **Enter your Azure Boards project link** box, then enter the URL. Example: https://dev.azure.com/org/project
1. Tab to the **Select a field for issue details** dropdown, use the Up arrow or Down arrow key to select an option, and then press the Enter key:

    1. If your project tracks _bugs_, select **Repro steps**.
    1. If your project tracks _issues_, select **Description**.

1. Tab to the **Close Settings Panel** button, then press the Enter key.

![Accessibility Insights for Web with the Settings panel open. Under Issue filing, Azure Boards is selected.](/assets/web/getstarted/issuefiling/settings-azureboards.png)

### Run automated checks

Detailed instructions for running automated checks are available in [FastPass](/docs/web/getstarted/fastpass/).

### File an issue

1. Find the failure instance you want to file as an issue.

2. Open a new issue form:

    1. In the bottom right corner of the failure instance card, select **More actions** (vertical ellipsis icon).
    1. In the menu that opens, select **File issue**.

    or

    1. Use the Tab key to set focus on a failure instance's **More actions** button, then press the Enter key to open the menu.
    1. Press the Enter key again to select **File issue**.

    ![A failure instance with the More actions menu open and the mouse hovering over File issue.](/assets/web/getstarted/issuefiling/file-issue-option.png)

    If you're using GitHub, a **New Issue** form will open:

    ![A GitHub New Issue form with failure details.](/assets/web/getstarted/issuefiling/github-new-issue.png)

    If you're using Azure Boards, and your project tracks _bugs_, a **New Bug** form will open:

    ![An Azure Boards New Bug form with failure details.](/assets/web/getstarted/issuefiling/azureboards-new-issue.png)

    If you're using Azure Boards, and your project tracks _issues_, a **New Issue** form will open:

    ![An Azure Boards New Issue form with failure details.](/assets/web/getstarted/issuefiling/azureboards-new-bug.png)

    If you're using Azure Boards, a **Sever Error** page will open if there's a problem with your issue filing configuration:

    ![An Azure Boards Server Error page.](/assets/web/getstarted/issuefiling/azureboards-server-error.png)

    To resolve this problem:

    1. In Accessibility Insights, go to **Settings** > **Issue filing** > **Select a field for issue details**, and choose a different option.
    1. If the problem persists, make sure the bug or issue [work item type is enabled](https://docs.microsoft.com/en-us/azure/devops/organizations/settings/work/customize-process-work-item-type?view=azure-devops#enable-disable) in Azure DevOps.

3. The **New Bug** or **New Issue** form will open with failure details automatically populated. If desired, edit the information in the form.

4. Save the new issue:

    - If you're using GitHub:

        - Select the **Submit new issue** button.

        or

        - Use the Tab key to set focus on the **Submit new issue** button, then press the Enter key.

    - If you're using Azure Boards:

        - Select the **Save** button.

        or

        - Press Ctrl+S on your keyboard.

        or

        - Use the Tab key to set focus on the **Save** button, then press the Enter key.

## Copy failure details

If you want to record an issue without filing it on GitHub or Azure Boards, you can copy the failure details to your clipboard and then paste them into the tool or document of your choice.

1. In the bottom right corner of a failure instance card, select **More actions** (vertical ellipsis icon).
1. In the menu that opens, select **Copy failure details**.

or

1. Use the Tab key to set focus on a failure instance's **More actions** button, then press the Enter key to open the menu.
1. Use the Up arrow or Down arrow key to select **Copy failure details**.
1. Press the Enter key to copy the failure details to your clipboard.

![A failure instance with the More actions menu open and the mouse hovering over Copy failure details.](/assets/web/getstarted/issuefiling/copy-failure-details-option.png)


Issue filing in Accessibility Insights for Web

/docs/web/getstarted/issuefiling


## What is Quick Assess?

Quick Assess is a process that measures limited compliance with [Web Content Accessibility Guidelines (WCAG) 2.1 Level AA](https://www.w3.org/WAI/WCAG21/quickref/?versions=2.1&levels=aaa) success criteria with 10 requirements and each test covers one accessibility requirement.

There are three types of requirement:

-   **Automated** – the tool identifies instances and evaluates them automatically.
-   **Assisted** – the tool actively helps you identify or evaluate instances.
-   **Manual** – the tool provides instructions for identifying and evaluating instances.

Note: Completing a quick assess pass requires you to use standard keyboard commands and to visually identify interactive interface elements.

## How to complete a Quick Assess

### Get ready to test


1. In Chrome or the new Microsoft Edge, navigate to the page you want to test (aka the target page).
1. Open Accessibility Insights for Web:

    - Select the extension icon.

    or

    - Press Alt+Shift+K (Option+Shift+K for macOS) ([Customize this keyboard shortcut](/docs/web/reference/keyboard/)).

    or

    - Use these keyboard commands:

        Windows or Linux:

        1. Press Shift+Alt+T or F10 to set focus on the browser's address bar.
        1. Press the Left arrow to set focus on the Accessibility Insights for Web extension.
        1. Press the Space key to open the extension.

        MacOS:

        1. Press ⌘+L to set focus on the browser's address bar.
        1. Press the Tab key to set focus on the Accessibility Insights for Web extension.
        1. Press the Space key to open the extension.

    The Accessibility Insights for Web extension will open to the **Launch pad**.

    ![Four options are available in the Launch pad: FastPass, Quick Assess, Assessment, Ad hoc tools](/assets/web/getstarted/general/launch-pad.png)

2. In the **Launch pad**, select **Quick Assess**.

    A secondary browser window will open to an overview of the quick assess process and results. At this point, the quick assess pass is 100% incomplete, so no results are available.

    ![Target page and the overview displayed side-by-side](/assets/web/getstarted/quickassess/overview.png)

### Run the automated checks

1. In the navigation pane, select **Automated checks**.

    The navigation pane will expand to show all of the automated checks, listed in alphabetical order.

2. Optional: To learn more about automated checks:

    1. In the navigation pane, under **Automated checks**, select **Getting started.**

        The main pane will update to show a brief description of automated checks.

    2. In the main pane, next to the page title, select **Guidance <InfoIcon />**.

        A new browser tab will open with additional information about automated checks.

3. In the navigation pane, under **Getting started**, select the first rule, **area-alt**.

    Within a few seconds, Accessibility Insights for Web will run all of the automated checks. The navigation pane will update to show the outcome for each rule checked.

    ![Automated checks results displayed in the navigation pane](/assets/web/getstarted/quickassess/automated-checks.png)

4. Explore the results:

    - To see failure instances: In the navigation pane, select a rule that failed.
    - To learn more about a rule: In the main pane, under **How to test** select **See more info here**.
    - To see failure instances highlighted directly in your target page:

        - In the main pane, turn on the **Visual helper** toggle (highlights all failure instances simultaneously).

        or

        - In the main pane, select one or more check boxes (highlights only selected failure instances).

    ![Failure instances highlighted on the target page](/assets/web/getstarted/quickassess/visual-toggle.png)

### Complete the assisted and manual tests

Each of the remaining ten requirements covers accessibility requirements. We recommend completing the tests and requirements in the order they appear in the navigation pane.

1.  In the navigation pane, collapse the list of automated checks by selecting **Automated checks**.

2.  Select the next test (**Keyboard**).

    The navigation pane will expand to show all of the test requirements.

3.  Optional: To learn more about (**Why it Matters**), view this information in the grey box on the right side under  (**Why it Matters.**)

4.  Optional: To learn more about this requirement, review the information and links on the _Why it Matters_ section. 

A side panel will open with detailed information about the requirement: 
        - Why it matters
        - From a user's perspective (where applicable). This is a contribution from the Design for People Guidelines.  
        - How to fix 
        - Examples 
        - Code snippets (where applicable) 
        - Links to relevant WCAG success criteria, sufficient techniques, and common failures.

    ![Requirement guidance in a side panel](/assets/web/getstarted/quickassess/examples.png)

5.  Read the instructions under **How to test**.

6.  Evaluate the instances and record your results.

    Some requirements in a quick assess require you to manually identify the instances to evaluate. (All of the requirements in the **Keyboard** test require you to manually identify instances.)

    Some requirements automatically generate a list of instances to evaluate. (The first requirement that generates a list of instances is in the **Link Purpose** requirement)

    -   For manual requirements:

        1. Select **Pass** or **Fail** for the requirement.

            Tip: You can reset a requirement to its original indeterminate state by selecting **Undo** <UndoIcon />.

        1. If the requirement fails, add a failure instance. (If the requirement passes, no further input is needed.)

        ![Keyboard navigation requirement shows failed when one failure instance added](/assets/web/getstarted/quickassess/failure-instance.png)

    -   For assisted requirements, select **Pass** or **Fail** for each instance.

        Tip: You can reset an instance to is original indeterminate state by selecting **Undo** <UndoIcon />.
        Tip: After you mark all the failures, you can pass the remaining instances by selecting **Pass unmarked instances**.

        ![Link purpose requirement shows passed when all instances are marked as pass](/assets/web/getstarted/quickassess/pass-requirement.png)

7.  Select the next requirement, follow the instructions, and record your results.

8.  Repeat with the remaining requirements.

9.  When every requirement in every test is marked as **Pass** or **Fail**, your quick assess is complete.

### View a summary of the quick assess results

At any time, select **Overview** in the navigation pane.

![Overview showing current results for an in progress quick assess](/assets/web/getstarted/quickassess/overview-updated.png)

### Share a detailed report of the assessment results

1. In the command bar near the top of the page, select **Export result**.

    A dialog will open.

2. Optional: In the dialog, provide a description for the report.
3. Select **Export** and choose one of the options.

### To export as HTML

The HTML report groups results by the tests in Quick Assess and provides a summarized view of all the tests and their state (_pass, fail_ or _incomplete_).

1. In the **Export** dialog, under the **Export** dropdown, select **Export as HTML**.

An HTML report will automatically download to your computer. Depending on your browser, the report might open automatically in a new browser tab, or you might have to open it manually.
![Report showing results of a completed assessment](/assets/web/getstarted/quickassess/report.png)

### To export as JSON

The JSON report groups results by the Success Criteria and provides a list of all the requirements under each S.C.
The date for the JSON report is exported in ISO 8601 format and the report version is the same as the Accessibility Insights for Web extension version.

1. In the **Export** dialog, under the **Export** dropdown, select **Export as JSON**.

A JSON report will automatically download to your computer.

## Start Over

### Start a new Quick Assess

Data collected in a Quick Assess will persist until you start a new Quick Assess.

1. In the command bar near the top of the page, select **Start over** > **Start over Quick Assess**.

    Note: Depending on the width of your browser window, you might have to select the **More items** disclosure button to access **Start over**.

1. In the confirmation dialog, select **Start over**.

    All data in the quick assess will be cleared, and you will automatically navigate to the Quick Assess **Overview**.

## Move to Assessment

At any time, you can move your data and test results from Quick Assess into Assessment.  If you have an existing assessment in progress, you will be notified through a dialog. 

1. In the command bar near the top of the page, select **Move to assessment**. 

2. Once you are in the assessment view, you will have the existing data, that contains quick assess results, and the functionality to complete additional tests and requirements. 

3. Alternatively, you can also move to Assessment using the **Complete** button on the last requirement page of Quick Assess.  

    *Note: Data collected in an assessment persists until you load or start a new assessment. If there is an in progress assessment already, a confirmation dialog will appear. Loading an assessment or quick assess pass will clear all data in the local in-progress assessment.*


Quick Assess in Accessibility Insights for Web

/docs/web/getstarted/quickassess


[Download for Web](/downloads/)

## What's Accessibility Insights for Web?

Accessibility Insights for Web is an extension for Chrome and [the new Microsoft Edge](https://www.microsoft.com/en-us/edge) that helps developers find and fix accessibility issues in web apps and sites.

The tool supports two primary scenarios:

-   _FastPass_ is a lightweight, two-step process that helps developers identify common, high-impact accessibility issues in less than five minutes.
    -   _Automated checks_ - the tool automatically checks for compliance with approximately 50 accessibility requirements.
    -   _Tab stops_ - the tool provides clear instructions, partial automation, and a visual helper that makes it easy to identify critical accessibility issues related to keyboard access, such as missing tab stops, keyboard traps, and incorrect tab order.
-   _Assessment_ allows anyone with HTML skills to verify that a web app or web site is compliant with [Web Content Accessibility Guidelines (WCAG) 2.1 Level AA](https://www.w3.org/WAI/WCAG21/quickref/?versions=2.1&levels=aaa).
    -   _Automated checks_ - the tool automatically checks for compliance with approximately 50 accessibility requirements.
    -   _Manual tests_ - the tool provides step-by-step instructions, examples, and how-to-fix guidance for approximately 20 tests; many tests are "assisted", which means that the tool identifies the test instances or provides a visual helper.

## Get Started

Get started by watching a video:

-   [Overview](https://www.youtube.com/watch?v=XVvBJoEe4Is)
-   [Assessment](https://www.youtube.com/watch?v=m1l7ghxOKF0)

Or read a tutorial:

-   [FastPass](/docs/web/getstarted/fastpass/)
-   [Issue filing](/docs/web/getstarted/issuefiling/)
-   [Assessment](/docs/web/getstarted/assessment/)

## Keyboard Shortcuts

Increase your productivity with Accessibility Insights for Web's keyboard shortcuts.

-   [Keyboard shortcuts](/docs/web/reference/keyboard/)

## Privacy

With your consent, Accessibility Insights for Web collects anonymized usage data and crash report information. You may opt out at any time by disabling it:

-   [How do I disable telemetry?](/docs/web/reference/telemetry/)

## Contributing

Accessibility Insights for Web is open source on GitHub:

-   [Go to the GitHub repository for Web](https://github.com/microsoft/accessibility-insights-web)

## Additional Help

For additional help such as reporting issues and asking questions:

-   [Help for Accessibility Insights for Web](/docs/web/reference/help/)


/docs/web/overview


> Prerequisite: [Install Accessibility Insights for Web](/downloads/) if you haven't already.

If you don't see an answer to your question here, check out [Help](/docs/web/reference/help/) and [Release notes](/docs/web/reference/releases/).

## How do I run Accessibility Insights for Web on local files?

1. Open your browser's Extensions page:
    - In Chrome, go to chrome://extensions/
    - In the new Microsoft Edge, go to edge://extensions/
1. Find Accessibility Insights for Web and select **Details**.
1. Turn on the **Allow access to file URLS** toggle.

## How do I run Accessibility Insights for Web in Incognito mode?

1. Open your browser's Extensions page:
    - In Chrome, go to chrome://extensions/
    - In the new Microsoft Edge, go to edge://extensions/
1. Find Accessibility Insights for Web and select **Details**.
1. Turn on the **Allow in Incognito** toggle.

## Which browsers are compatible with Accessibility Insights for Web?

Accessibility Insights for Web is currently compatible with:

- Chrome
- [Edge](https://www.microsoft.com/en-us/edge)

## What type of issues can be found with FastPass in Accessibility Insights for Web?

FastPass has two steps:

1. Automated checks: this checks are powered by [axe-core](https://www.npmjs.com/package/axe-core) and can detect **some** common accessibility problems, such as missing or invalid properties. However, most accessibility problems can be identified only through manual testing and Automated checks only provide **partial** coverage to WCAG success criteria.
1. Tab stops: an assisted manual test that helps you find **some** accessibility issues in keyboard navigation. In some cases, this test will also automatically detect potential keyboard access issues.

## Can automated checks in Accessibility Insights for Web detect issues in content that's currently hidden?

Some automated checks run only on visible content; they ignore content marked with `display: none` or `visibility: hidden`. To fully test content that's hidden by default – such as combo box options, dialog boxes, and menu options – you'll need to reveal the content before running automated checks:

1. Use your mouse or keyboard to reveal the hidden content.
1. Run the automated checks using the keyboard shortcut. The default shortcut is
    - Alt+Shift+1 in Windows
    - Option+Shift+1 in macOS

## How do I run automated checks on revealed content that disappears when focus moves away?

If revealed content – such as combo box options, dialog boxes, and menu options – disappears when focus moves away, you can run automated checks using the keyboard shortcut provided in **Ad hoc tools**:

1. Use your mouse or keyboard to reveal the hidden content.
1. Use the keyboard shortcut to run automated checks.
    - The default shortcut in Windows is Alt+Shift+1.
    - The default shortcut in macOS is Option+Shift+1.
1. View the results:
    1. To view results in the target page, click an error icon (red rectangle with white exclamation point).
    1. To view results in a list:
    - Open the Accessibility Insights for Web extension.
    - In the Launch pad, select **Ad hoc tools**.
    - Under **Automated checks**, select **List view and filtering**. Results will open in a new browser window.

## Are automated checks compatible with shadow DOM?

Automated checks are based on axe-core, which supports shadow DOM in _open_ mode but **not** in _closed_ mode.

Because closed mode prevents JavaScript from accessing an element's internal DOM, automated checks can't detect issues on components within a closed shadow DOM. Closed mode can also lead to false failure reports. For example, if an interactive component outside a shadow DOM is labelled by an element inside a closed shadow DOM, automated checks will report a missing label.

Shadow DOM in closed mode is sometimes implemented as an encapsulation measure. If you find that closed shadow DOM is interfering with automated checks, you might consider another approach to encapsulation.

## Can I aggregate test results from multiple pages?

Test results – automated or manual – can't be aggregated across multiple pages or page states.

## Is there a way to include automated tests in engineering pipeline?

If your project uses an end-to-end browser automation test framework, you can refer to samples available at [axe-pipelines-samples](https://github.com/microsoft/axe-pipelines-samples) to integrate automated accessibility tests in Azure pipelines. The samples use the same scanning engine, [axe-core](https://github.com/dequelabs/axe-core), that is used in Accessibility Insights for Web and demonstrate how automated accessibility tests are implemented in our own project pipeline.

## Why does Accessibility Insights for Web ask for additional permissions when it detects iframes?

The permissions the Accessibility Insights for Web extension requests have been modified. Previously, the extension had more powerful permissions that allowed it to scan all websites; to provide additional security and privacy options to its users, as well as streamline the review process for publishing updates to the extension, permissions are now only requested for the active page Accessibility Insights is invoked from.

Since the permissions are only for that active page, if you have cross-origin iframes (for example, you are scanning foo.com and inside foo.com you have an iframe that points to bar.com) Accessibility Insights for Web will not have permissions for the iframe's host and will not be able to scan it.

By providing these additional permissions, you are ensuring your whole page, including the iframe, is being scanned.

You can manage these permissions by visiting the extensions page for your browser and selecting "Details' for the Accessibility Insights for Web extension.

## What is the JSON schema used in assessment?

The JSON schema, as well as a full example output, is available in the [Accessibility Insights for Web release Assets](https://aka.ms/accessibility-insights-for-web/JsonSchema).

Each requirement in assessment can have 3 states: _pass, fail_ and _incomplete_:

- If at least one requirement failed, the S.C is marked as _fail_.
- If at least one requirement is incomplete and there are no failed requirements, the S.C is marked as _incomplete_.
- If all the requirements pass, the S.C is marked as _pass_.

## Where does Accessibility Insights for Web store scan data?

In general, Accessibility Insights for Web only stores complete scan data locally in the browser and does not upload results to any sort of external host.

If you chose to allow usage telemetry when you started the extension for the first time, it will upload some anonymous usage data. This includes information about how many violations of each type were found, but it does not include any information which would identify the user running the scan or the site the scan was run on - in particular, it does not include the URL or title of the site being scanned, nor the Path, Snippet or properties listed in the results in FastPass or Assessment. Telemetry is only sent if you opted in, and you can [disable telemetry](https://accessibilityinsights.io/docs/web/reference/telemetry/#disable-telemetry) at any time from the **Settings** panel.

## Why is the target page in the command bar of the Accessibility Insights for Web page a link?

This link is associated to the page you are testing (aka the target page); you can use this link to quickly return to it.

## Can I use Accessibility Insights for Web to test a browser extension?

Accessibility Insights for Web cannot test other browser extensions directly because web browsers do not allow extensions to run scripts on other extensions' pages.

However, it _is_ possible to run the "Automated checks" part of a FastPass or Assessment against a browser extension using an automated test. We recommend using [Playwright](https://playwright.dev/) for this. Some resources to learn more about this include:

- [Playwright's documentation on testing browser extensions](https://playwright.dev/docs/chrome-extensions)
- [Playwright's documentation on accessibility testing](https://playwright.dev/docs/accessibility-testing)
- [Example project in the axe-pipelines-sample GitHub repository demonstrating accessibility testing with Playwright](https://github.com/microsoft/axe-pipelines-samples/tree/main/typescript-playwright-sample)

## Do you have more information or examples about the rules used by Accessibility Insights for Web?

More information about the specific rules can be found at [Info and Examples for Accessibility Insights for Web](https://www.accessibilityinsights.io/info-examples/web/)

## Can I run Accessibility Insights for Web automatically in a Continuous Integration environment?

Most of the tests in Accessibility Insights for Web require some human analysis, so it isn't possible to completely automate a FastPass or an Assessment.

However, it _is_ possible to run the "Automated checks" part of a FastPass or Assessment in an automated test. You can find working examples of this in the [axe-pipelines-samples GitHub repository](https://github.com/microsoft/axe-pipelines-samples).


/docs/web/reference/faq


Thank you for using Accessibility Insights for Web.

## Get Started

Get started by reading our tutorials:

-   [FastPass](/docs/web/getstarted/fastpass/)
-   [Issue filing](/docs/web/getstarted/issuefiling/)
-   [Assessment](/docs/web/getstarted/assessment/)

## Keyboard Shortcuts

Increase your productivity with Accessibility Insights for Web's keyboard shortcuts.

-   [Keyboard shortcuts](/docs/web/reference/keyboard/)

## Privacy

With your consent, Accessibility Insights for Web collects anonymized usage data and crash report information. You may opt out at any time by disabling it:

-   [How do I disable telemetry?](/docs/web/reference/telemetry/)

## Contributing

Accessibility Insights for Web is open source on GitHub:

-   [Go to the GitHub repository for Web](https://github.com/microsoft/accessibility-insights-web)

## For additional help

| Help topic               | Instructions                                                                          |
| ------------------------ | ------------------------------------------------------------------------------------- |
| Ask a question           | [Ask a question in Stack Overflow](https://go.microsoft.com/fwlink/?linkid=2077941)   |
| Search known issues      | [Search GitHub issues](https://go.microsoft.com/fwlink/?linkid=2080529)               |
| Report an issue          | [Create a bug report in GitHub](https://go.microsoft.com/fwlink/?linkid=2080273)      |
| Search feature requests  | [Search GitHub feature requests](https://go.microsoft.com/fwlink/?linkid=2080524)     |
| Submit a feature request | [Create a feature request in GitHub](https://go.microsoft.com/fwlink/?linkid=2080273) |


/docs/web/reference/help


This page provides tips for people who use a keyboard to operate Accessibility Insights for Web.

## Keyboard shortcuts

Keyboard shortcuts allow you to run automated checks and turn on visual helpers without moving input focus away from the target page.

### Default keyboard shortcuts

Note: Chrome allows only six keyboard shortcuts per extension.

| Windows Key  | macOS Key    | Command                                      |
| ------------ | ------------ | -------------------------------------------- |
| Alt+Shift+K  | Option+Shift+K    | Activate the extension                       |
| Alt+Shift+1  | Option+Shift+1    | Show or hide Automated checks                |
| Alt+Shift+2  | Option+Shift+2    | Show or hide the visual helper for landmarks |
| Alt+Shift+3  | Option+Shift+3    | Show or hide the visual helper for headings  |
| (unassigned) | (unassigned) | Show or hide the visual helper for tab stops |
| (unassigned) | (unassigned) | Show or hide the visual helper for color     |

## Custom keyboard shortcuts

To customize keyboard shortcuts

1.  Open Accessibility Insights for Web:

    -   Select the extension icon.

    or

    -   Press Alt+Shift+K (Option+Shift+K for macOS) ([Customize this keyboard shortcut](/docs/web/reference/keyboard/)).

    or

    -   Use these keyboard commands:

        -   Windows or Linux:

            1. Press Shift+Alt+T or F10 to set focus on the browser's tool bar.
            1. Press the Left Arrow key to set focus on the Accessibility Insights for Web extension.
            1. Press the Space key to open the extension.

        -   macOS:

            1. Press ⌘+L to set focus on the browser's tool bar.
            1. Press the Tab key to set focus on the Accessibility Insights for Web extension.
            1. Press the Space key to open the extension.

    The Accessibility Insights for Web extension will open to the **Launch Pad**.

1.  In the menu <GlobalNavButtonIcon />, select **Keyboard shortcuts**.
1.  In the Shortcuts page, select the keyboard shortcut you want to customize and enter the new shortcut.

## Landmarks

Landmarks programmatically identify the major sections of a page. People who use screen readers and other assistive technologies use landmarks to find relevant content.

Accessibility Insights for Web provides the following landmarks.

### Launch pad

| Landmark      | Contents                                                                              |
| ------------- | ------------------------------------------------------------------------------------- |
| Banner        | **Manage settings** button, **Help menu** button, link to 3-minute video introduction |
| Main          | Links to **FastPass**, **Assessment**, **Ad hoc tools**                               |
| Complementary | Software version numbers, link to information about axe-core                          |

### FastPass and Assessment pages

| Landmark    | Contents                                                                   |
| ----------- | -------------------------------------------------------------------------- |
| Banner      | **Manage settings** button                                                 |
| Activity    | **Activity** listbox for choosing **FastPass** or **Assessment**           |
| Navigation  | Links to tests included in the selected activity                           |
| Command bar | **Target page** link, **Export result** button, **Start over** menu button |
| Main        | Content related to the selected test                                       |

### Ad hoc tools

| Landmark   | Contents                                                                                                                   |
| ---------- | -------------------------------------------------------------------------------------------------------------------------- |
| Banner     | **Manage settings** button, **Help menu** button                                                                           |
| Main       | Toggles for automated checks and visual helpers, link to detailed automated check results, links to visual helper guidance |
| Navigation | Link to the **Launch pad**                                                                                                 |


Keyboard Shortcuts for Accessibility Insights for Web

/docs/web/reference/keyboard


Check out our release notes in our [GitHub repository](https://aka.ms/accessibility-insights-web/release-notes)

_Release notes for Accessibility Insights for Web are titled "Accessibility Insights for Web: v#.#.#" and use the git tag "web@#.#.#"_


Release Notes for Accessibility Insights for Web

/docs/web/reference/releases


With your consent, Accessibility Insights for Web collects anonymized usage data and crash report data in order to improve our tools. For more details, [read about Accessibility Insights and telemetry](/docs/general/telemetry/);

## Disable telemetry

1.  Open Accessibility Insights for Web:

    -   Select the extension icon.

    or

    -   Press Alt+Shift+K (Option+Shift+K for macOS) ([Customize this keyboard shortcut](/docs/web/reference/keyboard/)).

    or

    -   Use these keyboard commands:

        -   Windows or Linux:

            1. Press Shift+Alt+T or F10 to set focus on the browser's tool bar.
            1. Press the Left Arrow key to set focus on the Accessibility Insights for Web extension.
            1. Press the Space key to open the extension.

        -   macOS:

            1. Press ⌘+L to set focus on the browser's tool bar.
            1. Press the Tab key to set focus on the Accessibility Insights for Web extension.
            1. Press the Space key to open the extension.

    The Accessibility Insights for Web extension will open to the **Launch Pad**.

1.  On the **Launch pad**, open **Manage Settings** <SettingsIcon /> and select **Settings** <SettingsIcon />.
1.  To disable telemetry, turn off the toggle under **Help improve Accessibility Insights for Web**. You can always enable it later by turning on the same toggle.


Telemetry in Accessibility Insights for Web

/docs/web/reference/telemetry


## What are automated checks?

Automated checks are a feature in Accessibility Insights for Windows that quickly checks an app for compliance with dozens of accessibility rules. It's easy to save the results to a file so you can share them with your team.

You can run automated checks on their own or as part of [FastPass](/docs/windows/getstarted/fastpass/), and you can [file issues](/docs/windows/getstarted/bugfiling/) directly from automated check failures.

## Running automated checks

You can run automated checks on an entire app or on a selected element, and you can use a timer to run automated checks after a delay.

However the checks are triggered, it is important to ensure that the application is in a "steady state" while being checked. Scan results may be inconclusive when checks are performed while the UI is in transition.

### Running automated checks on an entire app

Running automated checks on an entire app is the quickest way to identify issues.

1. In Accessibility Insights for Windows, go to the **Live Inspect** view.
1. Under **What to select**, choose **Entire app**.
1. Select an app, and then run automated checks on it: - Using a mouse: 1. Hover over the app. 1. Click the test icon that appears in the upper right corner of the app.
   or - Using a keyboard: 1. Press **Alt+Tab** on your keyboard to move focus to the app. 1. Press **Shift+F8**. (You can customize this [keyboard shortcut](/docs/windows/reference/keyboard/).)

![The app to be tested and Accessibility Insights for Windows are both open on the user's desktop. In the upper right corner of the app, the mouse pointer is hovering over the test icon.](/assets/windows/getstarted/automatedchecks/AutomatedChecks-01.jpg)

1. Review the automated check results:
    - A screenshot of the app appears, and all elements with failures are highlighted.
    - Detailed results are shown in Accessibility Insights for Windows:
        1. Failed rules are shown in a tree grid.
            - Where applicable, failed framework rules are shown in a separate tree grid.
        1. Each rule can be expanded to show its failure instances.
        1. Each failure instance has a link and a **File issue** button.

![A screenshot of the app shows all elements with failures highlighted. Accessibility Insights for Windows shows the accessibility check results. The first failed rule is expanded to show its two failure instances. The mouse pointer is hovering over the first failure instance's link.](/assets/windows/getstarted/automatedchecks/AutomatedChecks-02.jpg)

1. Select a failure instance link to see details:
    1. The selected element is highlighted in the screenshot.
    1. In Accessibility Insights for Windows,
        1. The selected element is displayed in the context of the UI Automation tree.
        1. Rules failed by the element are listed. 
        1. How-to-fix instructions are provided for each rule.

![The app screenshot shows a single highlighted element. Accessibility Insights for Windows shows the element in the UIA tree, lists the two rules failed by that element, and displays how-to-fix instructions for the first rule.](/assets/windows/getstarted/automatedchecks/AutomatedChecks-03.jpg)

### Running automated checks on a selected UI element

Running automated checks on a selected UI element scopes the results to that element and its children. Scoped results make it easier to identify a specific problem, for example when filing a bug.
You can run automated checks on an element by selecting the element either (1) directly in the app or (2) in the UI Automation tree in Accessibility Insights for Windows.

#### Selecting an element in the app

Selecting an element directly in the app the quickest way to run automated checks on it.

1. In Accessibility Insights for Windows, go to the **Live Inspect** view.
1. Under **What to select**, choose **Element**.
1. Select an element, and then run automated checks on it: - Using a mouse: 1. Hover over the element. 1. Click the test icon that appears in the upper right corner of the element.
   or - Using a keyboard (element must be focusable): 1. Move focus to the element. 1. Press **Shift+F8.**

#### Selecting an element in the UI Automation tree

Selecting an element in the UI Automation tree allows you to run automated checks on an element that isn't visible in the app. Also, this method allows you to use a keyboard to run automated checks on an element that isn't focusable.

1. In Accessibility Insights for Windows, go to the **Live Inspect** view.
1. Under **What to select**, choose **Entire app**.
1. Select an element, and then run automated checks on it. - Using a mouse: 1. Hover over the app until the test icon appears in its upper right corner. 1. In the UI Automation tree, click the element. 1. Click the **Test Element** button.
   or - Using a keyboard: 1. Press **Alt+Tab** to move focus to the app. 1. Press **Shift+F9** to bring Accessibility Insights for Windows to the foreground. (You can customize this [keyboard shortcut](/docs/windows/reference/keyboard/).) 1. In the UI Automation tree, use the arrow keys or the Live Inspect keyboard shortcuts to move focus to the element. 1. Press **Shift+F8**, or **Tab** to the **Test Element** button and then press **Enter**.

### Running automated checks with a timer

Accessibility Insights for Windows has a built-in timer that allows you to run automated checks after a delay. This feature can be handy when testing a UI component in a transient state, such as a combo box with its options expanded.

1. In the command bar, select **Timer**.
1. In the popup that opens, enter the number of seconds you'll need to get the UI into the desired state. (The default is 5.)
1. Start the timer by pressing the **Enter** key or clicking the popup.
1. In your target app, get the UI into the state you want to test, then wait. Automated checks will run when the timer reaches 0.

![The timer popup is open, and its delay is set to five seconds](/assets/windows/getstarted/automatedchecks/automated-checks-timer.png)

## Saving automated check results

Saving automated checks to a file allows you to share the results with your team. For example, you can attach the file to a bug, send it as an email attachment, or upload it into a file storage system.

1. Run automated checks using one of the methods described above.
1. Save the file:
    - Using a mouse, click **Save**, or
    - Using a keyboard, press **Ctrl+S**.
1. In the **Save As** dialog, choose a name for your file, and then select **Save**. The automated checks will be saved to a file with the .a11ytest file name extension.

![In the app screenshot, a single element is highlighted. In Accessibility Insights for Windows, the mouse pointer is hovering over the Save button.](/assets/windows/getstarted/automatedchecks/AutomatedChecks-04.jpg)

## Viewing automated check results

Anyone who has installed Accessibility Insights for Windows can view saved automated check results simply by opening the .a11ytest file. Accessibility Insights for Windows will open to the automated check results, and the app screenshot will open with failures highlighted.


Automated checks in Accessibility Insights for Windows

/docs/windows/getstarted/automatedchecks


Accessibility Insights for Windows makes it easy to file issues directly from automated check failures.

## How to file issues

### Sign into your issue filing account

Open Accessibility Insights for Windows.

Accessibility Insights will open to the **Live Inspect** view:

![Screenshot showing the "Live Inspect" view in Accessibility Insights for Windows](/assets/windows/getstarted/bugfiling/SignIn-01.png)

#### To sign in to Azure Boards

1. Go to **Sign In**.

    The **Settings** > **Connection** tab will open, with two options for filing issue: **Azure Boards** or **GitHub**.

    ![Screenshot showing the "Settings" view with the "Connection" tab open](/assets/windows/getstarted/bugfiling/SignIn-02.png)

2. Select **Azure Boards**.

    A text field and button will appear.

    ![Screenshot showing the "Enter desired Azure boards link" text field and "Connect Azure Boards account" button](/assets/windows/getstarted/bugfiling/SignIn-03.png)

3. Enter the URL for your Azure Boards account in the text field.

    The **Connect Azure Boards account** button will become enabled.

    ![Screenshot showing the "Connect Azure Boards account" button enabled](/assets/windows/getstarted/bugfiling/SignIn-04.png)

4. Select the **Connect Azure Boards account** button.

    A **Pick an account** dialog \_might \_open:

    ![Screenshot showing the "Pick an account" dialog](/assets/windows/getstarted/bugfiling/SignIn-05.png)

5. Select the account you want to use for filing issues.

    Under **Select your Azure Boards team**, a list of teams associated with the selected account will appear:

    ![Screenshot showing the list of teams associated with the selected account](/assets/windows/getstarted/bugfiling/SignIn-06.png)

6. Select your team.

    The **Save and close** button will become enabled:

    ![Screenshot showing the team selected](/assets/windows/getstarted/bugfiling/SignIn-07.png)

7. Select **Save and close**.

    You'll return to the **Live Inspect** view:

    ![Screenshot showing the "Live Inspect" view](/assets/windows/getstarted/bugfiling/SignIn-08.png)

#### To sign in to GitHub

1. Go to **Sign In**.

    The **Settings** > **Connection** tab will open, with two options for filing issues: **Azure Boards** or **GitHub**.

    ![Screenshot showing the "Settings" view with the "Connection" tab open](/assets/windows/getstarted/bugfiling/SignIn-09.png)

2. Select **GitHub**.

    A text field will appear.

    ![Screenshot showing the "Enter desired GitHub repo link" text field](/assets/windows/getstarted/bugfiling/SignIn-10.png)

3. Enter the URL for your GitHub account.

    The **Save and close** button will become enabled:

    ![Screenshot showing the "Save and close" button enabled](/assets/windows/getstarted/bugfiling/SignIn-11.png)

4. Select **Save and close**.

    You'll return to the **Live Inspect** view:

    ![Screenshot showing the "Live Inspect" view](/assets/windows/getstarted/bugfiling/SignIn-12.png)

### Run automated checks

1. Open the application you want to test (aka the target application).

    ![Screenshot showing the target application and Accessibility Insights for Windows](/assets/windows/getstarted/bugfiling/AutomatedChecks-1.png)

2. In the command bar, for **What to select**, choose **Entire app**.

    ![Screenshot showing "Entire app" selected](/assets/windows/getstarted/bugfiling/AutomatedChecks-2.png)

3. Start the automated checks:

    - Use a mouse:
        1. Hover your mouse over the target application window.
        2. Click the test beaker icon that appears in the upper right corner.

    or

    - Use these keyboard commands:
        1. Press Alt+Tab to switch to the target application window.
        2. Press Shift+F8.

    A screenshot of the target app will open in a new window directly over the app, and individual failure instances will be highlighted in the screenshot. Failed rules and failure instances will also appear in Accessibility Insights for Windows in the **Automated Checks** tree grid.

### File an issue

1. In the **Automated Checks** tree grid, expand a rule:

    - Use a mouse to click the rule.

    or

    - Use these keyboard commands:
        1. Press the Tab key to navigate to the **Automated checks** tree grid.
        2. Press the Up and Down arrow keys to navigate to a rule.
        3. Press the Right arrow key to expand the rule.

    When a rule is expanded, its failure instances are revealed:

    ![Screenshot showing the "Automated Checks" tree grid with one rule expanded](/assets/windows/getstarted/bugfiling/FileIssue-1.png)

2. Select the **File issue** link associated with the failure instance you wish to file.

    - Use a mouse to click the link.

    or

    - Use these keyboard commands:
        1. Press the Up and Down arrow keys to navigate to the failure instance.
        2. Press the Right arrow key to navigate to the **File issue** link.
        3. Press Enter to activate the link.

    If you signed into Azure Boards, a **New Issues** dialog will open, with information about the failure automatically populated:

    ![Screenshot showing a new issue in Azure Boards](/assets/windows/getstarted/bugfiling/FileIssue-2.png)

    If you signed into GitHub, the issue will open in a new browser window:

    ![Screenshot showing a new issue in GitHub](/assets/windows/getstarted/bugfiling/FileIssue-3.png)

3. Modify the information as desired (optional) and then save or submit the issue.

    When you save the issue, a screenshot and test file will be attached automatically.

## Troubleshooting

### How to install the WebView2 runtime

Filing issues to Azure Boards requires the WebView2 runtime. This is preinstalled on some Windows computers; Accessibility Insights for Windows will display a dialog if the WebView2 runtime is not installed.

1. To download and install the WebView2 runtime, navigate to the [Edge WebView2 download page](https://developer.microsoft.com/en-us/microsoft-edge/webview2/#download-section).

2. Download the "Evergreen Bootstrapper." Review the license terms.

![Screenshot highlighting the 'Download' button for the Evergreen Bootstrapper](/assets/windows/getstarted/bugfiling/InstallWebView2Runtime.png)

3. Run the Evergreen Bootstrapper.

4. Restart Accessibility Insights for Windows.

When the WebView2 runtime is installed, Accessibility Insights for Windows will be able to file issues to Azure Boards.


Issue filing in Accessibility Insights for Windows

/docs/windows/getstarted/bugfiling


## What is the Color Contrast Analyzer?

The Color Contrast Analyzer is a feature in Accessibility Insights for Windows that helps developers investigate contrast ratios.

**Contrast ratio** describes the relative brightness of foreground and background colors on a computer display. In general, higher contrast ratios make text and graphics easier to perceive and read. Black and white have the highest possible contrast ratio, 21:1. Identical colors have the lowest possible contrast ratio, 1:1. All other color combinations fall somewhere in between.

You can also watch a short video to [learn more about the Color Contrast Analyzer](https://www.youtube.com/watch?v=eEAYRBG4TOE).

## Why contrast ratio matters

Ensuring adequate contrast makes it easier for everyone to read text content, interpret graphical elements, identify UI components, and notice when those components change state. People with low vision often have difficulty reading text, identifying buttons that do not contrast with their background, or determining the state of UI components. The problems can be exacerbated if the person has a color vision deficiency that lowers the perceived contrast even further.

## Minimum contrast requirements

According to [WCAG 2.0 AA Success Criterion 1.4.3](https://www.w3.org/TR/2008/REC-WCAG20-20081211/#visual-audio-contrast-contrast):

-   Any text with a contrast of 4.5 or greater passes.
-   Large text (18pt or 14pt bold) with a contrast of 3.0 or greater passes.
-   Any text with a contrast below 3.0 fails.

According to [WCAG 2.1 AA Success Criterion 1.4.11](https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast.html):

-   Any UI component or meaningful graphical element with a contrast ratio of 3.0 or greater passes.
-   Any active (non-disabled) UI component or meaningful graphical element with a contrast ratio below 3.0 fails.

NOTE: Do not round up contrast ratios. 4.499 does not meet the threshold of 4.5 for regular text.

## How to test contrast ratio

### Identify elements to test

#### Text

Examine the app you want to test and ​identify any instances of meaningful text that might have a low background-to-foreground color contrast.

You do not need to test any text that is:

-   Part of an inactive (disabled) component
-   Purely decorative
-   Intended to be hidden from users
-   Part of a flag, logo or brand name

#### UI elements

Examine the app to identify any UI components (controls) that might have:

-   Low contrast against the background
-   Low contrast between different states (normal, focused, mouseover, selected)

You do not need to test:

-   Inactive UI components
-   UI components whose appearance is determined by the browser and not modified by the author

#### Graphical elements

Examine the app to identify any graphical objects (such as icons, charts, diagrams, and illustrations) that contain meaningful elements that might have low contrast against the background.

You do not need to test any graphical object where:

-   A particular presentation is [essential](https://www.w3.org/TR/WCAG21/#dfn-essential), and presenting it with sufficient contrast would undermine its meaning. For example, logos, photos real life scenes, illustrations using realistic colors, and screenshots are exempt from the contrast requirement.
-   The information conveyed graphically is also conveyed through visible text.
-   The graphical object is purely decorative.

### Launch the Color Contrast Analyzer

1. Open Accessibility Insights for Windows.
1. In the Navigation bar, select **Contrast** <ColorIcon />. (You can also press Ctrl+R).

### Auto detect contrast ratio

Auto detect makes it easy to test the foreground/background contrast ratio of text elements. Auto detect is not recommended for use on icons or other graphical elements.

1. Turn on the toggle for **Auto detect contrast ratio**.
1. To auto detect a text element's contrast ratio, use your mouse to hover over the text (or set keyboard focus on the element).
    - A tooltip will display the detected contrast ratio and confidence level.
    - Accessibility Insights for Windows will display the same information and also indicate whether the contrast ratio passes the relevant WCAG 2.1 AA success criteria. (You can bring Accessibility Insights for Windows to the foreground by pressing Shift+F9).
1. If Accessibility Insights for Windows is unable to detect the colors, or if the confidence level is **low** or **mid**, you must test the contrast ratio manually.

![Screenshot showing the target app and Accessibility Insights for Windows. The mouse is hovering over text that says, "Wildlife Manager." A tooltip says "Ratio: 21:1, Confidence: High." Accessibility Insights for Windows indicates that the ratio passes all of the WCAG success criteria for contrast.](/assets/windows/getstarted/colorcontrast/autodetect_text.png)

### Manually check contrast ratio

Because auto detect uses a heuristic intended specifically for text, the contrast ratio of UI components and graphical elements must be tested manually. Also, when auto detect doesn't work on text, the contrast ratio must be tested manually.

1. Turn off the toggle for **Auto detect contrast ratio**.

#### Text

1. Under Color 1, select the foreground color of the text (typically a horizontal or vertical portion of a character). To select a color, you can:

    - Select the first Eyedropper, and select the pixel that accurately represents the text's color. You can also use the arrow keys to focus on the pixel and press the Enter key.

    OR

    - Select the color using the Color Picker box.

    OR

    - If you know the text's hex color code, enter it in the **Hex Code** box.

1. Under Color 2, select the background color. If the background is not a single color, such as a gradient or image, select the pixel that is most similar to the foreground color.
1. Examine Accessibility Insights for Windows to determine whether the contrast ratio passes the relevant WCAG 2.1 AA success criteria.

![Screenshot showing the target app and Accessibility Insights for Windows. The mouse is hovering over the background of button that says "Close." Accessibility Insights for Windows indicates the color of the text foreground and background, and indicates that the contrast ratio fails the WCAG success criteria for regular or large text.](/assets/windows/getstarted/colorcontrast/select_color.png)

#### UI Components

1. Interact with each UI component in the target app to determine which of the following states it can adopt:
    1. Normal
    1. Focused
    1. Mouseover
    1. Selected
1. Identify any visual (non-text) indicators that communicate:
    1. The boundary of the component's clickable area
    1. The component's current state
1. Test the component's foreground/background contrast in each supported state: 1. Under Color 1, select the color of the visual indicator. 1. Under Color 2, select the adjacent (background) color.
   To select colors using the Eyedropper, it might be necessary to take a screenshot of the UI component in its desired state (for example, using the Snip & Sketch tool) and then select colors from the screenshot. Alternatively, you might be able to get the hex color from the code.
1. Examine Accessibility Insights for Windows to determine whether the contrast ratio passes the WCAG 2.1 AA Success Criterion for graphical objects and UI components (at least 3:1).
   ![Screenshot showing the target app, a screenshot in the Snip & Sketch tool, and Accessibility Insights for Windows. The mouse is hovering over the blue border of a selected list item in the screenshot. Accessibility Insights for Windows indicates that the contrast ratio between Color 1 (the border color of the unselected list item) and Color 2 (the border color of the selected list item) fails the WCAG Success Criterion for graphical objects and UI components.](/assets/windows/getstarted/colorcontrast/select_color.png)

#### Graphical Objects

1. For each graphic, identify the parts that are necessary for the graphic to be understood.
1. Test the foreground/background contrast of each necessary state. 1. Under Color 1, select the foreground color. 1. Under Color 2, select the adjacent (background) color.  
   If the foreground or background includes multiple colors or a gradient, select colors with the least apparent contrast.
1. Examine Accessibility Insights for Windows to determine whether the contrast ratio passes the WCAG 2.1 AA Success Criterion for graphical objects and UI components (at least 3:1).
   ![Screenshot showing the target app and Accessibility Insights for Windows. The mouse is hovering over a segment of a pie chart. Accessibility Insights for Windows indicates that the contrast ratio between the color of the segment (medium blue) and its background (white) passes the WCAG success criterion for graphical objects and UI components.](/assets/windows/getstarted/colorcontrast/graphic.png)


Color Contrast Analyzer in Accessibility Insights for Windows

/docs/windows/getstarted/colorcontrast


## What is event monitoring?

Event monitoring is a feature in Accessibility Insights for Windows that enables you to easily verify that a UI element in a Windows app:

-   Responds as expected to user input.
-   Generates the expected events.

## How to use Inspect

### Get ready to inspect

1. Open Accessibility Insights for Windows.
1. If you are not already in **Live Inspect** mode, select **Inspect** in the main navigation bar.
1. In the command bar, for **What to select**, choose **Element**.
1. Open the application you want to test (aka the target application).

### Select an element

1. Select the UI element you wish to inspect:

    - Use your mouse to hover over the element.

    or

    - Use your keyboard to set focus on the element, then press **Shift+F9** to switch back to Accessibility Insights.

    In the target application, the selected element will be visually highlighted. In Accessibility Insights for Windows, in the **Details** tab, the element's control type and accessible name will be prominently displayed, followed by its **Properties** and supported **Patterns** (if any).

    ![Target application with focused element visually highlighted element next to Accessibility Insights for Windows displaying the element's UI Automation properties](/assets/windows/getstarted/eventmonitoring/1_Select_an_element.png)

1. Pause selection (optional):
    1. When you have selected the element you wish to inspect, select **Pause UIA Tree** <PauseIcon /> in the command bar.
    1. When you are ready to inspect a different element, select **Resume UIA Tree** <PlayIcon /> in the command bar.

### Verify that the element responds correctly to user input

1. In the **Details** tab, in the **Patterns** section, select **Actions** for the first pattern.

    A dialog will open, with a tab for each action supported by the pattern. In this example, the pattern (SelectionPattern) has only one action (GetSelection), so the dialog has only one tab.

    ![SelectionPattern Actions dialog opened.](/assets/windows/getstarted/eventmonitoring/2_Pattern_actions_start.png)

1. In each tab:

    1. Make sure that the selected element is in an appropriate state to perform the action.
    1. Where needed, provide an appropriate value for the action.
    1. Run the action.
    1. Verify that the action succeeded.

    The dialog will update if the action succeeds. In this example, the GetSelection action returned the selected UI Element and a list of its properties.

    ![SelectionPattern Actions dialog after running the GetSelection action.](/assets/windows/getstarted/eventmonitoring/3_Pattern_actions_end.png)

1. Repeat steps 1 and 2 for each pattern listed in the **Patterns** section.

### Verify that the element generates expected events

1. Learn about the required events for the element's [control type](https://docs.microsoft.com/en-us/windows/desktop/winauto/uiauto-supportinguiautocontroltypes).

1. Find the selected element in the **UIA Tree**, and select **More options** <MoreIcon /> > **Listen to Events**.

    A new **Events** view will open in Accessibility Insights for Windows. The view includes an **Events** table and two tabs, **Details** and **Configuration.** By default, the **Events** table is empty, and the **Configuration** tab is open.

    ![Events view with the Events table empty and the Configuration tab open.](/assets/windows/getstarted/eventmonitoring/4_Event_listener_start.png)

1. Select the events you wish to record.

    By default, expected events based on the control type are recorded.

    If the type of event you wish to monitor is not listed, you can record any supported UI Automation event type by expanding "My Events" in the tree view and opening the "Edit My Events..." node contained within.

1. Start recording.

    The **Details** tab will open automatically, and new events will appear in the **Events** table.

    ![Events view with the Details tab open.](/assets/windows/getstarted/eventmonitoring/5_Event_listener_recording.png)

1. Interact with the element using your mouse or keyboard.

1. Verify that the element generates the required events.

    Events generated by the selected element will be added to the **Events** table. In this example, selecting an item in the **Species** list (in the target application) generated a series of focus change events.

    ![New events recorded in the Events table.](/assets/windows/getstarted/eventmonitoring/6_Event_listener_events.png)


Event monitoring in Accessibility Insights for Windows

/docs/windows/getstarted/eventmonitoring


## What is FastPass?

FastPass is a lightweight, _two-step_ process that helps developers identify common, high-impact accessibility issues in less than five minutes.

1. **Automated checks** - the tool automatically checks for compliance with dozens of accessibility rules.
1. **Manual test for tab stops** - the tool provides clear instructions and a visual helper that makes it easy to identify critical accessibility issues related to keyboard access, such as missing tab stops, keyboard traps, and incorrect tab order.

We recommend developers run a FastPass before every check-in of UI code.

Note: Completing a FastPass requires you to use standard keyboard commands and to visually identify interactive interface elements.

## How to complete a FastPass

### Get ready to test

1. Open Accessibility Insights for Windows.
1. In the command bar, for **What to select**, choose **Entire app**.
1. Open the application you want to test (aka the target application).

![Screenshot showing the target application and Accessibility Insights for Windows](/assets/windows/getstarted/fastpass/1_Launch.png)

### Complete the automated checks

1. Run the automated checks:

    - Hover your mouse over the target application window, then click the test beaker icon that appears in the upper right corner.

    or

    - Press Alt+Tab to switch to the target application window, then press Shift+F8.

    A screenshot of the app will open in a new window directly over the app, and individual failure instances will be highlighted in the screenshot. Failed rules and failure instances will also appear in Accessibility Insights for Windows in a tree grid. Where applicable, Framework specific failed rules and failure instances will appear in a separate tree grid.

    ![Screenshot showing failures highlighted in the target application and listed in Accessibility Insights for Windows](/assets/windows/getstarted/fastpass/2_Automated_checks_start.png)

1. Review failure details:

    - Click a failure icon (white exclamation on red background) in the application screenshot.

    or

    - Use these keyboard commands:

        1. Press the Tab key to navigate to the **Automated checks** tree grid.
        1. Press the Up and Down arrow keys to navigate to a rule.
        1. Press the Right arrow key to expand the rule.
        1. Press the Right arrow key to navigate to the **Element path** link.
        1. Press the Space or Enter key to activate the link.

    A new view will open in Accessibility Insights for Windows. The view includes the **UIA Tree** and a set of tabs: **Details** and **How to fix**.

    The **How to fix** tab is selected by default. It's divided into two regions:

    - **Test results** contains a selectable list of rules failed by the element selected in the **UIA Tree**. Framework specific list of rules will be displayed in a separate table below the test results.
    - **Fix the following** contains instructions for fixing the failure selected under **Test results**.

    ![Screenshot showing failure details in Accessibility Insights for Windows](/assets/windows/getstarted/fastpass/3_Automated_checks_end.png)

1. Review failure details for a different instance:

    - To select an element in the **UIA Tree**:

        - Click a failing element in the **UIA Tree**. (You might need to expand a node by clicking its arrow icon.)

        or

        - Use these keyboard commands:

            1. Press the Tab key to navigate to the **UIA Tree**.
            1. Press the Up and Down arrow keys to select a failing element. (If needed, press the Right arrow key to expand a node.)

    or

    - To return to the Automated Checks tree grid:

        - Click **Tests** in the breadcrumb or in the main navigation bar.

        or

        - Press Ctrl+T.

1. If you're a developer, we recommend fixing the automated check failures before proceeding to the next part of the FastPass.

### Complete the manual test for tab stops

1. Be sure you are in the **Tests** view.
1. Go to the **Tab stops** test:

    - Click **Tab Stops** in the navigation pane.

    or

    - Use these keyboard commands:

        1. Press Tab until you reach the **Automated checks** tab.
        1. Use the Down arrow key to select the **Tab stops** tab.

    ![Screenshot showing the Tab Stops test in Accessibility Insights for Windows](/assets/windows/getstarted/fastpass/4_Tab_stops_test.png)

1. Make sure your target app is in the state you want to test.
1. Start recording tab stops:

    - Click the **Record tab stops** toggle.

    or

    - Press Shift+F7.

    Input focus will move automatically to the target application.

    ![Screenshot showing the Tab Stops test with tab stop recording enabled](/assets/windows/getstarted/fastpass/5_Tab_stops_start.png)

1. Use standard keyboard commands to move input focus through all the interactive elements in the page.

    - Use Tab and Shift+Tab to navigate between controls.
    - Use the arrow keys to navigate between the focusable elements within a composite control, such as the items in a menu.

    In the target app, numbered circles will appear on elements that receive input focus. A list of those elements will also appear in a grid in Accessibility Insights for Windows.

    ![Screenshot showing tab stops highlighted and numbered in the target application](/assets/windows/getstarted/fastpass/6_Tab_stops_end.png)

1. As you navigate to each element, look for these accessibility problems:

    - An interactive element can't be reached using the Tab or arrow keys.
    - An interactive element "traps" input focus and prevents navigating away.
    - An interactive element doesn't give a visible indication when it has input focus.
    - The focus order is inconsistent with the logical order that's communicated visually.
    - Input focus moves unexpectedly without the user initiating it.

1. Stop recording when you have navigated to every element within your test scope.

When you've completed the tab stops test, your FastPass is complete.


FastPass in Accessibility Insights for Windows

/docs/windows/getstarted/fastpass


## What is Inspect?

Inspect is a feature in Accessibility Insights for Windows that enables you to easily verify that a UI element in a Windows app:

-   Has the expected UI Automation properties.
-   Supports the expected control patterns.

## How to use Inspect

### Get ready to inspect

1. Open Accessibility Insights for Windows.
1. If you are not already in **Live Inspect** mode, select **Inspect** in the main navigation bar.
1. In the command bar, for **What to select**, choose **Element**.
1. Open the application you want to test (aka the target application).

### Select an element

1. Select the UI element you wish to inspect:

    - Use your mouse to hover over the element.
      or
    - Use your keyboard to move the input focus to the element.

    In the target application, the selected element will be visually highlighted. In Accessibility Insights for Windows, in the **Details** tab, the element's control type and accessible name will be prominently displayed, followed by its **Properties** and supported **Patterns** (if any).

    ![target application and Accessibility Insights for Windows](/assets/windows/getstarted/inspect/1_Select_an_element.png)

1. Pause selection (optional):

    1. When you have selected the element you wish to inspect, select **Pause UIA Tree** <PauseIcon /> in the command bar.
    1. When you are ready to inspect a different element, select **Resume UIA Tree** <PlayIcon /> in the command bar.

### Verify that the element has the expected UI Automation properties

1. Learn about the expected properties for the element's [control type](https://docs.microsoft.com/en-us/windows/desktop/winauto/uiauto-supportinguiautocontroltypes).

1. In the **Details** tab, in the **Properties** section, examine the element's UI Automation properties.

    - Use the default view to see basic UIA properties.

    or

    - Choose **UIA Tree Properties Settings** > **Include all properties that have values**.

    or

    - Choose **UIA Tree Properties Settings** > **Configure properties to always show**.

1. Verify that the element has the expected properties.

### Verify that the element supports the expected control patterns

1. Learn about the allowed and required control patterns for the element's [control type](https://docs.microsoft.com/en-us/windows/desktop/winauto/uiauto-supportinguiautocontroltypes).

1. In the **Details** tab, in the **Patterns** section, examine the patterns supported by the element.

1. Verify that the element supports all of the required patterns.

### Customize your Inspect experience (optional)

1. Choose **Change settings** in the main navigation bar.

    A **Settings** view will open to the **Application** tab.

    ![Settings view with the Application tab open.](/assets/windows/getstarted/inspect/7_Settings.png)

1. Under **Selection type**, choose which selection mode(s) to enable.

1. Under **Other options**, choose a highlighter mode.


Inspect in Accessibility Insights for Windows

/docs/windows/getstarted/inspect


The following steps will prepare you to use Accessibility Insights for Windows on a Windows computer.

## Installing Accessibility Insights for Windows

### Using the setup wizard

1. Go to [Accessibility Insights Downloads](/downloads).
1. Under **For Windows**, select **Download for Windows.**
1. When the installer file finishes downloading, open it.
1. Follow the instructions in the setup wizard.

### Using a command prompt

This method is an alternative to using the setup wizard.

1. Go to [Accessibility Insights Downloads](/downloads).
1. Under **For Windows**, select **Download for Windows.**
1. When the installer file finishes downloading, open a command prompt as an administrator.
1. Change to the directory containing the file. For example, enter the following command:

    ```
    cd %HOMEPATH%\Downloads
    ```

1. Run the installer in quiet mode. For example, enter the following command:

    ```
    msiexec.exe /i AccessibilityInsights.msi /quiet
    ```

    An application icon will appear on the desktop when installation is complete.

## Testing your target application

By default, Accessibility Insights for Windows can't access applications running with administrative privileges. In this situation, you have three options:

- If possible, run your target application without administrative privileges.
- Run Accessibility Insights for Windows as administrator. (Must be done each session.)
- Enable UIAccess for Accessibility Insights for Windows. (Will impact all future sessions of Accessibility Insights for Windows.) To do this:
    1. Open a command prompt as an administrator.
    1. Navigate to the directory where the AccessibilityInsights.exe file is stored. For example, enter the following command:

        ```
        cd C:\Program Files (x86)\AccessibilityInsights\1.1
        ```

    1. Run UIAccess.cmd Enable from the directory where Accessibility Insights for Windows is installed. For example, enter the following command:

        ```
        UIAccess.cmd Enable
        ```

## Uninstalling Accessibility Insights for Windows

1. Go to **Apps & features**, select Accessibility Insights for Windows, and then select **Uninstall**.

## Troubleshooting

### GitHub authentication error while using the setup wizard

**Problem**

Accessibility Insights for Windows was unable to install the application on your device due to a GitHub Authentication issue when downloading.

**Solution**

#### Using the setup wizard

1. Open a new private browser window.
1. Go to [Accessibility Insights Downloads](https://accessibilityinsights.io/downloads).
1. Under **For Windows**, select **Download for Windows.**
1. When the installer file finishes downloading, open it.
1. Follow the instructions in the setup wizard.

#### Using a command prompt

This method is an alternative to using the setup wizard.

1. Open a new private browser window.
1. Go to [Accessibility Insights Downloads](https://accessibilityinsights.io/downloads).
1. Under **For Windows**, select **Download for Windows.**
1. When the installer file finishes downloading, open a command prompt as an administrator.
1. Change to the directory containing the file. For example, enter the following command:

    ```
    cd %HOMEPATH%\Downloads
    ```

1. Run the installer in quiet mode. For example, enter the following command:

    ```
    msiexec.exe /i AccessibilityInsights.msi /quiet
    ```

    An application icon will appear on the desktop when installation is complete.


Setting up Accessibility Insights for Windows

/docs/windows/getstarted/setup


[Download for Windows](/downloads/)

## What's Accessibility Insights for Windows?

Accessibility Insights for Windows helps developers find and fix accessibility issues in Windows apps. The tool supports three primary scenarios:

-   _Live Inspect_ allows developers to verify that an element in an app has the right UI Automation properties simply by hovering over the element or setting keyboard focus on it.
    -   Elements are displayed in the UIA Tree.
    -   Choose your view of the properties: properties relevant to the control type, all properties that have values, or custom.
-   _FastPass_ is a lightweight, two-step process that helps developers identify common, high-impact accessibility issues in less than five minutes.
    -   Automated checks - the tool automatically checks for compliance with more than 60 accessibility requirements.
    -   Tab stops test - the tool provides clear instructions and a visual helper that makes it easy to identify critical accessibility issues related to keyboard access, such as missing tab stops, keyboard traps, and incorrect tab order.
-   Troubleshooting allows you to diagnose and fix specific accessibility issues:
    -   View the patterns supported by a control and invoke the associated UI methods to see whether an element responds correctly to user input.
    -   Record application events to verify that your app is generating the expected events.
    -   Use the built-in contrast checker to identify contrast issues and select colors that provide sufficient contrast.

## Get Started

Get started by watching a video:

-   [Overview](https://www.youtube.com/watch?v=BIu9ONdMGGg)

Or read a tutorial:

-   [FastPass](/docs/windows/getstarted/fastpass/)
-   [Inspect](/docs/windows/getstarted/inspect/)

## Keyboard Shortcuts

Increase your productivity with Accessibility Insights for Windows's keyboard shortcuts.

-   [Keyboard shortcuts](/docs/windows/reference/keyboard/)

## Privacy

With your consent, Accessibility Insights for Windows collects anonymized usage data and crash report information. You may opt out at any time by disabling it:

-   [How do I disable telemetry?](/docs/windows/reference/telemetry/)

## Contributing

Accessibility Insights for Windows is open source on GitHub:

-   [Go to the GitHub repository for Windows](https://github.com/microsoft/accessibility-insights-windows)

## Additional Help

For additional help such as reporting issues and asking questions:

-   [Help for Accessibility Insights for Windows](/docs/windows/reference/help/)


Solve accessibility issues before they reach your customers.

For Web

For Windows

Ship accessible products to your customers

Agile

Up-to-date

Community

Visual Helper

Dedicated Tests

Learn more about Accessibility Insights

FastPass

Commitment to quality

Help the community

Get Started