composite pattern · Progressive disclosure
Accordion
A vertically stacked set of interactive headings that reveal or hide their associated content panels.
Decisive boundary
An accordion may allow one or multiple panels open. Do not assume mutual exclusivity.
Definition and intent
What is a Accordion UI pattern?
Use the behavior, not the silhouette
A vertically stacked set of interactive headings that reveal or hide their associated content panels. The term is used here as a composite pattern made from multiple controls or regions that must work together. That distinction prevents a visual resemblance from silently deciding focus, keyboard, modality, or dismissal behavior.
Organize several titled content sections with user-controlled visibility. A good implementation preserves that job while making the trigger, open state, close path, and responsive behavior observable to users.
Know when the label is wrong
The fastest way to identify a pattern is often to reject the nearest alternative. For Accordion, the boundary is: An accordion may allow one or multiple panels open. Do not assume mutual exclusivity.
Do not implement it as Disclosure for a single relation and Collapsible when only generic visibility behavior is known. If those requirements describe the real task better, use the related pattern page or the full Progressive disclosure comparison before writing code.
Decision process
Decide before choosing a component
Record these requirements in plain language. A library component name is not a substitute for the contract.
Confirm the user job
Organize several titled content sections with user-controlled visibility.
Define opening and closing
A button contained in each section heading. The same heading button collapses its panel when the design allows it.
Specify access behavior
Header buttons remain in normal document focus order. Enter or Space toggles; Tab reaches controls; optional arrow navigation must be consistent.
Reject the near miss
Disclosure for a single relation and Collapsible when only generic visibility behavior is known.
Behavior contract
What must survive the build
- trigger
- A button contained in each section heading.
- dismissal
- The same heading button collapses its panel when the design allows it.
- modality
- Non-modal inline structure.
- focus
- Header buttons remain in normal document focus order.
- keyboard
- Enter or Space toggles; Tab reaches controls; optional arrow navigation must be consistent.
- interactive
- Panels may contain normal document content and controls.
- persistence
- Expanded state may persist during the page session if useful.
- placement
- Inline vertical content structure.
- mobile
- Useful for reducing scroll, but labels must remain informative when collapsed.
Failure modes
Common wrong builds
- Using non-button headings as controls.
- Forcing one panel open without documenting it.
- Creating too many landmark regions.
Observable checks
Verify the result
- Each header is a button inside an appropriate heading.
- Expanded state is exposed.
- Each button controls the correct panel.
- Enter and Space toggle.
- Tab order follows the document.
- Open-state policy is explicit.
Coding-agent handoff
Implementation brief template
Pattern: Accordion Purpose: Organize several titled content sections with user-controlled visibility. Trigger: A button contained in each section heading. Dismissal behavior: The same heading button collapses its panel when the design allows it. Modality: Non-modal inline structure. Focus behavior: Header buttons remain in normal document focus order. Keyboard behavior: Enter or Space toggles; Tab reaches controls; optional arrow navigation must be consistent. Interactive content: Panels may contain normal document content and controls. Placement: Inline vertical content structure. Mobile behavior: Useful for reducing scroll, but labels must remain informative when collapsed. Do not implement as: Disclosure for a single relation and Collapsible when only generic visibility behavior is known. Acceptance checks: - Each header is a button inside an appropriate heading. - Expanded state is exposed. - Each button controls the correct panel. - Enter and Space toggle. - Tab order follows the document. - Open-state policy is explicit.
Claim-level references
Sources, not a confidence score
Frequently asked questions
Accordion UI pattern questions
Direct answers based on the reviewed behavior contract above.
What is a Accordion in web UI?
A vertically stacked set of interactive headings that reveal or hide their associated content panels. In this reference set it is a composite pattern made from multiple controls or regions that must work together.
When should I use a Accordion?
Organize several titled content sections with user-controlled visibility. The decisive boundary to confirm is this: An accordion may allow one or multiple panels open. Do not assume mutual exclusivity.
What keyboard and focus behavior does a Accordion need?
Enter or Space toggles; Tab reaches controls; optional arrow navigation must be consistent. Header buttons remain in normal document focus order. These statements describe the reviewed expectation, but the final implementation still needs testing in the component library and browser you ship.
How should a Accordion behave on mobile?
Useful for reducing scroll, but labels must remain informative when collapsed. Its modality is a separate requirement: Non-modal inline structure.
How do I verify a Accordion implementation?
Start with observable checks: Each header is a button inside an appropriate heading. Expanded state is exposed. Each button controls the correct panel. Then verify the remaining checks and compare the result with the linked source guidance.