Accessibility Examples: ARIA Disclosure (Show/Hide)

Disclosure widgets are collapsible regions in a page that are controlled (i.e. expanded or collapsed) by a button or a link. Disclosure widgets are relatively simply to implement accessibly, requiring very little JavaScript.

The following ARIA attributes are needed to implement a disclosure widget:

• button - Designates the disclosure toggle as a button. Not needed if the trigger is an html <button> element.
• aria-expanded (state) - True if the region is expanded; false if the region is collapsed.
• aria-controls (optional property) - Establishes a programmatic relationship between the region toggle and the region. Not needed if the disclosure region immediately follows the region toggle.
• region (optional role) - Optionally defines the collapsible region as a distinct region.
• aria-labelledby (optional state) - Optionally labels the region. Necessary if role=region is used on the toggled region.

The markup for the disclosure is as follows for the collapsed state:

<button id="hs-toggle" class="btn" aria-controls="hs-rgn" aria-expanded="false">Toggle Region 1</button>
<div id="hs-rgn" role="region" aria-labelledy="hs-toggle"> … </div>

When expanded, the value of the aria-expanded state should be updated via JavaScript to true:

<button id="hs-toggle" class="btn" aria-controls="hs-rgn" aria-expanded="true">Toggle Region 1</button>
<div id="hs-rgn" role="region" aria-labelledy="hs-toggle"> … </div>

When using a link as the toggle for a disclosure widget, it is necessary to add role=button to the link. This is because the link is being used as a button, not for navigation. The href attribute can either be empty ('#') or javascrip:void(0); may be used. The code would look something like this:

<a id="hs-toggle" href="javascript:void(0);" aria-controls="hs-rgn" aria-expanded="true" role="button">Toggle Region 2</a>
<div id="hs-rgn" role="region" aria-labelledy="hs-toggle"> … <div>

When using a link as the trigger it is also necessary to attach a keydown handler to allow the region to be toggled via the space bar (enter key support is implemented by default).

Incorrect Implementation

This example demonstrates incorrectly placing the aria-expanded attribute on the toggled region, instead of on the toggle button. This error will result in the user not being notified of the state of the disclosure region. ARIA states will only update the user if placed on the item that currently has focus.