Using the aria-hidden attribute

Draft
This page is not complete.

This technique demonstrates how to use the aria-hidden attribute. The aria-hidden attribute can either expose or hide non-interactive content from the accessibility API.

Description

Adding aria-hidden="true" to an element removes that element and all of its children from the accessibility tree. This can improve the experience for assistive technology users by hiding:

  • purely decorative content, such as icons or images
  • duplicated content, such as repeated text
  • offscreen or collapsed content, such as menus

According to the fourth rule of ARIA, aria-hidden="true" should not be used on a focusable element. Additionally, since this attribute is inherited by an element's children, it should not be added onto the parent or ancestor of a focusable element.

Using aria-hidden="false" will not re-expose the element to assistive technology if any of its parents specify aria-hidden="true".

WAI-ARIA Authoring Practices 1.1 notes that aria-hidden="false" currently behaves inconsistently across browsers.

Deciding between aria-hidden="true", role="presentation", and role="none"

On the surface, the aria-hidden="true", role="presentation", and role="none" attributes seem similar because they:

  • hide content from assistive technology
  • cannot be used on a focusable element
  • cannot be used on the parent of an interactive element

Despite these similarities, the intent behind each attribute is different.

  • aria-hidden="true" will remove the entire element from the accessibility API.
  • role="presentation" and role="none" will remove the semantic meaning of an element while still exposing it to assistive technology.

Values

false
(default) The element is exposed to the accessibility API.
true
The element is not exposed to the accessibility API.
undefined
(default) The user agent determines if the element is exposed to or hidden from the accessibility API.

Examples

In the example below, the paragraph is not exposed to the accessibility API (e.g. would not be read aloud by a screen reader).

<p aria-hidden="true">
  Some things are better left unsaid.
</p>

Children elements can be omitted from accessibility APIs:

<p>
  This is not hidden <span aria-hidden="true">but this is</span>!
</p>

Accessibility concerns

Best practices

aria-hidden="true" should not be added when:

  • the HTML hidden attribute is present
  • the element or the element's ancestor is hidden with display: none
  • The element or the element's ancestor is hidden with visibility: hidden

In all three scenarios, the attribute is unnecessary to add because the element has already been removed from the accessibility tree.

Specifications

See also