Accordion
APG Accordion 패턴 컴파운드 컴포넌트 — single/multiple 펼침을 비제어(defaultValue) 또는 제어(value)로 소유, h3+button과 region으로 구조화.
마지막 업데이트 2026-06-11
한눈에#
긴 콘텐츠를 섹션별로 접어 두고 필요한 것만 펼치는 APG Accordion입니다 — single(하나만)·multiple(동시) 펼침을 지원합니다.
- APG Accordion
- single·multiple 펼침
- h3 > button + region
- 제어·비제어
헤더는 h3 > button으로 문서 아웃라인에 노출되고, 패널은 region으로 연결됩니다
사용 시점#
긴 콘텐츠를 섹션별로 접어 필요한 것만 펼치면 Accordion — 한 뷰만 전환하거나 본문 없는 토글은 다른 컴포넌트입니다.
권장 — 이렇게 쓰세요
지양 — 이러지 마세요
쓴다 — FAQ·설정 그룹처럼 섹션을 접어 두고 필요한 것만 펼침(multiple로 동시 비교도)
대신 Tabs — 한 번에 한 뷰만 보이고 패널을 전환할 때
대신 SegmentedButton — 접을 본문 없이 옵션만 토글할 때
플레이그라운드#
컨트롤로 props를 조작하면 미리보기와 코드가 실시간 갱신됩니다.
Accordion를 직접 조작해 보세요
속성·테마·토큰을 바꾸고 React·Flutter 코드를 확인하는 풀스크린 빌더로 엽니다.
플레이그라운드는 넓은 작업 영역이 필요해 웹·태블릿에서 편집할 수 있어요.
변형#
type이 변형 축입니다 — 'single'(기본)은 새 항목을 펼치면 이전 항목이
접히고, 'multiple'은 여러 항목을 동시에 펼칩니다.
크기#
단일 크기입니다 — 트리거 패딩 space.4/6, 레이블 font-size.body-1,
본문 font-size.body-2 고정. 3단 size는 component 토큰 신설 기준(§4)
미충족으로 도입하지 않았습니다.
상태#
비제어/제어 컴파운드입니다 — 기본은 비제어로 <Accordion type defaultValue>가 펼침
상태(내부적으로 항상 배열)를 소유합니다. value를 주면 제어 모드가 되어 부모가 상태를
소유하고, 트리거 클릭 등 모든 토글은 내부 상태를 쓰지 않고 onValueChange로 펼쳐진 value
배열만 통지합니다(렌더는 부모 value를 따름). value는 defaultValue와 같은 모양 —
single은 문자열, multiple은 배열 — 을 받으며 둘 다 내부에서 배열로 정규화됩니다. 펼침/접힘은
aria-expanded와 hidden 토글로 표현되고 Hover/Focus는 CSS 의사클래스입니다.
Props#
점 표기(Accordion.Item)와 평탄 이름(AccordionItem)은 동일 함수입니다 —
서버 컴포넌트(RSC)에서는 클라이언트 참조에 점 접근이 해석되지 않으므로
평탄 이름을 사용하세요(이 문서의 데모도 평탄 이름).
<Accordion> (루트)
| Prop | 타입 | 기본값 | 설명 |
|---|---|---|---|
type | 'single' | 'multiple' | — | single: 한 번에 하나만 펼침 / multiple: 여러 개 동시 펼침 |
value | string | readonly string[] | — | 제어 펼침 값 — 제공하면 제어 모드(내부 상태 무시, 전환이 onValueChange로 통지). single=문자열, multiple=배열 권장 |
defaultValue | string | readonly string[] | — | 초기 펼침 값 — 이후 상태는 내부 소유(비제어, value 미제공 시) |
onValueChange | (value: readonly string[]) => void | — | 펼침 변경 콜백 — 항상 펼쳐진 value 배열 |
className | string | — | 루트 클래스 합성 |
ref | Ref<HTMLDivElement> | — | 루트 <div>로 전달되는 ref (React 19 ref-as-prop) |
<Accordion.Item>
| Prop | 타입 | 기본값 | 설명 |
|---|---|---|---|
value | string | — | 항목 식별자(고유). |
className | string | — | 추가 CSS 클래스 — 항목 루트에 합성. |
<Accordion.Trigger> — 네이티브 button 속성 확장
| Prop | 타입 | 기본값 | 설명 |
|---|---|---|---|
children | ReactNode | — | 헤더 레이블 — h3 > button 안에 렌더 |
<Accordion.Content>
| Prop | 타입 | 기본값 | 설명 |
|---|---|---|---|
children | ReactNode | — | 패널 본문 |
className | string | — | 클래스 합성 |
접근성#
| 계약 | 구현 |
|---|---|
| 헤더 구조 | h3 > button — 문서 아웃라인에 헤딩으로 노출 |
| 펼침 상태 | 버튼 aria-expanded + 셰브론 회전 표시 |
| 패널 | role="region" + aria-labelledby(헤더 버튼, useId 기반) |
| 연결 | 버튼 aria-controls → 패널 id |
| 키보드 | Tab으로 헤더 이동, Enter·Space 토글 (네이티브 button) |
| 접힘 | hidden 토글 — 접힌 내용은 탭 순서·접근성 트리에서 제외 |
| 모션 | 펼침은 opacity/transform만(레이아웃 속성 애니 금지) + prefers-reduced-motion 존중 |
토큰#
component 토큰 없이 semantic을 직접 소비합니다(신설 기준 §4 미충족).
| 속성 | 토큰 |
|---|---|
| 컨테이너/구분선 | color.border · radius.lg |
| 트리거 | color.text · hover color.surface-hover · 눌림 color.surface-pressed |
| 셰브론/본문 | color.text-muted |
| 포커스 링 | color.focus-ring |
| 타이포 | font.sans · font-size.body-1/body-2 · font-weight.medium · line-height.tight/normal |
| 간격 | space.2/4/6 |
| 모션 | duration.fast · ease.standard / ease.out |