Data Display/Accordion

Accordion

A vertically stacked set of interactive headings.

Themed

When to Use

Use Accordion when you need to:

  • Organize lengthy content into collapsible sections (FAQs, settings, documentation)
  • Reduce visual clutter by hiding secondary information until requested
  • Present a list of related items where only one or a few need attention at a time
  • Build step-by-step wizards or progressive disclosure flows
  • Create navigable content sections within a limited vertical space

When Not to Use

  • Single show/hide toggle - use Collapsible instead
  • Switching between distinct views - use Tabs for parallel content panels
  • Short content that fits on screen - display it directly without hiding
  • Primary navigation structure - use Navigation Menu or Sidebar

Default

A single-type accordion with collapsible behavior. Click a trigger to expand its content; the previously open item closes automatically.

Our flagship product combines cutting-edge technology with sleek design. Built with premium materials, it offers unparalleled performance and reliability.

Key features include advanced processing capabilities, and an intuitive user interface designed for both beginners and experts.

FAQ Style

Simple question and answer format commonly used for FAQ sections. No item is open by default.

Multiple

With type="multiple", any number of items can be expanded simultaneously. Useful for comparison views.

Multiple items can be open at the same time when using type="multiple".

Great for comparison views where users need to see multiple sections simultaneously.

Disabled Items

Individual accordion items can be disabled to prevent user interaction. Disabled triggers show reduced opacity.

Custom Styling

Accordion items can be styled with custom layouts, numbered indicators, and rounded borders for a card-like appearance.

UX & Design Guidelines

Content Organization

Keep accordion trigger labels concise and scannable. Use sentence case for triggers. Order items by importance or frequency of access - the most commonly needed section should appear first. Avoid nesting accordions inside other accordions; flatten the hierarchy or use a different pattern for deeply nested content.

Single vs Multiple

Use type="single" when sections are contextually independent and users typically need only one at a time (FAQs, settings panels). Use type="multiple" when users may need to compare or reference content across sections simultaneously (product specs, feature comparisons). Always add collapsible with single type so users can close all items.

Responsive Behavior

Accordions work well on mobile where vertical space is at a premium. Content hidden inside accordion panels does not affect page scroll length until expanded. On wider screens, consider whether a two-column layout or Tabs would better serve the content. Ensure touch targets for triggers meet the minimum 44x44px recommendation.

Animation & Transitions

The accordion uses CSS animate-accordion-down and animate-accordion-up for smooth height transitions. The chevron icon rotates 180 degrees when expanded. These animations respect prefers-reduced-motion for users who have requested minimal animations.

Accessibility

Keyboard Navigation

  • Tab — Move focus to the next accordion trigger
  • Shift + Tab — Move focus to the previous accordion trigger
  • Enter or Space — Toggle the focused accordion item open/closed
  • Arrow Down — Move focus to the next trigger
  • Arrow Up — Move focus to the previous trigger
  • Home — Move focus to the first trigger
  • End — Move focus to the last trigger

Screen Reader Support

  • Each trigger has role="button" inside an implicit heading element
  • Triggers announce aria-expanded="true" or "false" to convey state
  • Content regions are linked to their triggers via aria-controls and aria-labelledby
  • Disabled items announce as unavailable; screen readers skip them during arrow-key navigation

Focus Management

Visible focus ring with 3px width using focus-visible:ring-[3px]. Focus remains on the trigger after toggling, allowing rapid keyboard navigation without losing context. The focus ring color uses ring-ring/50 for consistent theming.

WAI-ARIA Pattern

Built on Radix UI, the accordion fully implements the WAI-ARIA Accordion Pattern. Triggers are wrapped in <h3> heading elements by default. Content panels use role="region" with associated labelling.

ARIA Attributes

{/* Single collapsible accordion */}
<Accordion type="single" collapsible>
  <AccordionItem value="faq-1">
    <AccordionTrigger>Is it accessible?</AccordionTrigger>
    <AccordionContent>
      Yes. Built on Radix UI with full WAI-ARIA support.
    </AccordionContent>
  </AccordionItem>
</Accordion>

{/* Controlled accordion with onValueChange */}
<Accordion
  type="single"
  collapsible
  value={openItem}
  onValueChange={setOpenItem}
>
  <AccordionItem value="section-1">
    <AccordionTrigger>Section Title</AccordionTrigger>
    <AccordionContent>Section content here.</AccordionContent>
  </AccordionItem>
</Accordion>

{/* Accordion with disabled item */}
<Accordion type="single" collapsible>
  <AccordionItem value="active" disabled={!hasPermission}>
    <AccordionTrigger>Restricted Section</AccordionTrigger>
    <AccordionContent>
      Only visible when permissions are granted.
    </AccordionContent>
  </AccordionItem>
</Accordion>

Related Components

Collapsible

A single interactive component that expands/collapses a panel. Use when you need just one toggle.

Tabs

Layered sections of content displayed one at a time. Better for parallel content selection.

Card

Container with header, content, and footer. Combine with accordion for expandable card layouts.

Separator

Visually separates content sections. Accordion items use bottom borders as built-in separators.

API Reference

The Accordion component is composed of four parts: Accordion (root), AccordionItem, AccordionTrigger, and AccordionContent.

Accordion

The root container that manages expanded state and keyboard navigation.

PropTypeDefaultDescription
type"single" | "multiple"—Determines whether one or multiple items can be open at the same time.
valuestring | string[]—The controlled value of the item(s) to expand.
defaultValuestring | string[]—The default value of the item(s) to expand (uncontrolled).
onValueChange(value: string | string[]) => void—Event handler called when the expanded state changes.
collapsiblebooleanfalseWhen type="single", allows closing content by clicking the trigger again.
disabledbooleanfalseWhen true, prevents user interaction with all items.
classNamestring—Additional CSS classes to apply to the root element.

AccordionItem

Wraps each collapsible section with its trigger and content.

PropTypeDefaultDescription
valuestring—A unique value for the item (required).
disabledbooleanfalseWhen true, prevents user interaction with this item.
classNamestring—Additional CSS classes to apply to the item.

AccordionTrigger

The clickable header that toggles the associated content panel.

PropTypeDefaultDescription
asChildbooleanfalseMerge props onto the immediate child element instead of the trigger.
classNamestring—Additional CSS classes to apply to the trigger.

AccordionContent

The collapsible content panel with animated height transitions.

PropTypeDefaultDescription
forceMountbooleanfalseForce mounting when more control is needed (useful for animations).
classNamestring—Additional CSS classes to apply to the content container.