Prepared Docs

Prepared Docs

⌘K

    Loading navigation…

User

  1. Components
  2. Accordion
  3. Usage

Accordion

Usage

Overview

Accordion stacks related content into titled sections that operators open as needed. It lowers initial visual noise while keeping depth one click away—ideal for dispatch-center settings, incident inspector panels, and QA review frames where the operator occasionally needs many subtopics without scrolling through one long page. The mental model is "a tall column of labeled drawers," each standing alone as a coherent unit. Choose it when progressive disclosure matches scanning order; choose something else when users need to compare content across sections at the same time.

When to use

For dense settings or configuration with optional detail

CAD field displays, protocol editors, supervisor preferences—panels with five or more related chunks where only a subset is relevant to a given task benefit from disclosure. Users expand only the sections they need.

For narrow panes where vertical space is precious

Chat inspector rails, mobile-constrained layouts, and side drawers where a long scrolling form would bury everything benefit from stacked, collapsible sections.

For progressive disclosure during onboarding or help

Learning flows and reference material often match accordion's pacing: read a heading, decide whether to go deeper, continue. It supports the way operators actually learn a product mid-shift.

When not to use

For a single expandable block

Use Collapsible. An accordion with one item is just a collapsible with extra chrome.

For primary navigation across routes

Use Sidebar or TabNav. Accordion implies "related sub-content," not "different destinations."

For content that must stay visible for compliance review

Do not hide required fields inside collapsed sections. If every field must be seen before submit, use a flat form and anchor links, not disclosure.

For comparing content side by side

Use Tabs when the mental model is "peer sections you switch between," not "a tall list you scan top to bottom."

Variants

VariantPurposeEmphasis
defaultPrimary page contentFull background and border treatment
ghostSidebars, inspector chromeLower weight; pairs with surrounding surfaces
lineText-heavy or compressed layoutsTight vertical rhythm; no container chrome
type="single"One section open at a timeFocus discipline; matches most dispatch settings
type="multiple"Multiple sections open at onceCross-section comparison (policy diffs, side-by-side detail)

Composition

Each AccordionItem pairs a trigger with the content it discloses. The trigger is a button with a chevron that rotates to indicate state; the content region is the disclosed body. Keep triggers short and unambiguous—operators should be able to predict the content before expanding.

Content guidelines

  • Trigger text is a short noun or verb phrase, sentence case, localized with formatMessage. Titles describe the content, not the mechanic.
  • Put summary information in the trigger row (counts, status dots) so operators can scan without opening every section.
  • Never bury validation errors only inside a collapsed item. Either auto-open the offending section or surface summary indicators at the group level.
  • For empty sections, expand by default or collapse with an empty-state hint in the trigger—do not let an empty accordion mimic a filled one.

Behavior and states

  • Default open sections. Open sections that contain blocking tasks, first-time critical info, or an active error state.
  • Controlled vs. uncontrolled. Use controlled state when syncing with URL params, analytics, or remote validation. Use uncontrolled for self-contained panels.
  • Animation. Expand/collapse animations respect prefers-reduced-motion; honor the system setting rather than overriding it.
  • Disabled items. Explain the reason. A disabled trigger with no rationale is worse than no trigger at all.

Best practices

Do

  • Group logically. Each item should stand alone as a coherent unit of the parent's task.
  • Keep the count of items in single digits. Above ~10, operators stop scanning and start scrolling—consider splitting into tabs or subpages.
  • Pair the trigger with status indicators when state matters (error counts, unsaved changes, live session indicators).
  • Prefer type="single" by default. One section open at a time reduces cognitive load; switch to multiple only when comparison is the task.

Don't

  • Nest accordions more than one level deep. Flatten the information architecture or move deeper content to a subpage.
  • Use accordion chrome for unrelated marketing FAQs mixed into transactional flows—contexts should feel consistent.
  • Hide critical information (required fields, active alerts) inside collapsed items without surfaced indicators.
  • Auto-close a section the user just opened because another toggled open. That is a framework bug wearing a product decision.

Related Components

  • Tabs for peer sections users switch between instead of scan top to bottom.
  • Tab nav for link-based navigation across routes.
  • Sidebar for primary navigation in the app shell.
  • Drawer for context-preserving side panels rather than inline disclosure.

Previous

Accessibility / Long Content

Next

Accordion / API and Development

On this page

Overview
When to use
For dense settings or configuration with optional detail
For narrow panes where vertical space is precious
For progressive disclosure during onboarding or help
When not to use
For a single expandable block
For primary navigation across routes
For content that must stay visible for compliance review
For comparing content side by side
Variants
Composition
Content guidelines
Behavior and states
Best practices
Related Components