Skip to content
flyingsalmon

Accordion

A vertical stack of headings that each reveal a panel, for secondary content that helps some readers and should not crowd the rest.

Add a flight or a hotel and the planner builds each day around it, keeping the check-in and the departure where they are.

Installation

npx shadcn@latest add @flyingsalmon/accordion

Usage

import {
  Accordion,
  AccordionContent,
  AccordionItem,
  AccordionTrigger,
} from '@/components/ui/accordion'

export function AccordionUsage() {
  return (
    <Accordion>
      <AccordionItem value="itinerary">
        <AccordionTrigger>Itinerary</AccordionTrigger>
        <AccordionContent>
          Four days in Kyoto, then two in Osaka.
        </AccordionContent>
      </AccordionItem>
      <AccordionItem value="budget">
        <AccordionTrigger>Budget</AccordionTrigger>
        <AccordionContent>Flights and lodging are paid.</AccordionContent>
      </AccordionItem>
    </Accordion>
  )
}

Examples

One at a time

type="single" closes the open panel when another opens. Pressing the open item closes it, so the stack can rest with nothing open. Pass collapsible={false} when one panel must always be visible.

Four days in Kyoto, then two in Osaka, with the train booked between them.

Disabled item

Disabling dims the trigger and drops it from the arrow path, but an open panel stays readable, because disabling never hides content.

Issued on 3 May and already emailed to Brian Nguyen. It cannot be edited.

Rich triggers

A trigger takes any phrasing content: a status badge with a summary line, a title long enough to wrap, a count. The chevron stays on the first line, where the eye starts reading.

Seats 14A and 14B, checked bags included. The airline releases boarding passes a day before departure.

Forms in panels

A panel is a plain container for fields, choices, and actions. Send a note with nothing typed to see a field error, then with text to see the result appear under the actions row, inside the panel that produced it.

Controlled

Pair value with onValueChange and the open set becomes the app's state: expand all, collapse all, or open the item a search matched.

1 of 3 open

Fushimi Inari at dawn, then Nishiki Market for lunch.

Guidelines

When to use

  • For secondary information that helps some readers: an FAQ, the detail behind a booking, a packing list.
  • When the page should stay clean without the extra content and the panels can stay in document flow.
  • For a single collapsible region: a one-item accordion covers it, so there is no separate collapsible.

When not to use

  • Use Tabs to switch between co-equal views of the same subject. Tabs swap the content in place, an accordion reveals more of it.
  • Use Card for content every reader needs. Hiding it behind a click costs them a step.
  • Use Dialog for content that stops the page or needs an answer.

Do and don’t

  • Do
    Keep a result inside the panel that produced it.The traveller is looking at that panel, so the result below the actions row is where it will be seen, and it stays until they have.
  • Do
    Write each trigger as the item’s name, with a muted line that sums up what the panel holds.A closed accordion is the table of contents. When every trigger reads on its own, the closed stack is a recap the reader scans without opening anything.
  • Do
    Start every item closed unless the reader needs it on arrival.The accordion holds what helps some readers, so the page opens on what every reader needs.
  • Don’t
    Give a trigger any job but opening its panel.A row that opens and also acts makes every press a guess. The controls live in the panel, where the reader has chosen to look.
  • Don’t
    Give the stack a border of its own or a fill to open panels. To box it, put it in a card’s content.The accordion is a flush divider list, and an open panel is the page continued, not a new surface.

Accessibility

KeyDescription
TabShift+TabMoves between triggers. Focus never enters a closed panel.
ArrowDownArrowUpMoves to the next or previous trigger, skipping disabled ones.
HomeEndJumps to the first or last trigger.
EnterSpaceOpens or closes the focused item.

Every trigger sits inside a heading, so the document outline survives, and carries aria-expanded. Its panel is a region labelled by the trigger. The trigger renders an h3; pass asChild with your own heading to place the row at another level. A button, a link, or a field inside a trigger would nest one control inside another, so keep controls in the panel.

The trigger draws no focus ring. Keyboard focus paints what hover paints: the item’s divider and the row’s chevron step to the indicator colour. A borderless row has no border to replace, and an inset ring would read as a box around a row that has no box.

API

Accordion

The root. The accordion is vertical only, so orientation and dir are not exposed.

PropTypeDefaultDescription
typeAccordionTypeAccordionType.MultipleMultiple lets every item open on its own. Single keeps one open at a time.
collapsiblebooleantrueWith type single, whether pressing the open item closes it. Multiple items always collapse.
valuestring[] | string–The open items when controlled: an array under multiple, one string under single, where an empty string means nothing is open.
defaultValuestring[] | string–The items open on first render.
onValueChange(value: string[] | string) => void–Called when the open set changes.
disabledbooleanfalseDisables every trigger.

AccordionItem

PropTypeDefaultDescription
valuestringRequiredIdentifies the item in the root’s value.
disabledbooleanfalseDims the trigger and drops it from the arrow path. An open panel stays readable.

AccordionTrigger

The trigger is itself a button, and everything you pass lands inside its heading. Keep it to text, badges, and spans: never a button, a link, or a field.

PropTypeDefaultDescription
asChildbooleanfalsePass your own heading element as the only child to set the row’s level in the outline.

AccordionContent takes the props of the element it renders. className lands on the padded body inside the panel. The stack draws no box of its own; to box it, wrap it in a card’s content.

  • Tabs

    Switches between co-equal views instead of revealing more.
  • Card

    A box to wrap an accordion in.
  • Badge

    A status inside a trigger.
  • Accessibility

    Why the focus indicator is not always a ring.