Accordion
Headings that each open the section under them: questions and answers, settings, filters.
Installation
npx @yolkui/cli add accordionUsage
Each AccordionItem holds an AccordionTrigger, the heading, and an AccordionContent, its section. One section is open at a time; defaultValue (an array of item values) opens some to start with, and value with onValueChange controls them from the page. A line separates the sections and there is no box, so it sits in a page, a card or a popover as text does.
- The heading is a real heading (h3 by default). Set headingLevel on AccordionTrigger to fit the page's outline, as headingLevel={4} inside a Card with an h3 title.
- Links in a section are underlined; paragraphs are 16 apart.
- For a single section that shows and hides on its own, a button and a panel are enough; for views of the same content side by side, use Tabs.
Several open at once
With multiple, opening one section leaves the others as they are: settings, filters, anything a person compares.
Email for mentions and replies, a weekly summary on Mondays.
Push notifications are off on this device.
Disabled
disabled on an AccordionItem keeps its section closed. The heading fades and stays focusable, so wrap it in a Tooltip that says why; disabled on the Accordion turns off every section.
In a box
For a busy page, give the Accordion a border, a radius and some padding: className="rounded-lg border border-border px-4".
In a Card
In a Card the accordion needs nothing extra: the card's edge is the only box.
Frequently asked
Found by the browser's search
hiddenUntilFound keeps closed sections in the page, hidden until found: the browser's find (Ctrl+F or Cmd+F) searches them and opens the one with the match, and search engines read them. Browsers that do not support it keep them closed until opened.
Right to left
In a right-to-left page the heading starts on the right and the chevron sits on the left, on their own.
API
Our additions on top of Base UI's Accordion (value, defaultValue, onValueChange, multiple, disabled, hiddenUntilFound, keepMounted and the rest work as in Base UI).
| Prop | On | Values | Default |
|---|---|---|---|
headingLevel | AccordionTrigger | 2 · 3 · 4 · 5 · 6 | 3 |
className | AccordionContent | goes on the inner box that holds the text and its padding | — |
Accessibility
Each heading is a button inside a heading, which says whether its section is open; the section is a region named by its heading. Screen readers list the headings with the rest of the page's.
- Every heading is its own Tab stop; Enter and Space open and close it. Arrow keys do not move between headings, as the WAI-ARIA accordion pattern now says.
- A disabled heading stays focusable and is announced as dimmed, so a Tooltip can explain it.
- Each open section is a region, a landmark screen readers list. When many sections can be open at once (multiple, more than about six), give AccordionContent role="group" so the landmark list stays short.
- The section slides open in 150ms, and at once when the system asks for reduced motion.
- Colour is never the only sign: the chevron turns with the section, and the screen reader hears expanded or collapsed.