
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>


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>


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)


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>


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>


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>


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>


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>


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>


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>


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>


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>


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>


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>


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>


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>


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>


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>


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>


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>


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>


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>


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>


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>


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>


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>


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>


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>


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>


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>


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>


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>


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>


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>


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>


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>


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>


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>


image-alt


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>


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>


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>


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>


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>


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>


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>


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>


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>


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>


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>


meta-viewport


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>


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>


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)


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>


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>


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>


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>


server-side-image-map


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>


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>


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>


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>


valid-lang

Info and Examples for Accessibility Insights for Web


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>



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>



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>


duplicate-id-aria


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>


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


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 and Examples for Accessibility Insights for Web

Needs Review rules

Automated Checks rules