WAI-ARIA: aria-hidden (State)

Description

Indicates whether the element is exposed to an accessibility API. See related aria-disabled.

User agents determine an element’s hidden status based on whether it is rendered, and the rendering is usually controlled by CSS. For example, an element whose display property is set to none is not rendered. An element is considered hidden if it, or any of its ancestors are not rendered or have their aria-hidden attribute value set to true.

Authors MAY, with caution, use aria-hidden to hide visibly rendered content from assistive technologies only if the act of hiding this content is intended to improve the experience for users of assistive technologies by removing redundant or extraneous content. Authors using aria-hidden to hide visible content from screen readers MUST ensure that identical or equivalent meaning and functionality is exposed to assistive technologies.

Note: Authors are advised to use extreme caution and consider a wide range of disabilities when hiding visibly rendered content from assistive technologies. For example, a sighted, dexterity-impaired individual may use voice-controlled assistive technologies to access a visual interface. If an author hides visible link text “Go to checkout” and exposes similar, yet non-identical link text “Check out now” to the accessibility API, the user may be unable to access the interface they perceive using voice control. Similar problems may also arise for screen reader users. For example, a sighted telephone support technician may attempt to have the blind screen reader user click the “Go to checkout” link, which they may be unable to find using a type-ahead item search (“Go to…”).

Note: At the time of this writing, aria-hidden=”false” is known to work inconsistently in browsers. As future implementations improve, use caution and test thoroughly before relying on this approach.

Note: It is recommended that authors key visibility of elements off this attribute, rather than change visibility and separately update this property. CSS 2 introduced a way to select on attribute values ([css3-selectors]).

Browser Compatibility

aria-hidden Example

HTML Example 1

<p aria-hidden="true">This content is hidden.</p>
<p aria-hidden="false">This content is not hidden.</p>

HTML Example 2

<div class="text">
  <label id="tp1-label" for="first">First Name:</label> <input type="text" id="first" name="first" size="20" aria-labelledby="tp1-label" aria-describedby="tp1" aria-required="false">
  <div id="tp1" class="tooltip" role="tooltip" aria-hidden="true">
    Your first name is optional
  </div>
</div>

CSS

.tab-panel[aria-hidden="true"] { display: none; } .tab-panel[aria-hidden=”false“] { display: block; }

Characteristics

Used in Roles

• All elements of the base markup

Value

• true/false/undefined:
  Value representing true, false, or not applicable. For example, an element with aria-expanded set to false is not currently expanded; an element with aria-expanded set to undefined is not expandable. The default value for this value type is undefined unless otherwise specified.
• false
  • The element is exposed to the accessibility API as if it was rendered.
• true
  • The element is hidden from the accessibility API.
• undefined (default)
  • The element’s hidden state is determined by the user agent based on whether it is rendered.

Semantic HTML

Use the HTML “hidden” attribute.

<p hidden>This paragraph should be hidden.</p>

Reference

• WAI-ARIA 1.2 Specification
  Refer to the notes from the WAI-ARIA 1.2 specification for more information on aria-hidden.
• MDN Web Docs
  The browser compatibility for each of the ARIA attributes is taken from the MDN Web Docs. Please refer to the original source if browser compatibility is updated for aria-hidden.