Accordion

세로로 쌓인 상호작용 가능한 제목 목록으로, 각 제목이 연관된 콘텐츠 섹션을 펼쳐 보여 주는 컴포넌트예요.

출처: 문서

본문

아코디언은 각 항목이 접혀 있다가 제목을 클릭하면 내용을 펼쳐 보여주는 UI예요. Radix Accordion은 키보드 내비게이션을 완전히 지원하고, 가로/세로 방향과 RTL을 모두 지원하며, 항목 하나 또는 여러 개를 동시에 펼칠 수 있어요.

Features

완전한 키보드 내비게이션 지원.
가로/세로 방향 지원.
오른쪽에서 왼쪽(RTL) 방향 지원.
항목 하나 또는 여러 개를 펼칠 수 있어요.
제어(controlled) 또는 비제어(uncontrolled) 방식 모두 지원.

Anatomy

모든 파트를 임포트해 조립해요.

import { Accordion } from "radix-ui";

export default () => (
  <Accordion.Root>
    <Accordion.Item>
      <Accordion.Header>
        <Accordion.Trigger />
      </Accordion.Header>

      <Accordion.Content />
    </Accordion.Item>
  </Accordion.Root>
);

API Reference

Root

아코디언의 모든 파트를 담아요.

Prop	Type	Default
`asChild`	`boolean`	`false`
`type*`	`enum`	No default value
`value`	`string`	No default value
`defaultValue`	`string`	No default value
`onValueChange`	`function`	No default value
`value`	`string[]`	`[]`
`defaultValue`	`string[]`	`[]`
`onValueChange`	`function`	No default value
`collapsible`	`boolean`	`false`
`disabled`	`boolean`	`false`
`dir`	`enum`	`"ltr"`
`orientation`	`enum`	`"vertical"`

Data attribute	Values
`[data-orientation]`	`"vertical" \| "horizontal"`

Item

접을 수 있는 섹션의 모든 파트를 담아요.

Prop	Type	Default
`asChild`	`boolean`	`false`
`disabled`	`boolean`	`false`
`value*`	`string`	No default value

Data attribute	Values
`[data-state]`	`"open" \| "closed"`
`[data-disabled]`	Present when disabled
`[data-orientation]`	`"vertical" \| "horizontal"`

Accordion.Trigger를 감싸요. asChild prop으로 페이지에 맞는 제목 레벨로 바꿔 쓸 수 있어요.

Prop	Type	Default
`asChild`	`boolean`	`false`

Data attribute	Values
`[data-state]`	`"open" \| "closed"`
`[data-disabled]`	Present when disabled
`[data-orientation]`	`"vertical" \| "horizontal"`

Trigger

연관된 항목의 접힘 상태를 토글해요. Accordion.Header 안에 중첩해서 사용해야 해요.

Prop	Type	Default
`asChild`	`boolean`	`false`

Data attribute	Values
`[data-state]`	`"open" \| "closed"`
`[data-disabled]`	Present when disabled
`[data-orientation]`	`"vertical" \| "horizontal"`

Content

항목의 접을 수 있는 콘텐츠를 담아요.

Prop	Type	Default
`asChild`	`boolean`	`false`
`forceMount`	`boolean`	No default value

Data attribute	Values
`[data-state]`	`"open" \| "closed"`
`[data-disabled]`	Present when disabled
`[data-orientation]`	`"vertical" \| "horizontal"`

CSS Variable	Description
`--radix-accordion-content-width`	The width of the content when it opens/closes
`--radix-accordion-content-height`	The height of the content when it opens/closes

Examples

기본으로 펼쳐진 항목

defaultValue prop으로 기본으로 열려 있는 항목을 지정해요.

<Accordion.Root type="single" defaultValue="item-2">
  <Accordion.Item value="item-1">…</Accordion.Item>

  <Accordion.Item value="item-2">…</Accordion.Item>
</Accordion.Root>

모든 항목 접기 허용

collapsible prop으로 모든 항목이 닫히게 허용해요.

<Accordion.Root type="single" collapsible>
  <Accordion.Item value="item-1">…</Accordion.Item>

  <Accordion.Item value="item-2">…</Accordion.Item>
</Accordion.Root>

여러 항목 동시에 펼치기

type prop을 multiple로 설정하면 여러 항목을 한 번에 열 수 있어요.

<Accordion.Root type="multiple">
  <Accordion.Item value="item-1">…</Accordion.Item>

  <Accordion.Item value="item-2">…</Accordion.Item>
</Accordion.Root>

열렸을 때 아이콘 회전

chevron 같은 장식 요소를 추가하고, 항목이 열렸을 때 회전시키면 돼요.

// index.jsx

import { Accordion } from "radix-ui";

import { ChevronDownIcon } from "@radix-ui/react-icons";

import "./styles.css";

export default () => (
  <Accordion.Root type="single">
    <Accordion.Item value="item-1">
      <Accordion.Header>
        <Accordion.Trigger className="AccordionTrigger">
          <span>Trigger text</span>

          <ChevronDownIcon className="AccordionChevron" aria-hidden />
        </Accordion.Trigger>
      </Accordion.Header>

      <Accordion.Content>…</Accordion.Content>
    </Accordion.Item>
  </Accordion.Root>
);

/* styles.css */

.AccordionChevron {
  transition: transform 300ms;
}

.AccordionTrigger[data-state="open"] > .AccordionChevron {
  transform: rotate(180deg);
}

가로 방향

orientation prop으로 가로 아코디언을 만들 수 있어요.

<Accordion.Root orientation="horizontal">
  <Accordion.Item value="item-1">…</Accordion.Item>

  <Accordion.Item value="item-2">…</Accordion.Item>
</Accordion.Root>

콘텐츠 크기 애니메이션

--radix-accordion-content-width/--radix-accordion-content-height CSS 변수로 콘텐츠가 열리고 닫힐 때 크기를 애니메이션할 수 있어요.

// index.jsx

import { Accordion } from "radix-ui";

import "./styles.css";

export default () => (
  <Accordion.Root type="single">
    <Accordion.Item value="item-1">
      <Accordion.Header>…</Accordion.Header>

      <Accordion.Content className="AccordionContent">…</Accordion.Content>
    </Accordion.Item>
  </Accordion.Root>
);

/* styles.css */

.AccordionContent {
  overflow: hidden;
}

.AccordionContent[data-state="open"] {
  animation: slideDown 300ms ease-out;
}

.AccordionContent[data-state="closed"] {
  animation: slideUp 300ms ease-out;
}

@keyframes slideDown {
  from {
    height: 0;
  }

  to {
    height: var(--radix-accordion-content-height);
  }
}

@keyframes slideUp {
  from {
    height: var(--radix-accordion-content-height);
  }

  to {
    height: 0;
  }
}

Accessibility

Accordion WAI-ARIA 디자인 패턴을 준수해요.

키보드 상호작용

Key	Description
`Space`	When focus is on an `Accordion.Trigger` of a collapsed section, expands the section.
`Enter`	When focus is on an `Accordion.Trigger` of a collapsed section, expands the section.
`Tab`	Moves focus to the next focusable element.
`Shift + Tab`	Moves focus to the previous focusable element.
`ArrowDown`	Moves focus to the next `Accordion.Trigger` when `orientation` is `vertical`.
`ArrowUp`	Moves focus to the previous `Accordion.Trigger` when `orientation` is `vertical`.
`ArrowRight`	Moves focus to the next `Accordion.Trigger` when `orientation` is `horizontal`.
`ArrowLeft`	Moves focus to the previous `Accordion.Trigger` when `orientation` is `horizontal`.
`Home`	When focus is on an `Accordion.Trigger`, moves focus to the first `Accordion.Trigger`.
`End`	When focus is on an `Accordion.Trigger`, moves focus to the last `Accordion.Trigger`.

더 알아보기 (Learn more)

type="single"이면 하나만, type="multiple"이면 여러 항목을 동시에 펼칠 수 있어요.
접힘/펼침 애니메이션은 Radix가 제공하는 content-width/content-height CSS 변수를 활용하면 부드럽게 구현할 수 있어요.