Keep information everyone needs visible. Use disclosure when users can identify and open only the sections relevant to them.
Problem
A page feels too long.
Use disclosure or accordions when
- Related reference sections serve different needs, and their headings help users choose what to open.
- One or two short, secondary explanations suit simple disclosure; a larger set of related sections may suit an accordion.
Avoid disclosure or accordions when
- Hiding instructions everyone needs or errors people must fix.
- Using an accordion to avoid editing repetitive content or improving headings.
Example
Subscription details
You can cancel at any time. Access ends after the current billing period; export your projects before then.
Which export formats are available?
Projects can be exported as JSON or CSV in this example.
Where can I find past receipts?
Receipts are listed under Billing in this example.
These panels use native HTML disclosure controls.
Implementation
- Write descriptive labels that make sense while collapsed. First check whether editing the content, adding headings or using anchor links removes the need to hide it.
- For simple disclosure, use native details with summary as its first child. Keep its built-in behavior; do not add role="button" or duplicate expanded state to summary.
- For a custom accordion, follow the APG pattern: put each button in an appropriately leveled heading, set aria-controls to its panel ID, and keep aria-expanded synchronized with visibility. Hide collapsed panels and their controls.
- Support Enter and Space to toggle. Keep focus on the trigger after toggling, and keep every header button and control in an expanded panel in the normal Tab sequence.
- Allow multiple panels to stay open when users need to compare them. A shared name on details enforces one open panel, so use it only when that restriction helps the task. Avoid unnecessary nesting.
- Panel region landmarks are optional. Use them selectively for substantial sections, with aria-labelledby pointing to the controlling button; avoid turning every small panel into a landmark.
Tradeoffs
Accordions shorten the visible page but increase interaction cost and hide content from scanning. A longer, well-structured page is often easier to read.
Verification
Can users predict which section they need, toggle it by keyboard, hear its expanded state, and reach its contents without being moved unexpectedly?