ui/components/accordion

Accordion

Collapsible content sections with single or multiple open items. Supports controlled and uncontrolled modes.

Preview

tsx

1 import {2   Accordion,3   AccordionContent,4   AccordionHeader,5   AccordionItem,6   AccordionTrigger,7 } from "@/components/ui/accordion";8 import { InlineCode } from "@/components/ui/code-block";9 10 export default function AccordionDefault() {11   return (12     <Accordion defaultValue="item-1">13       <AccordionItem value="item-1">14         <AccordionHeader>15           <AccordionTrigger>What is @diffgazer/ui?</AccordionTrigger>16         </AccordionHeader>17         <AccordionContent>18           <p className="text-sm text-muted-foreground">19             A terminal-inspired component registry for React. Install components via CLI and own the20             source.21           </p>22         </AccordionContent>23       </AccordionItem>24       <AccordionItem value="item-2">25         <AccordionHeader>26           <AccordionTrigger>How do I install components?</AccordionTrigger>27         </AccordionHeader>28         <AccordionContent>29           <p className="text-sm text-muted-foreground">30             Run <InlineCode>dgadd add button</InlineCode> to add a component to your project.31           </p>32         </AccordionContent>33       </AccordionItem>34       <AccordionItem value="item-3">35         <AccordionHeader>36           <AccordionTrigger>Can I customize components?</AccordionTrigger>37         </AccordionHeader>38         <AccordionContent>39           <p className="text-sm text-muted-foreground">40             Yes. Components are copied into your project as source files. Modify them freely.41           </p>42         </AccordionContent>43       </AccordionItem>44       {/* Disabled items dim their trigger and are skipped by arrow navigation. */}45       <AccordionItem value="item-4" disabled>46         <AccordionHeader>47           <AccordionTrigger>Enterprise support (disabled)</AccordionTrigger>48         </AccordionHeader>49         <AccordionContent>50           <p className="text-sm text-muted-foreground">Not available on this plan.</p>51         </AccordionContent>52       </AccordionItem>53     </Accordion>54   );55 }56

Installation

$pnpm exec dgadd add ui/accordion

[Installs to]src/components/ui/accordion[Item]ui/accordion

dgadd is not public on npm yet. Until the first release, pack @diffgazer/add from the repository and install that tarball into this app, which is what puts dgadd on pnpm exec.

UI components require Tailwind CSS v4. Local copy mode imports src/styles/styles.css; package mode uses @diffgazer/ui CSS once packages are available.

Usage

tsx

1 import {2   Accordion,3   AccordionContent,4   AccordionHeader,5   AccordionItem,6   AccordionTrigger,7 } from "@/components/ui/accordion";8 import { InlineCode } from "@/components/ui/code-block";9 10 export default function AccordionDefault() {11   return (12     <Accordion defaultValue="item-1">13       <AccordionItem value="item-1">14         <AccordionHeader>15           <AccordionTrigger>What is @diffgazer/ui?</AccordionTrigger>16         </AccordionHeader>17         <AccordionContent>18           <p className="text-sm text-muted-foreground">19             A terminal-inspired component registry for React. Install components via CLI and own the20             source.21           </p>22         </AccordionContent>23       </AccordionItem>24       <AccordionItem value="item-2">25         <AccordionHeader>26           <AccordionTrigger>How do I install components?</AccordionTrigger>27         </AccordionHeader>28         <AccordionContent>29           <p className="text-sm text-muted-foreground">30             Run <InlineCode>dgadd add button</InlineCode> to add a component to your project.31           </p>32         </AccordionContent>33       </AccordionItem>34       <AccordionItem value="item-3">35         <AccordionHeader>36           <AccordionTrigger>Can I customize components?</AccordionTrigger>37         </AccordionHeader>38         <AccordionContent>39           <p className="text-sm text-muted-foreground">40             Yes. Components are copied into your project as source files. Modify them freely.41           </p>42         </AccordionContent>43       </AccordionItem>44       {/* Disabled items dim their trigger and are skipped by arrow navigation. */}45       <AccordionItem value="item-4" disabled>46         <AccordionHeader>47           <AccordionTrigger>Enterprise support (disabled)</AccordionTrigger>48         </AccordionHeader>49         <AccordionContent>50           <p className="text-sm text-muted-foreground">Not available on this plan.</p>51         </AccordionContent>52       </AccordionItem>53     </Accordion>54   );55 }56

Examples

Multiple Open

Preview

tsx

1 import {2   Accordion,3   AccordionContent,4   AccordionItem,5   AccordionTrigger,6 } from "@/components/ui/accordion";7 8 export default function AccordionMultiple() {9   return (10     <Accordion type="multiple" defaultValue={["item-1", "item-3"]}>11       <AccordionItem value="item-1">12         <AccordionTrigger>Section A</AccordionTrigger>13         <AccordionContent>14           <p className="text-sm text-muted-foreground">15             Multiple sections can be open simultaneously.16           </p>17         </AccordionContent>18       </AccordionItem>19       <AccordionItem value="item-2">20         <AccordionTrigger>Section B</AccordionTrigger>21         <AccordionContent>22           <p className="text-sm text-muted-foreground">23             Click any trigger to toggle that section independently.24           </p>25         </AccordionContent>26       </AccordionItem>27       <AccordionItem value="item-3">28         <AccordionTrigger>Section C</AccordionTrigger>29         <AccordionContent>30           <p className="text-sm text-muted-foreground">31             This section starts open because its value is in the defaultValue array.32           </p>33         </AccordionContent>34       </AccordionItem>35     </Accordion>36   );37 }38

Custom Handle

Preview

tsx

1 import {2   Accordion,3   AccordionContent,4   AccordionItem,5   AccordionTrigger,6 } from "@/components/ui/accordion";7 8 export default function AccordionCustomHandle() {9   return (10     <Accordion type="multiple" defaultValue={["item-1"]}>11       <AccordionItem value="item-1">12         <AccordionTrigger handle={<span className="text-xs font-mono shrink-0">+</span>}>13           Custom handle (+)14         </AccordionTrigger>15         <AccordionContent>16           <p className="text-sm text-muted-foreground">17             Pass any ReactNode as the handle prop to replace the default chevron.18           </p>19         </AccordionContent>20       </AccordionItem>21       <AccordionItem value="item-2">22         <AccordionTrigger handle={null}>No handle (hidden)</AccordionTrigger>23         <AccordionContent>24           <p className="text-sm text-muted-foreground">25             Pass handle={"{null}"} to hide the indicator entirely.26           </p>27         </AccordionContent>28       </AccordionItem>29       <AccordionItem value="item-3">30         <AccordionTrigger>Default chevron</AccordionTrigger>31         <AccordionContent>32           <p className="text-sm text-muted-foreground">33             Without the handle prop, the animated Chevron component is used by default.34           </p>35         </AccordionContent>36       </AccordionItem>37     </Accordion>38   );39 }40

Source Variant

Preview

tsx

1 import {2   Accordion,3   AccordionContent,4   AccordionItem,5   AccordionTrigger,6 } from "@/components/ui/accordion";7 import { CodeBlock, CodeBlockContent, CodeBlockLine } from "@/components/ui/code-block";8 9 // variant="source" is the small inline toggle used above code and diff panes.10 const SOURCE_LINES = [11   { number: 1, content: 'import { Accordion } from "@diffgazer/ui/components/accordion";' },12   { number: 2, content: "" },13   { number: 3, content: 'export const Faq = () => <Accordion type="multiple" />;' },14 ];15 16 export default function AccordionSourceVariant() {17   return (18     <Accordion type="multiple" defaultValue={["source"]} className="w-full">19       <AccordionItem value="source">20         <AccordionTrigger variant="source">Show source</AccordionTrigger>21         <AccordionContent>22           <CodeBlock>23             <CodeBlockContent>24               {SOURCE_LINES.map((line) => (25                 <CodeBlockLine key={line.number} {...line} />26               ))}27             </CodeBlockContent>28           </CodeBlock>29         </AccordionContent>30       </AccordionItem>31       <AccordionItem value="notes">32         <AccordionTrigger variant="source">Show notes</AccordionTrigger>33         <AccordionContent>34           <p className="text-xs text-muted-foreground">35             The source variant drops to text-xs and adds bottom spacing so it reads as a caption36             above the block it toggles, not as a section header.37           </p>38         </AccordionContent>39       </AccordionItem>40     </Accordion>41   );42 }43

API Reference

Accordion

Name	Type	Default	Description
type	"single" \| "multiple"	"single"	Single allows one open item; multiple allows several open at once. Switches the value/onChange/defaultValue shape from string to string[].
value	string \| undefined \| string[]	—	Controlled open value(s). In single mode, undefined means no item is open. In multiple mode, undefined is normalized to an empty array while remaining controlled.
defaultValue	string \| string[]	—	Initial open value(s) for uncontrolled mode.
onChange	((value: string \| undefined) => void) \| ((value: string[]) => void)	—	Fired when the open value(s) change. Single mode emits undefined when no item is open; multiple mode emits an array.
collapsible	boolean	true (single mode)	Single mode only. When false, the currently open item cannot be closed by clicking it.
childrenrequired	ReactNode	—	AccordionItem children.

Accordion.Item

Name	Type	Default	Description
valuerequired	string	—	Stable identifier matched against the Accordion value.
disabled	boolean	false	Disables the item: trigger is not focusable and not toggleable.
childrenrequired	ReactNode	—	Header and Content children.

Accordion.Header

Name	Type	Default	Description
as	"h2" \| "h3" \| "h4" \| "h5" \| "h6"	"h3"	Heading level wrapping the trigger.
childrenrequired	ReactNode	—	Typically an Accordion.Trigger.

Accordion.Trigger

Name	Type	Default	Description
variant	"default" \| "source"	"default"	Visual style. Source is a smaller variant used for inline source toggles.
headingLevel	"h2" \| "h3" \| "h4" \| "h5" \| "h6"	"h3"	Heading level wrapping the trigger button (APG heading requirement). Ignored when the trigger is composed inside an AccordionHeader, which then owns the heading.
handle	ReactNode \| null	<Chevron open={isOpen} size="sm" />	Custom handle element. Pass null to hide the chevron entirely.
childrenrequired	ReactNode	—	Trigger label.

Accordion.Content

Name	Type	Default	Description
region	boolean	false	Opt in to role="region" with aria-labelledby pointing at the trigger while the panel is open. Off by default per the APG accordion pattern (region is listed as optional). Enable for a small number of substantive panels (typically six or fewer); leave it off for many short items to avoid landmark noise.
childrenrequired	ReactNode	—	Collapsible body content.

Data attributes

Attribute	Applies to	Values	Description
data-state	Accordion.Item / Accordion.Trigger / Accordion.Content	"open" \| "closed"	Open state for item, trigger, and panel styling.
data-disabled	Accordion.Item / Accordion.Trigger	present when disabled	Marks disabled accordion items and triggers.
data-value	Accordion.Trigger	item value	Stable item value used by navigation and open-state lookup.

Accessibility

Keyboard Navigation

Built-in keyboard navigation via @diffgazer/keys navigation helpers. Arrow Up/Down moves focus between accordion triggers, Home/End jumps to first/last, Enter/Space toggles the focused item.

Key	Action
ArrowUp / ArrowDown	Moves focus to the previous or next enabled trigger.
Home / End	Moves focus to the first or last enabled trigger.
Enter / Space	Toggles the focused trigger.

Default (with keyboard support)

Preview

tsx

1 import {2   Accordion,3   AccordionContent,4   AccordionHeader,5   AccordionItem,6   AccordionTrigger,7 } from "@/components/ui/accordion";8 import { InlineCode } from "@/components/ui/code-block";9 10 export default function AccordionDefault() {11   return (12     <Accordion defaultValue="item-1">13       <AccordionItem value="item-1">14         <AccordionHeader>15           <AccordionTrigger>What is @diffgazer/ui?</AccordionTrigger>16         </AccordionHeader>17         <AccordionContent>18           <p className="text-sm text-muted-foreground">19             A terminal-inspired component registry for React. Install components via CLI and own the20             source.21           </p>22         </AccordionContent>23       </AccordionItem>24       <AccordionItem value="item-2">25         <AccordionHeader>26           <AccordionTrigger>How do I install components?</AccordionTrigger>27         </AccordionHeader>28         <AccordionContent>29           <p className="text-sm text-muted-foreground">30             Run <InlineCode>dgadd add button</InlineCode> to add a component to your project.31           </p>32         </AccordionContent>33       </AccordionItem>34       <AccordionItem value="item-3">35         <AccordionHeader>36           <AccordionTrigger>Can I customize components?</AccordionTrigger>37         </AccordionHeader>38         <AccordionContent>39           <p className="text-sm text-muted-foreground">40             Yes. Components are copied into your project as source files. Modify them freely.41           </p>42         </AccordionContent>43       </AccordionItem>44       {/* Disabled items dim their trigger and are skipped by arrow navigation. */}45       <AccordionItem value="item-4" disabled>46         <AccordionHeader>47           <AccordionTrigger>Enterprise support (disabled)</AccordionTrigger>48         </AccordionHeader>49         <AccordionContent>50           <p className="text-sm text-muted-foreground">Not available on this plan.</p>51         </AccordionContent>52       </AccordionItem>53     </Accordion>54   );55 }56

Notes

Requires @diffgazer/keys (package mode)

Accordion's arrow-key trigger navigation imports from the required @diffgazer/keys peer. Package consumers must install @diffgazer/keys with @diffgazer/ui; packages are not yet published to npm, so until the first release install both from locally packed tarballs. Importing @diffgazer/ui/components/accordion without keys fails at module load with an error naming the missing @diffgazer/keys package. Copy/dgadd consumers do not need the package — copy mode rewrites the keyboard helpers to local source.

Single vs Multiple

In single mode (default), only one item can be open. Set type='multiple' to allow several items open at once.

Collapsible

In single mode, collapsible defaults to true. With collapsible={false}, an accordion may still initialize with no open item, but once an item is selected, activating it again cannot close it.

Heading semantics

The APG accordion pattern requires each trigger to sit inside a heading. AccordionTrigger wraps itself in a default h3; set its headingLevel prop to match the surrounding document outline. Compose an explicit AccordionHeader to control the level instead — the trigger then skips its own wrapper so no doubled heading appears.

Keyboard Navigation

Arrow Up/Down moves focus between triggers. Home/End jumps to first/last trigger. Enter or Space toggles the focused item. Navigation wraps around.

Region role (opt-in)

AccordionContent accepts a region prop. When set, the open panel exposes role="region" with aria-labelledby pointing at its trigger. The APG accordion pattern lists this role as optional, so the default is off. Enable it for a small number of substantive panels (typically six or fewer) where each panel functions as its own landmark; leave it off when an accordion has many short items, since extra landmarks add noise to assistive-technology rotors.

Region role

AccordionContent accepts a region prop that opts the open panel into role="region" with aria-labelledby pointing at its trigger. The default is false.

tsx

<Accordion.Content region>{children}</Accordion.Content>

The APG accordion pattern lists this role as optional ("MAY"), which is why the prop is opt-in rather than the default:

Enable it when each panel functions as its own landmark and the accordion has a small number of substantive sections (typically six or fewer). Assistive-technology users can then jump straight to a panel via the landmark rotor.
Leave it off when an accordion has many short items or stacks alongside other accordions on the page. Extra landmarks add noise to the rotor and dilute the value of true page-level regions.

Behavior:

The role is only exposed while the panel is open. Collapsed panels never expose role="region".
The accessible name comes from the trigger via aria-labelledby; no extra label markup is required on the panel.
All other a11y wiring (aria-expanded, aria-controls, native <button> semantics, inert on collapsed content) is unconditional and unaffected by this prop.

Source

Install via CLI: pnpm exec dgadd add ui/accordion. Keyboard hooks are included as standalone copies. For the full experience, use --integration keys.

Highlighted source loads after this disclosure opens. Browse the source repository.

Accordion

Installation

Usage

Examples

Multiple Open

Custom Handle

Source Variant

API Reference

Accordion

Accordion.Item

Accordion.Header

Accordion.Trigger

Accordion.Content

Data attributes

Accessibility

Keyboard Navigation

Default (with keyboard support)

Notes

Requires @diffgazer/keys (package mode)

Single vs Multiple

Collapsible

Heading semantics

Keyboard Navigation

Region role (opt-in)

Region role

Source

View component source (26 files)