Using the aria-hidden attribute
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.
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.
aria-hidden="false" will not re-expose the element to assistive technology if any of its parents specify
WAI-ARIA Authoring Practices 1.1 notes that
aria-hidden="false" currently behaves inconsistently across browsers.
On the surface, the
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="none"will remove the semantic meaning of an element while still exposing it to assistive technology.
- (default) The element is exposed to the accessibility API.
- The element is not exposed to the accessibility API.
- (default) The user agent determines if the element is exposed to or hidden from the accessibility API.
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>
aria-hidden="true" should not be added when:
- the HTML
hiddenattribute is present
- the element or the element's ancestor is hidden with
- The element or the element's ancestor is hidden with
In all three scenarios, the attribute is unnecessary to add because the element has already been removed from the accessibility tree.