---
id: wiki-2026-0508-accordion
title: Accordion
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [Collapsible, Disclosure]
duplicate_of: none
source_trust_level: A
confidence_score: 0.9
verification_status: applied
tags: [ui, component, a11y]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: TypeScript
  framework: React
---

# Accordion

## 매 한 줄
> **"매 expand-on-demand UI primitive"**. 매 1980s desktop GUI 의 origin → 매 2026 web 의 ARIA disclosure pattern, FAQ/sidebar/settings 의 default density-saving widget.

## 매 핵심

### 매 mechanism
- 매 header (button) + 매 panel (region) 의 pair.
- 매 `aria-expanded` + `aria-controls` + `region role` 의 a11y triplet.
- 매 single-expand (radio-like) vs multi-expand (checkbox-like).

### 매 modern stack
- 매 Radix UI `Accordion` (headless, WAI-ARIA-compliant).
- 매 React Aria, Headless UI, shadcn/ui Accordion.
- 매 native `<details>/<summary>` (free a11y, limited animation).

### 매 응용
1. FAQ pages (Stripe, GitHub docs).
2. Settings panels (VSCode sidebar).
3. Mobile navigation drawers.

## 💻 패턴

### Radix UI Accordion (single-expand)
```tsx
import * as Accordion from '@radix-ui/react-accordion';

export function FAQ() {
  return (
    <Accordion.Root type="single" collapsible defaultValue="item-1">
      <Accordion.Item value="item-1">
        <Accordion.Trigger className="flex w-full justify-between p-4">
          What is React?
          <ChevronDown className="transition-transform data-[state=open]:rotate-180" />
        </Accordion.Trigger>
        <Accordion.Content className="overflow-hidden data-[state=open]:animate-slideDown">
          A library for UIs.
        </Accordion.Content>
      </Accordion.Item>
    </Accordion.Root>
  );
}
```

### Native `<details>` (zero-JS)
```html
<details>
  <summary>Click to expand</summary>
  <p>Hidden content.</p>
</details>

<style>
  details[open] summary ~ * { animation: slideDown 200ms ease-out; }
  @keyframes slideDown { from { opacity: 0; transform: translateY(-8px); } }
</style>
```

### Custom hook (multi-expand)
```ts
function useAccordion(initial: string[] = []) {
  const [open, setOpen] = useState(new Set(initial));
  const toggle = (id: string) =>
    setOpen(prev => {
      const next = new Set(prev);
      next.has(id) ? next.delete(id) : next.add(id);
      return next;
    });
  return { isOpen: (id: string) => open.has(id), toggle };
}
```

### 매 height animation (interpolate to auto)
```css
[data-state='closed'] { grid-template-rows: 0fr; }
[data-state='open']   { grid-template-rows: 1fr; }
.panel { display: grid; transition: grid-template-rows 200ms; }
.panel > div { overflow: hidden; }
```

### 매 keyboard support (Radix-equivalent)
```ts
function onKeyDown(e: KeyboardEvent) {
  if (e.key === 'ArrowDown') focusNextHeader();
  if (e.key === 'ArrowUp')   focusPrevHeader();
  if (e.key === 'Home')      focusFirstHeader();
  if (e.key === 'End')       focusLastHeader();
}
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| 0-JS, simple FAQ | `<details>` |
| Animated, controlled | Radix UI |
| Form section | Custom (preserve mounted state) |

**기본값**: Radix UI Accordion + Tailwind animations.

## 🔗 Graph
- 부모: [[Headless-UI]]
- 변형: [[Collapsible]]
- Adjacent: [[Radix-UI]] · [[ARIA]]

## 🤖 LLM 활용
**언제**: density-saving long-form lists, optional sections.
**언제 X**: critical information (hidden by default = missed); sequential workflows (use Stepper).

## ❌ 안티패턴
- **Multi-open by default 의 visual chaos**: Use single-expand for nav.
- **No `aria-expanded`**: screen readers 매 broken.
- **Animating `height: auto`**: Use grid-rows trick or `max-height`.

## 🧪 검증 / 중복
- Verified (Radix UI docs, WAI-ARIA Accordion Pattern).
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — Accordion FULL content with Radix patterns |