Accordion
Accordion groups related disclosure items with single or multiple expansion while keeping content and product policy consumer-owned.
Overview and decision boundary
Use Accordion for a related group of disclosure items whose expansion state benefits from one bounded owner.
Do not use Accordion for navigation trees, routed menus, or unrelated sections.
Plans renew monthly unless cancelled.
import { Accordion, AccordionHeader, AccordionItem, AccordionPanel, AccordionTrigger } from "@nerio-ui/ui/client";<Accordion defaultValue={["billing"]}> <AccordionItem value="billing"> <AccordionHeader> <AccordionTrigger>How does billing work?</AccordionTrigger> </AccordionHeader> <AccordionPanel>Plans renew monthly unless cancelled.</AccordionPanel> </AccordionItem> <AccordionItem value="members"> <AccordionHeader> <AccordionTrigger>Can I invite collaborators?</AccordionTrigger> </AccordionHeader> <AccordionPanel>Workspace owners can invite and remove members.</AccordionPanel> </AccordionItem></Accordion>Installation and imports
Install the editable registry source, or use the matching package entrypoint when the product keeps Nerio as a workspace dependency.
pnpm exec nerio add accordionimport { Accordion, AccordionHeader, AccordionItem, AccordionPanel, AccordionTrigger } from "@nerio-ui/ui/client";Usage
import { Accordion, AccordionHeader, AccordionItem, AccordionPanel, AccordionTrigger } from "@nerio-ui/ui/client";<Accordion defaultValue={["billing"]}> <AccordionItem value="billing"> <AccordionHeader> <AccordionTrigger>How does billing work?</AccordionTrigger> </AccordionHeader> <AccordionPanel>Plans renew monthly unless cancelled.</AccordionPanel> </AccordionItem></Accordion>Variants
| Mode | Use |
|---|---|
Single expansion | Default mode for a compact related set with at most one open item. |
Multiple expansion | Use multiple when people need to compare or keep several sections open. |
Anatomy
| Slot | Purpose |
|---|---|
root | Owns the array of expanded item values. |
item | Stable string identity and optional disabled state. |
header | Semantic heading matched to the surrounding outline. |
trigger | Native button associated with one panel. |
panel | Hidden content that unmounts when closed by default. |
States
| State | Behavior |
|---|---|
Closed | Item value is absent and the panel is removed by default. |
Open | Item value is present in the root value array. |
Disabled | Item remains visible and cannot change state. |
Reduced motion | Panel changes state immediately without travel. |
RTL | Logical alignment follows inherited document direction. |
Motion
- Panel height uses the Base UI measured height variable and shared reveal tokens.
- Opacity reinforces state without carrying essential information.
- Reduced motion makes the state change immediate.
Accessibility
- Uses the Base UI Accordion primitive and one native trigger button for each item.
- Wrap each trigger in AccordionHeader and choose a heading level that fits the surrounding page hierarchy through render composition.
- Each item requires a stable string value for controlled state and predictable associations.
- Single expansion is the default; multiple allows independent open items without changing trigger keyboard semantics.
- Disabled items remain visible but cannot change state.
- Closed panels are unmounted by default so hidden interactive descendants do not remain focusable; keepMounted and hiddenUntilFound preserve browser-hidden semantics.
- Tab follows document order and Enter or Space toggles the focused trigger; Arrow-key roving focus is intentionally not added after the current APG guidance update.
- Height and opacity motion use shared disclosure tokens and become immediate under reduced motion.
- Routing, FAQ schema, fetching, nested-state persistence, and navigation behavior remain consumer-owned.
Review the shared responsibility and evidence boundaries in the Accessibility foundation alongside this component-specific contract. Use the Spacing & layout foundation for shared density, wrapping, overflow, reflow, and component-versus-product ownership guidance. The Color foundation, Typography foundation, and Localization foundation define the shared visual-role, text-resilience, direction, and locale boundaries used by component examples.
API
| Prop | Use |
|---|---|
value / defaultValue | Controlled or uncontrolled arrays of stable string values. |
onValueChange | Receives the next array and cancellable Nerio event details. |
multiple | Allows more than one item to remain open. |
AccordionItem value / disabled | Identifies one item and optionally disables it. |
AccordionHeader render | Selects the heading level required by the document outline. |
Implementation contract
| Contract | Value |
|---|---|
Registry item | accordion installs 6 source files into the configured components directory. |
Base UI | accordion |
Registry dependencies | None. |
Package dependencies | @base-ui/react, clsx, react, tailwind-merge, tailwindcss |
Styling contract
| Contract | Value |
|---|---|
Authoring | Complete, statically detectable Tailwind CSS v4 recipes own component visuals. |
Values | Semantic and component --n-* variables remain the canonical customization layer. |
Overrides | Customizable slots merge consumer className values with tailwindCn so conflicting utilities resolve deterministically. |
Residual CSS | Only shared keyframes and scoped no-Preflight compatibility rules remain; there is no parallel visual selector layer. |
Design notes
- Accordion is content disclosure, not application navigation or a routing owner.
- FAQ schema, nested persistence, fetching, analytics, and product workflow remain consumer-owned.
Do / do not
Do
Group concise, related sections and keep every stable value unique.
Do not
Use Accordion for routed navigation, unrelated page sections, or essential always-visible content.
Related components
Tokens
| Token | Controls |
|---|---|
--n-disclosure-background / border / divider | Grouped surface and item boundaries. |
--n-disclosure-trigger-min-height / padding-inline | Density-aware trigger geometry. |
--n-disclosure-panel-padding-inline / foreground | Panel content rhythm and tone. |
--n-disclosure-focus-ring | Inset trigger focus treatment. |
--n-motion-reveal-duration / easing | Measured-height state transition. |