aria-hidden-focus

Description

The aria-hidden-focus rule ensures that elements marked with aria-hidden="true" do not contain any focusable or interactive descendants. The aria-hidden attribute removes an element and all its children from the accessibility tree, hiding them from assistive technologies. However, if those children are still focusable (for example, a <button> or a link), keyboard users can still tab to them — reaching an element that has no accessible name, role, or state exposed to assistive technologies. This creates a confusing and broken keyboard experience.

This rule meets WCAG requirements by:

1. Ensuring Consistent Role and Value Exposure (WCAG 4.1.2 Name, Role, Value): It prevents situations where focusable elements exist in the DOM but are invisible to assistive technologies, leaving keyboard users stranded on unmarked, undescribed controls.
2. Maintaining a Logical Focus Order (WCAG 2.4.3 Focus Order): It ensures that the sequential focus order does not include elements that have been deliberately hidden from the accessibility tree, preserving a coherent and meaningful navigation experience.

To comply with this rule, do not place focusable elements inside an aria-hidden="true" container.

Examples

In the following incorrect example, a button is nested inside an aria-hidden container. Keyboard users can tab to it, but screen readers will not announce it because it is hidden from the accessibility tree.

The following corrected example moves the button outside the aria-hidden container so it is visible to both keyboard users and assistive technologies.

How to fix?

To fix violations of the aria-hidden-focus rule, follow these steps:

• Move all interactive and focusable elements (buttons, links, inputs) outside of any container that has aria-hidden="true".

• If the container must remain hidden from assistive technologies and the interactive children are not needed, remove the children from the DOM entirely rather than just hiding them from the accessibility tree.

• If you need to keep the element in the DOM but must prevent keyboard focus, add tabindex="-1" to each focusable child in addition to the aria-hidden="true" on the container — but only if the element truly serves no purpose for any user.

Reference

• WCAG Success Criterion 4.1.2: Name, Role, Value

• WCAG Success Criterion 2.4.3: Focus Order