# Accordion

## Overview

A vertically stacked set of collapsible sections. Each section has a clickable trigger header that reveals or hides its content. Ideal for FAQs, configuration settings, and dense navigation trees where only one (or a few) section needs to be visible at a time.

---

## When to Use

- FAQ sections
- Settings panels with multiple categories
- Navigable tree structures inside a sidebar
- Reducing visual density by hiding supplementary information

## When NOT to Use

- Switching between views — use `<Tabs>` instead.
- A single expandable section — use `<Collapsible>` instead.

---

## Anatomy

```
<Accordion type="single" collapsible>
  <AccordionItem value="item-1">
    <AccordionTrigger>Question or Title</AccordionTrigger>
    <AccordionContent>Content that is revealed</AccordionContent>
  </AccordionItem>
</Accordion>
```

---

## Props

### Accordion

| Prop            | Type                     | Default | Required | Description                                                           |
| --------------- | ------------------------ | ------- | -------- | --------------------------------------------------------------------- |
| `type`          | `'single' \| 'multiple'` | —       | **Yes**  | Single: one open at a time. Multiple: all can be open simultaneously. |
| `collapsible`   | `boolean`                | `false` | No       | When `type="single"`, allows closing the open item by re-clicking.    |
| `defaultValue`  | `string \| string[]`     | —       | No       | Initially open item(s)                                                |
| `value`         | `string \| string[]`     | —       | No       | Controlled open item(s)                                               |
| `onValueChange` | `(v) => void`            | —       | No       | Change handler                                                        |

### AccordionItem

| Prop    | Type     | Required | Description                     |
| ------- | -------- | -------- | ------------------------------- |
| `value` | `string` | **Yes**  | Unique identifier for this item |

---

## Examples

### FAQ (Single, Collapsible)

```tsx
import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from 'xertica-ui/ui';

<Accordion type="single" collapsible className="w-full">
  <AccordionItem value="q-1">
    <AccordionTrigger>Is this library accessible?</AccordionTrigger>
    <AccordionContent>
      Yes. Built entirely on Radix UI with full ARIA support and keyboard navigation.
    </AccordionContent>
  </AccordionItem>
  <AccordionItem value="q-2">
    <AccordionTrigger>How do I apply custom styles?</AccordionTrigger>
    <AccordionContent>
      Override the `className` on triggers or content. Classes are merged via `tailwind-merge`.
    </AccordionContent>
  </AccordionItem>
</Accordion>;
```

### Multiple Open

```tsx
<Accordion type="multiple">
  <AccordionItem value="notifications">
    <AccordionTrigger>Notification Settings</AccordionTrigger>
    <AccordionContent>{/* switches */}</AccordionContent>
  </AccordionItem>
  <AccordionItem value="privacy">
    <AccordionTrigger>Privacy Settings</AccordionTrigger>
    <AccordionContent>{/* options */}</AccordionContent>
  </AccordionItem>
</Accordion>
```

---

## AI Rules

- `AccordionItem` **requires** a unique non-empty `value` string — without it, open/close tracking breaks.
- The animated `ChevronDown` icon is **already built into** `AccordionTrigger`. Do not add another chevron icon.
- `type` is **required** — never omit it.
- Use `type="single" collapsible` for FAQ-style lists. Use `type="multiple"` for settings panels where users may need multiple sections open.
- Do not use Accordion for switching primary views — use `Tabs` for that.

---

## Related Components

- [`Collapsible`](./collapsible.md) — For a single expandable section
- [`Tabs`](./tabs.md) — For view switching