---
title: Accordion
description: Coordinate one or several expandable sections with shared disclosure rules.
package: moraine
version: 0.11.0
repository: https://github.com/subframe7536/moraine
---

# Accordion

> Coordinate one or several expandable sections with shared disclosure rules.

## Anatomy

```text
Accordion [component; slot=root]
└── item [slot]
    ├── header [slot]
    │   └── trigger [slot]
    │       ├── leading [slot]
    │       ├── label [slot]
    │       └── trailing [slot]
    └── content [slot]
        └── body [slot]
```

## Usage

Use Accordion for several related disclosures that share one open-item policy. For a single independent
disclosure, use [Collapsible](https://moraine.subf.dev/components/collapsible.md).

```tsx
import { Accordion } from 'moraine'

export function Example() {
  return (
    <Accordion items={[{ value: 'shipping', label: 'Shipping', content: 'Ships in two days.' }]} />
  )
}
```

### Content

`content` accepts text or JSX, or a component that receives `{ value, expanded, disabled }`.
Use the component form when the panel depends on the item state. Content mounts on first open. `headingLevel` (default `3`) sets the heading level that
wraps each trigger. `icon` adds a leading icon to an item, and `expandIcon` replaces the indicator icon
for every item.

```tsx
<Accordion
  items={[
    { value: 'billing', label: 'Billing', content: (props) => <Invoices open={props.expanded} /> },
  ]}
/>
```

### Open items

`value`, `defaultValue`, and `onValueChange` always use an array of item values. By default, opening an
item closes the others. Set `multiple` to allow several open items. Pair `value` with `onValueChange`
when the page owns the open set. `onValueChange` receives the complete next array and fires only for
user toggles, not for changes you make to `value`. In single mode, `collapsible` (default `true`)
controls whether the open item can close; with `multiple`, every item can always close.

```tsx
const [open, setOpen] = createSignal<string[]>(['shipping'])

<Accordion items={items} value={open()} onValueChange={setOpen} collapsible />
<Accordion multiple defaultValue={['general', 'security']} items={items} />
```

### Content lifetime

The content shell always stays mounted, so each trigger's `aria-controls` points to a real element.
`forceMount` controls only the content inside that shell. By default, content mounts on first open and
unmounts when it closes. Set `forceMount` to mount content before the first open and keep it mounted, so
hidden fields preserve local state.

```tsx
<Accordion forceMount defaultValue={['notes']} items={items} />
```

### Keyboard interaction

| Key                                 | Description                                  |
| ----------------------------------- | -------------------------------------------- |
| <kbd>Enter</kbd> / <kbd>Space</kbd> | Toggles the focused trigger when enabled.    |
| <kbd>ArrowDown</kbd>                | Moves focus to the next enabled trigger.     |
| <kbd>ArrowUp</kbd>                  | Moves focus to the previous enabled trigger. |
| <kbd>Home</kbd>                     | Moves focus to the first enabled trigger.    |
| <kbd>End</kbd>                      | Moves focus to the last enabled trigger.     |

Arrow-key focus wraps from the last trigger to the first by default. Set `loop={false}` to stop at
either end. Disabled items are skipped.

## Examples

### Answer a workspace FAQ

Keep one section open at a time. Read `value` when surrounding copy needs to name the active topic.

```tsx
import { Accordion } from 'moraine'
import { createSignal } from 'solid-js'

export function Single() {
  const [openValue, setOpenValue] = createSignal<string[]>(['invite'])

  return (
    <div class="max-w-xl w-full space-y-3">
      <Accordion
        value={openValue()}
        onValueChange={setOpenValue}
        items={[
          {
            value: 'invite',
            label: 'What should I check before inviting a member?',
            icon: 'i-lucide:user-plus',
            content:
              'Confirm the email address and choose the role that gives the person only the access they need.',
          },
          {
            value: 'archive',
            label: 'When should I archive a project?',
            icon: 'i-lucide:archive',
            content:
              'Archive work that no longer needs active updates after your team has saved any reports it still needs.',
          },
          {
            value: 'status',
            label: 'Where should a release status be recorded?',
            icon: 'i-lucide:list-checks',
            content:
              'Keep the status on the release record so everyone sees the same source of truth.',
          },
        ]}
      />

      <p class="text-xs text-muted-foreground">
        Active section: <span class="text-foreground font-medium">{openValue()[0] ?? 'none'}</span>
      </p>
    </div>
  )
}
```

### Configure several workspace sections

Set `multiple` when operators need billing, security, and general settings open together.

```tsx
import { Accordion } from 'moraine'

export function Multiple() {
  return (
    <Accordion
      multiple
      defaultValue={['general', 'security']}
      items={[
        {
          value: 'general',
          label: 'General Workspace Information',
          icon: 'i-lucide:settings',
          content: 'Configure your organization name, slug, avatar, and default language settings.',
        },
        {
          value: 'security',
          label: 'Security & Access Control',
          icon: 'i-lucide:shield-alert',
          content:
            'Manage SSO providers, enforce two-factor authentication, and review active sessions.',
        },
        {
          value: 'billing',
          label: 'Subscription & Invoices',
          icon: 'i-lucide:credit-card',
          content:
            'View current plan usage, payment methods, and download historical invoice receipts.',
        },
      ]}
      classes={{
        root: 'max-w-xl rounded-xl b-1 b-border border-border bg-card',
        trigger: 'px-4',
        content: 'px-4 text-foreground text-sm',
      }}
    />
  )
}
```

### Complete a setup checklist with a locked step

Use item `disabled` for sections the current plan cannot open. Put lists or callouts in `content`
when the answer is more than a paragraph.

```tsx
import { Accordion } from 'moraine'

export function DisabledCustomContent() {
  return (
    <Accordion
      defaultValue={['setup']}
      expandIcon="icon-plus"
      items={[
        {
          value: 'setup',
          label: 'Setup checklist',
          icon: 'i-lucide-list-checks',
          content: (
            <div class="space-y-2">
              <p>Complete these steps before inviting your team:</p>
              <ul class="pl-5 list-disc space-y-1">
                <li>Create workspace profile</li>
                <li>Configure authentication</li>
                <li>Enable notifications</li>
              </ul>
              <div class="text-xs text-muted-foreground p-2 rounded-md bg-muted">
                Tip: You can finish the checklist later from Settings.
              </div>
            </div>
          ),
        },
        {
          value: 'security',
          label: 'Security review (Locked)',
          icon: 'i-lucide-shield-check',
          disabled: true,
          content: 'Available on Pro plan and above.',
        },
        {
          value: 'integrations',
          label: 'Integrations',
          icon: 'i-lucide-plug',
          content: (
            <div class="pt-2 space-y-2">
              <p>Connect your tools to automate the workflow.</p>
              <p>
                Supported: <strong>GitHub</strong>, <strong>Slack</strong>, and{' '}
                <strong>Notion</strong>.
              </p>
            </div>
          ),
        },
      ]}
      classes={{
        root: 'max-w-xl rounded-lg b-1 b-border border-border bg-background',
        trigger: 'px-3',
        content: 'px-4 text-foreground',
      }}
    />
  )
}
```

### Keep draft notes while a section closes

Set `forceMount` so inputs inside a panel keep their values across toggles.

```tsx
import { Accordion, Input } from 'moraine'

export function ContentLifetime() {
  return (
    <div class="max-w-md w-full">
      <Accordion
        collapsible
        forceMount
        defaultValue={['settings']}
        items={[
          {
            value: 'settings',
            label: 'Persistent form state',
            content: (
              <div class="py-2 space-y-2">
                <p class="text-xs text-muted-foreground">
                  Inputs retain their state across open/close toggles.
                </p>
                <Input placeholder="Preserved input text" defaultValue="Draft notes" />
              </div>
            ),
          },
        ]}
      />
    </div>
  )
}
```

### Drive the open FAQ from page state

Pair `value` with `onValueChange`. The array always holds item values, even in single mode. Surrounding
copy can read the same signal to name the active topic.

```tsx
import { Accordion } from 'moraine'
import type { AccordionT } from 'moraine'
import { createSignal } from 'solid-js'

const FAQ_ITEMS = [
  {
    value: 'q1',
    label: 'Is Moraine SSR-compatible?',
    content: 'Yes, Moraine is designed for full SolidStart SSR and SSG hydration safety.',
  },
  {
    value: 'q2',
    label: 'How does styling work?',
    content:
      'Moraine uses atomic class styling with official presets and plugins for UnoCSS and Tailwind CSS.',
  },
] satisfies AccordionT.Item[]

export function OpenItems() {
  const [active, setActive] = createSignal<string[]>(['q1'])

  return (
    <div class="max-w-md w-full space-y-3">
      <Accordion collapsible items={FAQ_ITEMS} value={active()} onValueChange={setActive} />
      <p class="text-xs text-muted-foreground">
        Open item: <span class="text-foreground font-mono">{active()[0] ?? 'none'}</span>
      </p>
    </div>
  )
}
```

## API Reference

### Attributes

| Attributes | Slot | Description |
| --- | --- | --- |
| `data-disabled` | `accordion`, `accordion-item`, `accordion-trigger` | Present when the component, slot, or item is disabled. |
| `data-closed` | `accordion-item`, `accordion-trigger`, `accordion-content` | Present when disclosure or transition content is closed. |
| `data-expanded` | `accordion-item`, `accordion-trigger`, `accordion-trailing`, `accordion-content` | Present when the panel, accordion, or menu is expanded. |

### Props

Props for the Accordion component.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| collapsible | boolean \| undefined | true | Whether the expanded item can be closed by activating its trigger again. Only applies when<br>`multiple` is `false`; with `multiple`, every item can always be collapsed. |
| defaultValue | string[] \| undefined | [] | Item values expanded on first render when `value` is not provided. Read once at creation. |
| disabled | boolean \| undefined | false | Whether every item is disabled, regardless of each item's own `disabled`. No trigger can be<br>toggled or reached with arrow keys. |
| expandIcon | IconT.Name \| undefined | 'icon-chevron-down' | Name of the icon rendered after the label in every item's trigger, typically an expand<br>indicator. |
| forceMount | boolean \| undefined | false | Whether closed content stays mounted. When `false`, content mounts on first open and<br>unmounts once it closes; when `true`, content mounts even before the first open. |
| headingLevel | 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined | 3 | Heading level (1 to 6) of the element that wraps each trigger, rendered as `<h1>` to `<h6>`.<br>Pick the level that fits the surrounding document outline. |
| id | string \| undefined | — | Id of the root element. Also used as the prefix of the generated trigger and content ids that<br>link each trigger to its panel through `aria-controls` and `aria-labelledby`. A unique id is<br>generated when omitted. |
| items | ({<br>  /** Header label rendered inside the trigger button. When omitted and `ariaLabel` is not set,<br>the trigger's accessible name falls back to `value`. */<br>  label?: JSX.Element;<br>  /** Accessible label for the accordion trigger button.<br>Useful when `label` is omitted, icon-only, or contains non-text content. */<br>  ariaLabel?: string;<br>  /** Unique value identifying the item. It is the entry stored in the accordion's `value` array and<br>passed to `onValueChange`; duplicates trigger a development warning. */<br>  value: string;<br>  /** Whether this item's trigger is disabled. A disabled item cannot be toggled and is skipped by<br>arrow-key, `Home` and `End` navigation. */<br>  disabled?: boolean;<br>  /** Name of an icon rendered before the label inside the trigger. */<br>  icon?: IconT.Name;<br>  /** Panel content for the item. Accepts static JSX or a component that receives<br>`{ expanded, disabled, value }`. It is mounted when the item first opens (see<br>`forceMount` on the accordion). */<br>  content?: JSX.Element \| Component<ContentRenderProps>;<br>  /** Extra class applied to this item's root element, merged after the `item` slot class and<br>overridable by `classes.item`. */<br>  class?: SlotClassValue;<br>})[] \| undefined | — | Items to render, in order. Each item needs a unique `value`; `label`, `icon`, `content`,<br>`disabled`, `ariaLabel` and `class` are optional. |
| loop | boolean \| undefined | true | Whether `ArrowDown` and `ArrowUp` focus wraps from the last enabled trigger to the first and<br>vice versa. `Home` and `End` always jump to the first and last enabled trigger. |
| multiple | boolean \| undefined | false | Whether several items can be expanded at once. When `false`, opening an item replaces the<br>current `value` with just that item, which closes the others. |
| onValueChange | ((value: string[]) => void) \| undefined | — | Called when a user toggles an item (trigger click, `Enter`, `Space`, or browser find-in-page<br>revealing hidden content). Receives the complete next array of expanded values, in both<br>controlled and uncontrolled mode. It is not called for changes you make to `value`. |
| value | string[] \| undefined | — | Controlled list of expanded item values. Always an array, even when `multiple` is `false`.<br>Leave it `undefined` for uncontrolled usage; when set, update it from `onValueChange`. |
| class | SlotClassValue \| undefined | — | Class applied to the component root or trigger element. |
| classes | Classes \| undefined | — | Family slot class defaults for this instance. |
| style | SlotStyleValue \| undefined | — | Style applied to the component root or trigger element. |
| styles | Styles \| undefined | — | Family slot style defaults for this instance. |

**`items` example**

```tsx
import { Accordion } from 'moraine'

<Accordion
  defaultValue={['intro']}
  items={[
    { value: 'intro', label: 'Intro', icon: 'icon-info', content: 'Getting started.' },
    { value: 'faq', label: 'FAQ', content: (state) => (state.expanded ? 'Open' : 'Closed') },
    { value: 'beta', label: 'Beta', disabled: true },
  ]}
/>
```

**`onValueChange` example**

```tsx
import { Accordion } from 'moraine'

<Accordion
  multiple
  items={[
    { value: 'a', label: 'A', content: 'First' },
    { value: 'b', label: 'B', content: 'Second' },
  ]}
  onValueChange={(value) => console.log(value)}
/>
```
