Accordion

콘텐츠를 접었다 펼 수 있는 아코디언 컴포넌트입니다.

기본 사용법 (Basic Usage)#

// 기본 아코디언
Accordion(
  items: [
    AccordionItem(
      title: '섹션 1',
      content: Text('섹션 1의 내용입니다.'),
    ),
    AccordionItem(
      title: '섹션 2',
      content: Text('섹션 2의 내용입니다.'),
    ),
    AccordionItem(
      title: '섹션 3',
      content: Text('섹션 3의 내용입니다.'),
    ),
  ],
)

// 다중 열기 허용
Accordion(
  allowMultiple: true,
  items: accordionItems,
)

// 초기 열림 상태 — 항목별 expanded
Accordion(
  items: [
    AccordionItem(
      title: '기본 정보',
      content: Text('기본 정보 내용입니다.'),
      expanded: true,
    ),
    AccordionItem(
      title: '추가 정보',
      content: Text('추가 정보 내용입니다.'),
    ),
  ],
)

// 기본 아코디언
Accordion(
  items: [
    AccordionItem(
      title: '섹션 1',
      content: Text('섹션 1의 내용입니다.'),
    ),
    AccordionItem(
      title: '섹션 2',
      content: Text('섹션 2의 내용입니다.'),
    ),
    AccordionItem(
      title: '섹션 3',
      content: Text('섹션 3의 내용입니다.'),
    ),
  ],
)

// 다중 열기 허용
Accordion(
  allowMultiple: true,
  items: accordionItems,
)

// 초기 열림 상태 — 항목별 expanded
Accordion(
  items: [
    AccordionItem(
      title: '기본 정보',
      content: Text('기본 정보 내용입니다.'),
      expanded: true,
    ),
    AccordionItem(
      title: '추가 정보',
      content: Text('추가 정보 내용입니다.'),
    ),
  ],
)

Live Preview#

class AccordionDefaultExample extends StatelessComponent {
  const AccordionDefaultExample({super.key});

  @override
  Component build(BuildContext context) {
    return Accordion(
      items: [
        AccordionItem(
          title: 'Is it accessible?',
          content: Text('Yes. It adheres to the WAI-ARIA design pattern.'),
          expanded: true,
        ),
        AccordionItem(
          title: 'Is it styled?',
          content: Text('Yes. It comes with default styles that matches the other components.'),
        ),
        AccordionItem(
          title: 'Is it animated?',
          content: Text('Yes. It\'s animated by default, but you can disable it if you prefer.'),
        ),
      ],
    );
  }
}

class AccordionDefaultExample extends StatelessWidget {
  const AccordionDefaultExample({super.key});

  @override
  Widget build(BuildContext context) {
    return const Accordion(
      items: [
        AccordionItem(
          title: 'Is it accessible?',
          content: Text('Yes. It adheres to the WAI-ARIA design pattern.'),
          expanded: true,
        ),
        AccordionItem(
          title: 'Is it styled?',
          content: Text(
            'Yes. It comes with default styles that matches the other components.',
          ),
        ),
        AccordionItem(
          title: 'Is it animated?',
          content: Text(
            "Yes. It's animated by default, but you can disable it if you prefer.",
          ),
        ),
      ],
    );
  }
}

사용 시기 (When to Use)#

이 컴포넌트를 사용하세요:

• FAQ, 도움말 등 질문-답변 형태의 콘텐츠를 표시할 때
• 긴 내용을 섹션별로 접어서 공간을 절약할 때
• 설정 패널의 카테고리별 옵션을 그룹화할 때

대신 다른 컴포넌트를 사용하세요:

• Tree: 고정 콘텐츠 섹션이 아니라 데이터의 부모·자식 가지를 탐색해야 할 때
• Collapsible: 항목 목록의 상호배타 열림 없이, 한 영역의 expanded 를 호출부에서 제어해야 할 때
• Disclosure: 트리거 · 요약 · 추가 내용 슬롯을 갖는 독립적인 정보 공개가 필요할 때
• Tabs: 펼침 목록이 아니라 선택된 패널 하나만 교체해야 할 때
• Dialog / Drawer: 본문 흐름 안의 접힘 영역이 아니라 오버레이가 필요할 때

Props / Parameters#

Accordion 파라미터#

AccordionItem#

W 는 Flutter의 Widget, Web의 Jaspr Component 입니다. 슬롯의 의미와 필수 여부는 공통입니다.

AccordionTrigger (Flutter)#

스타일 시스템 (Style System)#

Accordion 의 모든 chrome / dimensional / nested-slot 오버라이드는 CoreAccordionStyle 단일 슬롯으로 흐릅니다. 시맨틱 enum / behaviour (items / allowMultiple) 는 위젯 파라미터로 직접 전달합니다.

시맨틱 vs 스타일#

• 시맨틱 enum / behaviour: 위젯/컴포넌트 파라미터로 직접 (items, allowMultiple)
• chrome / dimensional / 슬롯 스타일: CoreAccordionStyle 한 곳으로 (backgroundColor / borderColor / borderWidth / borderRadius / contentPadding / itemSpacing / dividerColor / dividerThickness / duration / arrowIconStyle / triggerStyle / contentTextStyle / chevronIconStyle / iconGapStyle / clickableStyle)

Resolve chain#

design system default for accordion
  → CoreAccordionTheme.style                   // 프로젝트 공통
  → parent component slot override
  → widget.accordionStyle                      // 인스턴스별

각 nested 슬롯 스타일 (triggerStyle / contentTextStyle / chevronIconStyle) 은 자기 컴포넌트의 자체 resolve chain 으로 다시 한 번 머지됩니다.

CoreAccordionStyle 필드#

사용 예 (Flutter)#

Accordion(
  items: [
    AccordionItem(
      title: 'FAQ Question',
      content: Text('Answer'),
    ),
  ],
  accordionStyle: CoreAccordionStyle(
    contentPadding: CoreEdgeInsets.symmetric(vertical: CoreSpace.space24),
    dividerColor: CoreColor.token(CoreColors.outlineVariant),
    dividerThickness: CoreStrokeWidth.stroke1,
    triggerStyle: CoreButtonStyle(
      padding: CoreEdgeInsets.symmetric(vertical: CoreSpace.space16),
      labelStyle: CoreTextStyle.token(CoreTextStyles.bodyLarge),
    ),
    contentTextStyle: CoreTextStyle.token(CoreTextStyles.bodySmall),
    chevronIconStyle: CoreIconStyle(size: CoreIconSize.size20),
  ),
)

사용 예 (Web)#

Accordion(
  items: [
    AccordionItem(
      title: 'FAQ Question',
      content: Text('Answer'),
    ),
  ],
  accordionStyle: CoreAccordionStyle(
    contentPadding: CoreEdgeInsets.symmetric(vertical: CoreSpace.space24),
    dividerThickness: CoreStrokeWidth.stroke1,
    triggerStyle: CoreButtonStyle(
      padding: CoreEdgeInsets.symmetric(vertical: CoreSpace.space16),
    ),
  ),
)

빠른 오버라이드 (Chain)#

이미 만든 Accordion 인스턴스에 스타일을 빠르게 덧붙이고 싶다면 withStyle 체인을 쓸 수 있습니다. 생성자의 style 슬롯 인자와 동일하게 동작하지만, 이미 구성된 위젯 위에서 바로 이어 쓸 수 있습니다. .radius4처럼 Core 토큰 상수 이름과 똑같은 이름의 getter도 있습니다 — withStyle을 한 번 더 줄인 sugar로, 이름이 곧 값이라(radius4 == CoreRadius.radius4) 어느 컴포넌트에서 써도 뜻이 갈리지 않습니다.

class AccordionChainExample extends StatelessWidget {
  const AccordionChainExample({super.key});

  @override
  Widget build(BuildContext context) {
    return Column(
      mainAxisSize: MainAxisSize.min,
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        // 토큰-정확 getter combo — 이름이 곧 값 (getter 이름 = Core 토큰 상수 1:1).
        const Accordion(
          items: [
            AccordionItem(
              title: 'Is it accessible?',
              content: Text('Yes. It adheres to the WAI-ARIA design pattern.'),
              expanded: true,
            ),
            AccordionItem(
              title: 'Is it styled?',
              content: Text(
                'Yes. It comes with default styles that matches the other components.',
              ),
            ),
            AccordionItem(
              title: 'Is it animated?',
              content: Text(
                "Yes. It's animated by default, but you can disable it if you prefer.",
              ),
            ),
          ],
        ).radius16.primary,
        const Gap.space12(),
        // withStyle full-control — getter 가 없는 필드(borderColor/borderWidth)까지.
        const Accordion(
          items: [
            AccordionItem(
              title: 'Is it accessible?',
              content: Text('Yes. It adheres to the WAI-ARIA design pattern.'),
              expanded: true,
            ),
            AccordionItem(
              title: 'Is it styled?',
              content: Text(
                'Yes. It comes with default styles that matches the other components.',
              ),
            ),
            AccordionItem(
              title: 'Is it animated?',
              content: Text(
                "Yes. It's animated by default, but you can disable it if you prefer.",
              ),
            ),
          ],
        ).withStyle(
          const CoreAccordionStyle(
            backgroundColor: CoreColor.token(
              CoreColors.surfaceContainerHighest,
            ),
            borderColor: CoreColor.token(CoreColors.tertiary),
            borderWidth: CoreStrokeWidth.stroke2,
            borderRadius: CoreBorderRadius.all(CoreRadius.radius24),
          ),
        ),
      ],
    );
  }
}

class AccordionChainExample extends StatelessComponent {
  const AccordionChainExample({super.key});

  @override
  Component build(BuildContext context) {
    return div(
      [
        // 토큰-정확 getter combo — 이름이 곧 값 (getter 이름 = Core 토큰 상수 1:1).
        Accordion(
          items: [
            AccordionItem(
              title: 'Is it accessible?',
              content: Text('Yes. It adheres to the WAI-ARIA design pattern.'),
              expanded: true,
            ),
            AccordionItem(
              title: 'Is it styled?',
              content: Text(
                'Yes. It comes with default styles that matches the other components.',
              ),
            ),
            AccordionItem(
              title: 'Is it animated?',
              content: Text(
                'Yes. It\'s animated by default, but you can disable it if you prefer.',
              ),
            ),
          ],
        ).radius16.primary,
        const Gap.space12(),
        // withStyle full-control — getter 가 없는 필드(borderColor/borderWidth)까지.
        Accordion(
          items: [
            AccordionItem(
              title: 'Is it accessible?',
              content: Text('Yes. It adheres to the WAI-ARIA design pattern.'),
              expanded: true,
            ),
            AccordionItem(
              title: 'Is it styled?',
              content: Text(
                'Yes. It comes with default styles that matches the other components.',
              ),
            ),
            AccordionItem(
              title: 'Is it animated?',
              content: Text(
                'Yes. It\'s animated by default, but you can disable it if you prefer.',
              ),
            ),
          ],
        ).withStyle(
          const CoreAccordionStyle(
            backgroundColor: CoreColor.token(
              CoreColors.surfaceContainerHighest,
            ),
            borderColor: CoreColor.token(CoreColors.tertiary),
            borderWidth: CoreStrokeWidth.stroke2,
            borderRadius: CoreBorderRadius.all(CoreRadius.radius24),
          ),
        ),
      ],
      classes: 'flex flex-col items-start',
    );
  }
}

변형 (Variants)#

아이콘 포함 (커스텀 트리거)#

title 은 문자열 전용이라, 헤더에 아이콘을 넣으려면 trigger 슬롯에 직접 조립합니다. Flutter 는 AccordionTrigger 로 감싸면 토글·포커스·chevron 이 그대로 따라오고, Web 의 trigger 는 임의 Component 라 필요한 인터랙션을 직접 붙입니다.

// Flutter
AccordionItem(
  trigger: AccordionTrigger(
    child: Row(
      children: [
        Icon(LucideIcons.user),
        Gap(gapStyle: CoreGapStyle(size: CoreSpace.space8)),
        Text('개인 정보').bodyMedium.onSurface,
      ],
    ),
  ),
  content: PersonalInfoForm(),
)

FAQ 스타일#

Accordion(
  items: faqList.map((faq) => AccordionItem(
    title: faq.question,
    content: Text(faq.answer),
  )).toList(),
)

단일 항목 (접기/펼치기)#

AccordionItem(
  title: '고급 설정',
  expanded: false,
  content: AdvancedSettingsPanel(),
)

동작 스펙 (Behavior)#

열기/닫기#

• 헤더 클릭 시 해당 섹션이 슬라이드 애니메이션으로 펼쳐짐/접힘
• allowMultiple: false (기본): 하나를 열면 이전에 열린 항목이 자동으로 닫힘
• allowMultiple: true: 여러 항목을 동시에 열 수 있음
• expanded 는 항목을 만들 때의 초기값입니다. 열림은 컴포넌트 내부에서 관리하며 외부 제어 값 · 변경 콜백 · 비활성 플래그는 없습니다. 초기값으로 여러 항목을 열 때는 단일 열림 모드가 초기 상태를 정규화한다고 기대하지 마세요.

애니메이션#

• 기본 CoreDuration.normal (200ms), easeInOut 커브
• 시간은 accordionStyle.duration 으로 조정합니다 (프로젝트 공통은 CoreAccordionTheme.style.duration)

Accordion(
  items: accordionItems,
  accordionStyle: CoreAccordionStyle(
    duration: Duration(milliseconds: CoreDuration.moderate),
  ),
)

화살표 아이콘#

• 헤더 우측의 chevron 아이콘이 열림/닫힘 방향을 표시 (180° 회전 트랜지션)
• 크기·색은 accordionStyle.chevronIconStyle (기본값은 arrowIconStyle) 로 조정합니다
• 아이콘 글리프 자체를 바꾸려면 trigger 슬롯에 헤더를 직접 조립합니다

사용 가이드라인 (Usage Guidelines)#

✅ Do#

Accordion(
  items: faqList.map((faq) => AccordionItem(
    title: faq.question,
    content: Text(faq.answer),
  )).toList(),
)

❌ Don't#

Accordion(items: [
  AccordionItem(
    title: '결제 정보',
    content: PaymentForm(), // 반드시 입력해야 하는 폼
  ),
])

✅ Do#

Accordion(
  items: categories.map((cat) => AccordionItem(
    title: cat.name,
    content: cat.settingsPanel,
  )).toList(),
)

❌ Don't#

Accordion(items: [
  AccordionItem(title: '유일한 섹션', content: onlySection),
])

접근성 (Accessibility)#

역할#

• Flutter — 헤더는 Clickable 합성이라 Semantics(button: true, enabled: …) 를 받고(clickable.dart:505), 그 위를 CoUISemantics(expanded: …) 가 감싸 펼침 상태를 얹습니다(accordion.dart:488). Accordion 루트와 항목 래퍼에는 role 이 없습니다.
• Web — 헤더는 Clickable 의 <div> 라 role="button" + tabindex="0" 이 붙고(clickable.dart:436), 그 위에 aria-expanded 가 caller attributes 로 실립니다(accordion.dart:363). 루트 <div> 는 configureAttributes 를 override 하지 않아 호출자가 넘긴 attributes 외에는 아무 role 도 붙지 않습니다.

양 플랫폼 모두 헤더와 패널을 잇는 aria-controls 도, 패널의 region role 도, 헤딩 레벨도 내보내지 않습니다 — 리더의 heading 목록에 아코디언 헤더는 잡히지 않습니다.

키보드#

컴포넌트가 바인딩하는 키는 Enter / Space 뿐입니다(clickable.dart:14). WAI-ARIA 아코디언 패턴이 선택 사항으로 두는 헤더 간 화살표·Home/End 이동은 구현돼 있지 않습니다.

Flutter 에서 화살표로 포커스가 움직이는 것은 프레임워크의 방향성 순회이지 아코디언의 동작이 아닙니다 — 아코디언에 스코프되지 않고, Flutter Web 에서는 같은 키가 스크롤로 갑니다.

스크린 리더#

접근 가능한 이름은 title 문자열이 그대로 헤더 텍스트가 되어 나옵니다(Flutter accordion.dart:324, Web accordion.dart:402). trigger 슬롯을 채우면 이름은 그 안에 넣은 콘텐츠에서 옵니다.

펼침 상태는 헤더에 실려 함께 읽히지만, 여닫은 결과를 알리는 live region 은 양쪽 다 없습니다 — 사용자는 헤더로 되돌아와 상태를 다시 들어야 합니다.

접힌 패널은 리더에 노출되지 않습니다. Flutter 는 높이 0 으로 클립되어 시맨틱 트리에 올라가지 않고, Web 은 inert 로 접근성 트리·탭 순서·hit-test 에서 함께 빠집니다(accordion.dart:439).

항목 사이 구분선은 Divider 기본값(semantic: false)이라 리더에 아무것도 읽히지 않습니다(Flutter divider.dart:51, Web divider.dart:76).

포커스 관리#

• 진입 / 이탈 — 없음. 오버레이가 아니라 인라인 섹션이라 열고 닫을 때 포커스를 옮기지 않습니다.
• 트랩 — 없음. Tab 은 아코디언 밖으로 그대로 빠져나갑니다.
• 펼친 패널 안의 포커스 가능 요소는 탭 순서에 들어오고, 접으면 빠집니다. Flutter 는 닫힘 애니메이션이 끝난 시점(_controller.isDismissed)에 ExcludeFocus 로 제외하고(accordion.dart:351), Web 은 상태가 뒤집히는 즉시 inert 를 붙입니다(accordion.dart:439).
• 패널 안에 포커스가 있는 채로 접으면 포커스를 헤더로 되돌리는 코드가 없습니다.

알려진 제약#

• Web 에서 trigger 슬롯을 채우면 그 헤더는 동작하지 않습니다 — 커스텀 트리거는 그대로 렌더될 뿐 토글 배선도 aria-expanded 도 붙지 않고(accordion.dart:402), 펼침 상태는 부모 Accordion 이 인덱스로 들고 있어 호출자가 밖에서 바꿀 수도 없습니다. Web 에서는 title 을 쓰세요. Flutter 는 AccordionTrigger 로 감싸면 토글·포커스·펼침 상태가 그대로 따라옵니다(accordion.dart:324).
• 헤더와 패널에 속성을 실을 진입점이 없습니다 — Web AccordionItem(attributes: …) 는 항목 래퍼 <div> 에만 닿고(accordion.dart:445) 헤더(Clickable)와 패널에는 caller 표면이 없으며, Flutter AccordionItem 에는 그런 표면 자체가 없습니다. 위에서 말한 aria-controls / 헤딩 레벨을 소비자가 밖에서 보강할 수 없다는 뜻입니다.

전역 축(동작 줄이기 · 고대비 · 색 강제 모드 · 시맨틱 역할 · 최소 터치 타겟)은 접근성 페이지가 한 곳에서 다룹니다.

크로스 플랫폼 차이점 (Platform Differences)#

관련 컴포넌트 (Related Components)#

• Tabs: 콘텐츠를 탭으로 전환. 아코디언과 달리 한 번에 하나의 패널만 표시
• Card: 콘텐츠 컨테이너. 아코디언 항목 내부에 카드를 배치 가능

조합 예제#

// 설정 페이지 패턴
Accordion(
  allowMultiple: true,
  items: [
    AccordionItem(
      title: '프로필 설정',
      content: ProfileSettingsForm(),
    ),
    AccordionItem(
      title: '알림 설정',
      content: NotificationSettingsForm(),
    ),
    AccordionItem(
      title: '보안 설정',
      content: SecuritySettingsForm(),
    ),
  ],
)