# Accordion

Stacks collapsible sections that each reveal a labelled panel.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Accordion.tsx)

## Overview

Each trigger toggles a labelled panel. By default, one item is open at a time.

## Examples

### Basic

```tsx
import { Accordion, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <Accordion.Root defaultValue={['one']} {...styles.root()}>
      <Accordion.Item value="one">
        <Accordion.Trigger>What is Tempo?</Accordion.Trigger>
        <Accordion.Panel>A blockchain for payments.</Accordion.Panel>
      </Accordion.Item>
      <Accordion.Item value="two">
        <Accordion.Trigger>How do fees work?</Accordion.Trigger>
        <Accordion.Panel>Fees are paid in stablecoins.</Accordion.Panel>
      </Accordion.Item>
    </Accordion.Root>
  )
}

namespace styles {
  export const root = style({ maxWidth: '28rem !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Accordion/Basic.tsx)

### Size

Set `size` to `small`, `medium` (default), or `large`.

```tsx
import { Accordion, Stack, style } from '@tempoxyz/ds'

export const fill = true
function Items(props: Accordion.Root.Props) {
  return (
    <Accordion.Root {...props}>
      <Accordion.Item value="one">
        <Accordion.Trigger>What is Tempo?</Accordion.Trigger>
        <Accordion.Panel>A blockchain for payments.</Accordion.Panel>
      </Accordion.Item>
      <Accordion.Item value="two">
        <Accordion.Trigger>How do fees work?</Accordion.Trigger>
        <Accordion.Panel>Fees are paid in stablecoins.</Accordion.Panel>
      </Accordion.Item>
    </Accordion.Root>
  )
}

export function Demo() {
  return (
    <Stack gap="32" {...styles.stack()}>
      {(['small', 'medium', 'large'] as const).map((size) => (
        <Items defaultValue={['one']} key={size} size={size} />
      ))}
    </Stack>
  )
}

namespace styles {
  export const stack = style({ maxWidth: '28rem !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Accordion/Size.tsx)

### Multiple

Set `multiple` on `Accordion.Root` to keep several items open at once.

```tsx
import { Accordion, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <Accordion.Root multiple {...styles.root()}>
      <Accordion.Item value="one">
        <Accordion.Trigger>What is Tempo?</Accordion.Trigger>
        <Accordion.Panel>A blockchain for payments.</Accordion.Panel>
      </Accordion.Item>
      <Accordion.Item value="two">
        <Accordion.Trigger>How do fees work?</Accordion.Trigger>
        <Accordion.Panel>Fees are paid in stablecoins.</Accordion.Panel>
      </Accordion.Item>
    </Accordion.Root>
  )
}

namespace styles {
  export const root = style({ maxWidth: '28rem !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Accordion/Multiple.tsx)

### Disabled

Set `disabled` on an `Accordion.Item` to block it from opening.

```tsx
import { Accordion, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <Accordion.Root {...styles.root()}>
      <Accordion.Item value="one">
        <Accordion.Trigger>What is Tempo?</Accordion.Trigger>
        <Accordion.Panel>A blockchain for payments.</Accordion.Panel>
      </Accordion.Item>
      <Accordion.Item disabled value="three">
        <Accordion.Trigger>Disabled</Accordion.Trigger>
        <Accordion.Panel>Hidden.</Accordion.Panel>
      </Accordion.Item>
    </Accordion.Root>
  )
}

namespace styles {
  export const root = style({ maxWidth: '28rem !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Accordion/Disabled.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { Accordion } from '@tempoxyz/ds'

<Accordion.Root>
  <Accordion.Item>
    <Accordion.Trigger />
    <Accordion.Panel />
  </Accordion.Item>
</Accordion.Root>
```

## Guidelines

### When to Use

* Shorten a page of related, optional content, such as fee help answers or advanced webhook settings.
* Let people scan summaries and open only the sections they need.

### When Not to Use

* Use [Tabs](/docs/components/tabs) to switch between views of equal weight, such as Balances and Activity.
* Use [ListGroup](/docs/components/list-group) for facts people check at a glance, such as the amount and fee of a payment.
* Use [Stepper](/docs/components/stepper) for steps people complete in order.
* If most people need the content, keep it visible in a [Surface](/docs/components/surface), such as the amount and fee on a payment review.

### Summarize the Panel in the Trigger

A closed panel shows only its trigger. Write each trigger so people can tell what the panel holds before they open it.

**Do:** Write triggers that say what each panel contains.

```tsx
/**
 * Do example for "Summarize the Panel in the Trigger" on the Accordion page.
 * Write triggers that say what each panel contains.
 * @module
 */
import { Accordion } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Accordion.Root>
      <Accordion.Item value="cost">
        <Accordion.Trigger>What does a transfer cost?</Accordion.Trigger>
        <Accordion.Panel>Each transfer pays a network fee in a stablecoin.</Accordion.Panel>
      </Accordion.Item>
      <Accordion.Item value="settle">
        <Accordion.Trigger>When does a payment settle?</Accordion.Trigger>
        <Accordion.Panel>A payment settles when its block is final.</Accordion.Panel>
      </Accordion.Item>
      <Accordion.Item value="tokens">
        <Accordion.Trigger>Which tokens can pay fees?</Accordion.Trigger>
        <Accordion.Panel>Supported stablecoins, such as PathUSD and USDC.</Accordion.Panel>
      </Accordion.Item>
    </Accordion.Root>
  )
}
```

**Don't:** Use labels such as Details, More info, or Other.

```tsx
/**
 * Don't example for "Summarize the Panel in the Trigger" on the Accordion page.
 * Don't use labels such as Details, More info, or Other.
 * @module
 */
import { Accordion } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Accordion.Root>
      <Accordion.Item value="details">
        <Accordion.Trigger>Details</Accordion.Trigger>
        <Accordion.Panel>Each transfer pays a network fee in a stablecoin.</Accordion.Panel>
      </Accordion.Item>
      <Accordion.Item value="more">
        <Accordion.Trigger>More info</Accordion.Trigger>
        <Accordion.Panel>A payment settles when its block is final.</Accordion.Panel>
      </Accordion.Item>
      <Accordion.Item value="other">
        <Accordion.Trigger>Other</Accordion.Trigger>
        <Accordion.Panel>Supported stablecoins, such as PathUSD and USDC.</Accordion.Panel>
      </Accordion.Item>
    </Accordion.Root>
  )
}
```

### Open the Item Most People Need

Opening one item closes the others. Open the item most people need with `defaultValue`. If people compare panels, such as two groups of webhook settings, set `multiple`.

**Do:** Open one item by default, the one most people need.

```tsx
/**
 * Do example for "Open the Item Most People Need" on the Accordion page.
 * Open one item by default, the one most people need.
 * @module
 */
import { Accordion } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Accordion.Root defaultValue={['cost']}>
      <Accordion.Item value="cost">
        <Accordion.Trigger>What does a transfer cost?</Accordion.Trigger>
        <Accordion.Panel>Each transfer pays a network fee in a stablecoin.</Accordion.Panel>
      </Accordion.Item>
      <Accordion.Item value="settle">
        <Accordion.Trigger>When does a payment settle?</Accordion.Trigger>
        <Accordion.Panel>A payment settles when its block is final.</Accordion.Panel>
      </Accordion.Item>
      <Accordion.Item value="tokens">
        <Accordion.Trigger>Which tokens can pay fees?</Accordion.Trigger>
        <Accordion.Panel>Supported stablecoins, such as PathUSD and USDC.</Accordion.Panel>
      </Accordion.Item>
    </Accordion.Root>
  )
}
```

**Don't:** Open every item when people read one at a time.

```tsx
/**
 * Don't example for "Open the Item Most People Need" on the Accordion page.
 * Don't open every item when people read one at a time.
 * @module
 */
import { Accordion } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Accordion.Root defaultValue={['cost', 'settle', 'tokens']} multiple>
      <Accordion.Item value="cost">
        <Accordion.Trigger>What does a transfer cost?</Accordion.Trigger>
        <Accordion.Panel>Each transfer pays a network fee in a stablecoin.</Accordion.Panel>
      </Accordion.Item>
      <Accordion.Item value="settle">
        <Accordion.Trigger>When does a payment settle?</Accordion.Trigger>
        <Accordion.Panel>A payment settles when its block is final.</Accordion.Panel>
      </Accordion.Item>
      <Accordion.Item value="tokens">
        <Accordion.Trigger>Which tokens can pay fees?</Accordion.Trigger>
        <Accordion.Panel>Supported stablecoins, such as PathUSD and USDC.</Accordion.Panel>
      </Accordion.Item>
    </Accordion.Root>
  )
}
```

### Keep Panels Short and Flat

Keep each panel to a few short paragraphs, a list, or a small form. Link to a separate page for more.

**Do:** Answer in a sentence or two inside the panel.

```tsx
/**
 * Do example for "Keep Panels Short and Flat" on the Accordion page.
 * Answer in a sentence or two inside the panel.
 * @module
 */
import { Accordion } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Accordion.Root defaultValue={['retry']}>
      <Accordion.Item value="retry">
        <Accordion.Trigger>Retry policy</Accordion.Trigger>
        <Accordion.Panel>Failed deliveries retry 5 times over 24 hours.</Accordion.Panel>
      </Accordion.Item>
      <Accordion.Item value="signing">
        <Accordion.Trigger>Signing secret</Accordion.Trigger>
        <Accordion.Panel>Each delivery is signed with the webhook's secret.</Accordion.Panel>
      </Accordion.Item>
    </Accordion.Root>
  )
}
```

**Don't:** Nest an accordion inside a panel.

```tsx
/**
 * Don't example for "Keep Panels Short and Flat" on the Accordion page.
 * Don't nest an accordion inside a panel.
 * @module
 */
import { Accordion } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Accordion.Root defaultValue={['retry']}>
      <Accordion.Item value="retry">
        <Accordion.Trigger>Retry policy</Accordion.Trigger>
        <Accordion.Panel>
          <Accordion.Root defaultValue={['attempts']} size="small">
            <Accordion.Item value="attempts">
              <Accordion.Trigger>Attempts</Accordion.Trigger>
              <Accordion.Panel>Failed deliveries retry 5 times over 24 hours.</Accordion.Panel>
            </Accordion.Item>
          </Accordion.Root>
        </Accordion.Panel>
      </Accordion.Item>
      <Accordion.Item value="signing">
        <Accordion.Trigger>Signing secret</Accordion.Trigger>
        <Accordion.Panel>Each delivery is signed with the webhook's secret.</Accordion.Panel>
      </Accordion.Item>
    </Accordion.Root>
  )
}
```

### Keep Collapsed Content Reachable

Closed panels unmount. Set the prop that matches the content, on `Accordion.Root` or an `Accordion.Panel`.

* **Searchable Text (hiddenUntilFound):** Lets find in page search closed panels and open the one that matches.
* **Form Inputs (keepMounted):** Keeps the values of form inputs when their panel closes.

### Explain Instead of Disabling

A disabled item hides content without a reason. Remove the item, or keep it enabled and explain in the panel what is unavailable.

**Do:** Keep the item enabled, and state in the panel when it becomes available.

```tsx
/**
 * Do example for "Explain Instead of Disabling" on the Accordion page.
 * Keep the item enabled, and state in the panel when it becomes available.
 * @module
 */
import { Accordion } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Accordion.Root defaultValue={['withdraw']}>
      <Accordion.Item value="deposit">
        <Accordion.Trigger>Deposit funds</Accordion.Trigger>
        <Accordion.Panel>Send USDC to your wallet address.</Accordion.Panel>
      </Accordion.Item>
      <Accordion.Item value="withdraw">
        <Accordion.Trigger>Withdraw funds</Accordion.Trigger>
        <Accordion.Panel>Withdrawals open after you verify your identity.</Accordion.Panel>
      </Accordion.Item>
    </Accordion.Root>
  )
}
```

**Don't:** Disable an item without a reason.

```tsx
/**
 * Don't example for "Explain Instead of Disabling" on the Accordion page.
 * Don't disable an item without a reason.
 * @module
 */
import { Accordion } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Accordion.Root>
      <Accordion.Item value="deposit">
        <Accordion.Trigger>Deposit funds</Accordion.Trigger>
        <Accordion.Panel>Send USDC to your wallet address.</Accordion.Panel>
      </Accordion.Item>
      <Accordion.Item disabled value="withdraw">
        <Accordion.Trigger>Withdraw funds</Accordion.Trigger>
        <Accordion.Panel>Withdrawals open after you verify your identity.</Accordion.Panel>
      </Accordion.Item>
    </Accordion.Root>
  )
}
```

## Content

* Use questions for help content and nouns for settings groups, such as Retry policy.
* Keep one form across items: all questions or all nouns.
* Answer in the first sentence of the panel, then add detail.
* Don't repeat the trigger at the top of its panel.

## Accessibility

Each item pairs a heading button with its panel, following the [WAI-ARIA Accordion pattern](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/) for required keys.

### Semantics

* **Accordion.Trigger (button):** A native button inside a heading, reachable by heading navigation.
* **Expanded State (aria-expanded):** Reports whether the panel is open. `aria-controls` points at the panel.
* **Accordion.Panel (region):** Each panel is labelled by its trigger.
* **Disabled Items (aria-disabled):** A disabled trigger stays in the tab order.
* **Chevron (aria-hidden):** Hidden from assistive technology.

### Keyboard

* **Move to the Next Trigger (Tab):** Moves focus to the next trigger or into the open panel.
* **Move to the Previous Control (Shift+Tab):** Moves focus to the previous trigger or control.
* **Open or Close the Item (Enter or Space):** Opens or closes the focused item. Without `multiple`, it also closes the open one.

The arrow keys do not move focus between triggers.

### Focus

* **Focus Stays Put:** Focus stays on the trigger when its panel opens or closes.
* **Closed Panels (keepMounted):** A closed panel unmounts by default and leaves the tab order.

### Motion

* **Reduced Motion (prefers-reduced-motion):** Panels fade without animating their height, and the chevron flips instantly.

### Your Responsibilities

* **Fit the Outline (h3):** Triggers render inside an `h3`, so place the accordion under an `h2`.
* **Keep Triggers Plain:** Don't put controls inside a trigger. It is already a button.

## Related

[Tabs](/docs/components/tabs)

Use for switching between views.

[ListGroup](/docs/components/list-group)

Use for expanding a detail under one row.

[Stepper](/docs/components/stepper)

Use for sequential steps.

[Surface](/docs/components/surface)

Use for content that stays visible.
