Get StartedFoundationsComponentsPatternsRulesDevelopAI & ToolsUpdates

Accordion

여러 개의 관련된 콘텐츠 섹션을 수직으로 나열하고, 각 섹션을 펼치거나 접어 정보를 탐색할 수 있는 컴포넌트예요.

설치

pnpm dlx shadcn@latest add https://rebar.conmarket-landing.workers.dev/r/accordion.json

Anatomy

Accordion은 Trigger(Prefix, Title, Description, Chevron Icon)와 확장 시 나타나는 Custom Content로 구성돼요.

  • Trigger: 사용자가 눌러서 콘텐츠를 열고 닫는 영역이에요. Prefix, Title, Description, Chevron Icon을 포함해요.
  • Content: 열림/닫힘 애니메이션 컨테이너예요. 패딩, 배경, 타이포그래피는 제공하지 않으므로 내부 콘텐츠에서 직접 구성해요.

Properties

Open

Accordion은 두 가지 시각적 상태를 가져요.

  • Collapsed: 헤더만 노출되고 Content Panel이 숨겨진 상태예요. Chevron Icon이 아래 방향을 가리켜요.
  • Expanded: 헤더 아래에 Content Panel이 펼쳐진 상태예요. Chevron Icon이 위 방향을 가리켜요.

기본적으로 모든 패널은 Collapsed 상태로 시작해서, 사용자에게 콘텐츠의 전체적인 개요를 먼저 보여줘요. defaultValues 로 처음 열려 있을 항목을 지정할 수 있어요.

Size

모바일과 PC를 하나의 컴포넌트로 대응하기 위한 속성이에요. 사이즈에 따라 Padding, Font Size, Chevron Icon Size가 달라져요. 기본값은 Medium이에요.

  • Medium: 모바일 기본 사이즈예요.
  • Large: PC 대응 사이즈예요.
  • Responsive: 화면 너비가 md 미만이면 Medium, md 이상이면 Large로 자동 전환돼요.

Large 사이즈는 PC 환경에서 뷰포트 너비가 바뀌어도 폰트 사이즈가 동일하게 유지돼요.

Variant

Accordion Item들의 시각적 배치 방식을 정의해요. 콘텐츠의 성격과 레이아웃에 맞는 Variant를 골라요.

  • Inline: 아이템들이 하나의 연속된 목록처럼 표현되고, 사이에 구분선이 보여요. 밀접하게 관련된 항목을 컴팩트하게 나열할 때 사용해요.
  • Separated: 각 아이템이 개별 카드 형태로 분리돼요. 항목 간 시각적 독립성이 필요하거나 각 섹션의 중요도가 동등할 때 사용해요.

State

Enabled, Pressed, Disabled 상태를 제공해요. Accordion 에 disabled 를 지정하면 모든 항목이, AccordionItem 에 지정하면 해당 항목만 비활성화돼요.

Prefix

Prefix 슬롯은 Trigger 좌측에 위치해요. 아이콘 외에 다른 요소도 넣을 수 있고, 요소에 따라 Trigger와의 간격은 디자인 시스템의 spacing 토큰으로 조절해요.

Description

description 으로 트리거에 부가 설명을 추가할 수 있어요.

Guidelines

Accordion 기본 사용하기

Accordion은 관련 정보를 그룹화하거나, 긴 페이지의 스크롤을 줄여야 할 때 사용해요.

Item 최소 개수

Accordion은 여러 섹션을 접고 펼치며 탐색하는 컴포넌트이므로, 최소 2개 이상의 Item으로 구성해요. 단일 콘텐츠를 접고 펼치는 용도라면 Collapsible 동작을 활용해요.

배송 안내환불 안내
Do· 2개 이상의 Item

관련된 섹션 여러 개를 함께 나열해요.

배송 안내
Don't· 단일 Item

Accordion Item을 하나만 사용하지 않아요.

터치 영역

터치 영역은 Chevron 아이콘뿐만 아니라 Trigger 전체를 포함해요.

Expansion Behavior

동작설명사용처
Single Expand한 번에 하나의 패널만 열 수 있어요. 다른 패널을 열면 기존 패널이 자동으로 닫혀요.단계별 프로세스, 작은 화면 혹은 영역
Multi Expand여러 패널을 동시에 열 수 있어요. 각 패널의 상태가 독립적으로 관리돼요. (multiple)FAQ, 콘텐츠가 풍부한 경우

확장 시 자동 스크롤 / 포커스 이동

자동 스크롤과 포커스 이동은 기본으로 지원하지 않아요. 다만 Accordion 콘텐츠가 뷰포트보다 길어지면 전체 Accordion이 페이지 수준에서 수직으로 스크롤되어야 해요.

Content Panel 내 스크롤 지양

Content Panel 내부에서의 개별 스크롤은 지양해요. 콘텐츠가 길면 Accordion 전체를 포함하는 페이지 수준에서 수직 스크롤을 허용해요.

긴 안내 문구가 이어져요.페이지와 함께 스크롤돼요.끝까지 다 보여요.
Do· 페이지 수준 스크롤

콘텐츠를 모두 펼쳐 보여주고 페이지가 스크롤되게 해요.

긴 안내 문구가 이어져요.패널 안에서만 스크롤돼요.잘려서 보여요.
Don't· 패널 내부 스크롤

Content Panel 안에 고정 높이와 스크롤을 두지 않아요.

접근성

WAI-ARIA Accordion Pattern을 따라요. AccordionTrigger 는 heading > button 구조로 렌더링되고 기본 heading level은 h3 이에요. 상위 섹션 구조에 맞게 headingLevel 로 조정해요.

키동작
Enter / Space포커스된 트리거의 패널을 펼치거나 접어요.
Tab / Shift + Tab다음 / 이전 포커스 가능한 요소로 이동해요.
ArrowDown / ArrowUp다음 / 이전 트리거로 포커스를 이동해요.
Home / End첫 번째 / 마지막 트리거로 포커스를 이동해요.

Props

Accordion

Prop

Type

AccordionItem

Prop

Type

AccordionTrigger

Prop

Type

On this page