Accordion

접었다 펴는 목록이다. 항목은 index 로 식별하고 Head 와 Panel 이 같은 index 를 공유해 연결된다.

import { Accordion } from "@nui-kit/react";
// 서브패스로 좁힐 때
import { Accordion } from "@nui-kit/react/accordion";
import "@nui-kit/react/styles/accordion.css";   // 온디맨드일 때

import { Accordion } from "@nui-kit/react";

<Accordion type="single">
  <Accordion.Item index={0}>
    <Accordion.Head buttonIndex={0}>제목</Accordion.Head>
    <Accordion.Panel index={0}>내용</Accordion.Panel>
  </Accordion.Item>
</Accordion>

// ✅ 모드 A — 헤더 전체가 버튼
<Accordion.Button index={0}>
  <Accordion.Head>제목</Accordion.Head>
</Accordion.Button>

// ✅ 모드 B — 화살표 아이콘만 버튼
//    헤더에 체크박스 등 다른 조작 요소가 있을 때
<Accordion.Head buttonIndex={0}>제목</Accordion.Head>

// ❌ 둘을 겹치면 button 안에 button
<Accordion.Button index={0}>
  <Accordion.Head buttonIndex={0}>제목</Accordion.Head>
</Accordion.Button>

단일 · 다중

type="single" 은 하나만 열리고, 기본값 "multiple" 은 여러 개를 동시에 열 수 있다.

<Accordion type="single" defaultActiveIndices={[0]}>…</Accordion>

<Accordion type="multiple">…</Accordion>

토글 영역 — 두 가지 모드

헤더 전체를 버튼으로 만들지, 화살표 아이콘만 버튼으로 만들지 고른다. 헤더 안에 체크박스처럼 다른 조작 요소를 둔다면 반드시 아이콘만 버튼으로 해야 한다 — 버튼 안에 버튼을 넣을 수 없기 때문이다.

<Accordion.Button index={0}>
  <Accordion.Head>제목</Accordion.Head>
</Accordion.Button>

<Accordion.Head buttonIndex={0}>제목</Accordion.Head>

변형

<Accordion variant="line" type="single">…</Accordion>

비활성

Accordion.Button 에 disabled 를 준다. 배경이 없는 버튼이라 글자와 화살표 색만 바뀐다.

<Accordion.Button index={1} disabled>…</Accordion.Button>

제어 모드

activeIndices 를 주면 열림 상태를 소비자가 소유한다.

<Accordion activeIndices={indices} onChange={setIndices}>…</Accordion>

내용을 DOM 에 남기기

shouldKeepMounted 를 주면 닫혀도 패널이 DOM 에 남는다. 폼 입력값을 잃지 않아야 하거나, 브라우저 검색(Ctrl+F)에 걸려야 할 때 쓴다.

<Accordion shouldKeepMounted type="single">…</Accordion>

접근성

• 토글 버튼에 aria-expanded 와 aria-controls 가 붙는다
• 패널은 role="region" + aria-labelledby 로 자기 버튼과 연결된다
• Head 에 제목이 있으면 그것이 버튼의 접근 이름이 된다 (aria-labelledby). 없으면 대체 텍스트를 붙인다
• 패널이 DOM 에 없을 때는 aria-controls 를 생략한다 — 존재하지 않는 id 를 가리키지 않도록
• prefers-reduced-motion 에서 펼침 애니메이션이 꺼진다

커스터마이징

색은 컴포넌트별로 열지 않는다. 한 곳만 바꾸려면 className 을, 화면 전체를 바꾸려면 브랜드 프리셋을 쓴다.

API

Accordion

AccordionProps 에서 자동 생성됨 (components/Accordion/Accordion.tsx).

Accordion.Item

AccordionItemProps 에서 자동 생성됨 (components/Accordion/AccordionItem.tsx). 표준 DOM 속성 277개는 그대로 전달되며 표에서 생략했다.

Accordion.Head

AccordionHeadProps 에서 자동 생성됨 (components/Accordion/AccordionHead.tsx). 표준 DOM 속성 277개는 그대로 전달되며 표에서 생략했다.

Accordion.Button

AccordionButtonProps 에서 자동 생성됨 (components/Accordion/AccordionButton.tsx). 표준 DOM 속성 285개는 그대로 전달되며 표에서 생략했다.

Accordion.Panel

AccordionPanelProps 에서 자동 생성됨 (components/Accordion/AccordionPanel.tsx).