Disclosure
A disclosure widget lets users toggle the visibility of additional content, with a trigger button that communicates its expanded or collapsed state to assistive technology.
Demo
Activate the disclosure trigger button below using a mouse click or by pressing Enter or Space while it has keyboard focus. Watch how the hidden content region appears and disappears. Pay attention to how the button label or icon changes to reflect the current state, and verify that a screen reader would announce the change.
A disclosure widget is a user interface component that allows users to show or hide a section of content. The trigger button communicates its current state (expanded or collapsed) to assistive technologies using the aria-expanded attribute.
Use a disclosure when you have supplementary content that does not need to be visible at all times. Common use cases include FAQ sections, additional details, and progressive disclosure of form fields. Disclosures help reduce cognitive load by letting users reveal content on demand.
While both patterns toggle content visibility, an accordion typically enforces that only one section is open at a time. Disclosure widgets are independent of each other, meaning multiple sections can be open simultaneously without any mutual constraint.
What to Observe
- The trigger button's
aria-expandedattribute switches betweentrueandfalseas the content is shown or hidden. - The controlled content region is associated with the trigger via
aria-controls, giving screen reader users a programmatic link between the two. - The button receives a clear visible focus indicator when navigated to with the keyboard.
- Content is hidden using a method that removes it from the accessibility tree (not just visually), so screen readers do not read collapsed content.
- The button text or accompanying icon conveys the current state in a way that makes sense without seeing the content area.
Anatomy
[Anatomy image placeholder — will be added when assets are available]
- Trigger button — A
<button>element that controls the disclosure; carriesaria-expandedto reflect the current state andaria-controlsto point to the content panel. - State indicator — A visual cue (such as a chevron icon) that rotates or changes to signal whether the content is expanded or collapsed.
- Content panel — The collapsible region linked to the trigger; hidden or shown in a way that keeps it in sync with the accessibility tree.
- Panel content — Any text, links, or other elements inside the panel that become available only when the disclosure is open.
Accessibility Behavior
- The trigger must be a native
<button>element (or haverole="button"with full keyboard support) so it is keyboard-operable by default. aria-expandedmust be set on the trigger and updated every time the panel is toggled — never left static.- The content panel must be hidden in a way that removes it from the accessibility tree when collapsed, such as using the
hiddenattribute ordisplay: none. - The relationship between the trigger and the panel must be programmatically expressed using
aria-controls. - Activating the trigger with Enter or Space must toggle the panel, matching the behavior of a native button.
Common Mistakes
- Using a
<div>or<span>as the trigger instead of a<button>, which breaks keyboard access entirely. - Hiding the panel with
visibility: hiddenoropacity: 0instead of removing it from the DOM flow, so screen readers still read the collapsed content. - Forgetting to update
aria-expandedwhen the state changes, leaving screen reader users with stale information. - Using icon-only triggers (like a bare chevron) without any text or
aria-label, making the button's purpose undiscoverable to screen reader users. - Omitting
aria-controls, breaking the programmatic association between the trigger and the panel.
Why This Matters
Disclosure widgets are the foundation for FAQs, accordion sections, "read more" patterns, and sidebar navigation groups. When built incorrectly — especially when a non-button element is used as the trigger or aria-expanded is missing — screen reader users cannot tell whether content is available, and keyboard-only users may be completely unable to open the section. A pattern as fundamental as show/hide should be one of the most reliable in any component library.
Accessibility Validation
This component is validated against internal accessibility criteria aligned with WCAG standards, using our internally developed system, Resonance Specs.
To learn more, please contact us.
Code