Ensures aria-hidden Elements are Not Focusable Nor Contain Focusable Elements

Casandra Visser

Author

Yotam Flohr

Researcher

Ritvik Shrivastava

Expert

July 29, 2024

Disabilities affected: Blind Low vision Hearing Mobility

Standards: WCAG 2.2 Level A

Written and researched for humans by humans

Casandra Visser

Author

Yotam Flohr

Researcher

Ritvik Shrivastava

Expertly reviewed by

Comments: 0

Accessibility algorithms will check that aria-hidden elements do not contain focusable elements.

The name and role of all user interface components must have the ability to be programmatically determined and notification of changes to these items must be available to user agents, including assistive technologies.

Why It Matters

When the aria-hidden=”true” attribute is used on an element, it removes the element as well as all of its child nodes from the accessibility API. This means assistive technologies cannot access them.

The only time this attribute should be used is if hiding content will improve the user experience.

If aria-hidden needs to be used to hide visible content from screen readers, an identical or equivalent meaning and functionality must be accessible to assistive technologies.

Please note that using aria-hidden=”false” on content that is a descendent of an element that is hidden will not expose that content to the accessibility API.

When adding aria-hidden=”true” to an element, developers must ensure that assistive technologies will ignore the element. This is usually the case when hiding decorative parts of a web page.

Fixing the Issue

The issue can be corrected by ensuring the value inside each attribute is spelled correctly and corresponds to a valid value. It’s also important to use appropriate ARIA roles, states, and properties.

Good Code Examples

Content not focusable by default.

Code example

<p aria-hidden="true">Some text</p> Copy

Content hidden through CSS.

Code example

<div aria-hidden="true">
    <a href="/" style="display:none">Link</a>
</div>

Copy

Content made unfocusable through tabindex.

Code example

<div aria-hidden="true">
	<button tabindex="-1">Some button</button>
</div>

Copy

Content made unfocusable through disabled.

Code example

<input disabled aria-hidden="true" /> Copy

aria-hidden can’t be reset once set to true on an ancestor.

Code example

<div aria-hidden="true">
    <div aria-hidden="false">
        <button tabindex="-1">Some button</button>
    </div>
</div>

Copy

Bad Code Examples

Focusable off screen link.

Code example

<div aria-hidden="true">
	<a href="/" style="position:absolute; top:-999em">Link</a>
</div>

Copy

Focusable form field, incorrectly disabled.

Code example

<div aria-hidden="true">
	<input aria-disabled="true" />
</div>

Copy

aria-hidden can’t be reset once set to true on an ancestor.

Code example

<div aria-hidden="true">
    <div aria-hidden="false">
        <button>Some button</button>
    </div>
</div>

Copy

Focusable content through tabindex.

Code example

<p tabindex="0" aria-hidden="true">Some text</p> Copy

Focusable summary element.

Code example

<details aria-hidden="true">
    <summary>Some button</summary>
    <p>Some details</p>
</details>

Copy

Test Cases

For further examples, visit W3C’s GitHub’s ATC Rules library.