ARIA Disclosure Widgets

A disclosure widget consists of a trigger (<button>) that toggles the hidden state of its associated content.

Check out the demo page for markup patterns and variations.

How does it work?

Use either a <disclosure-inline> (for display: inline-block) or <disclosure-block> (for display: block) custom element wrapping element.

Whichever wrapping element used, it MUST contain a <disclosure-content> element. This element represents the content you want to show/hide.

The minimal expected markup pattern for this script to work is as follows:

<disclosure-block> <!-- or disclosure-inline -->
  <disclosure-content>
    ...
  </disclosure-content>
</disclosure-block>

The trigger

A <button> element to toggle the <disclosure-content> will be auto generated by the script. Use the data-trigger attribute on the <disclosure-inline> or <disclosure-block> element to provide this element a visible label and its accessible name. If the data-trigger attribute is not specified, the generated <button> will render a fallback label of "More info".

<disclosure-inline data-trigger="Unique name goes here">
  <disclosure-content>
    ...
  </disclosure-content>
</disclosure-inline>

If you want more control over the placement of the generated <button> element, and thus also include additional structured and semantic content to your disclosure widget, then you can use the data-insert-trigger to specify the element where the <button> will be generated. The content of the chosen element will become the content of the <button> element.

<disclosure-block>
  <h5 data-insert-trigger>
    <img src=... alt>
    <span>Visible text label</span>
  </h5>
  <disclosure-content>
    ...
  </disclosure-content>
</disclosure-block>

Per the above markup, the <button> will be insterted into the <h5> element. The resulting markup will render as follows:

<h5 ...>
  <button aria-expanded=...>
    <img ...>
    <span>Visible text label</span>
  </button>
</h5>

Alternatively, the <button> can be injected into another element as an inline trigger. This will render the <button> with only the down arrow/chevron icon, and use an aria-label="More info" to provide it an accessible name. Consider the following markup:

<disclosure-inline>
  <h5>
    My topic here
    <span data-insert-trigger="inline"></span>
  </h5>
  ...
</disclosure-inline>

The resulting markup will render as follows:

<h5>
  My topic here
  <span ...>
    <button ... aria-expanded="..." aria-label="More info"></button>
  </span>
</h5>

Other options

The following attributes are available to use on the wrapping <disclosure-block> or <disclosure-inline> element:

data-open – Use to open a disclosure widget by default.
data-disabled - Will add a disabled attribute to the generated <button>.
data-left-align - Will render the down arrow / chevron on the left of the <button>, rather than the default right position.
data-popup - The <disclosure-content> will be displayed as a faux "popup". If keyboard focus is detected outside of the widget, the popup content will auto-collapse and the <button> will return to the aria-expanded=false state. When identified as a "popup", the content panel will be provided a tabindex=-1 and a role=note. Comments describing why are provided in the JavaScript file.

Keyboard controls

The <button> element allows for default Space and Enter keys to toggle the expanded and collapsed state of the associated content.

If the disclosure widget is rendered as a popup, then the Esc key can be used to collapse the content if focus is on the <button> element, or within the expanded disclosure widget content container. Pressing Esc will return focus to the <button> element of the disclosure widget.

License & such

This script was written by Scott O'Hara.

It has an MIT license.

Do with it what you will :)

scottaohara / aria_disclosure_widget