Breadcrumb#

현재 페이지의 위치를 계층적으로 표시하여 사용자가 상위 페이지로 쉽게 이동할 수 있도록 하는 탐색 경로 컴포넌트입니다.

Live Preview#

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

  @override
  Component build(BuildContext context) {
    return Breadcrumb(
      items: const [
        CoreBreadcrumbItem(label: 'Home', href: '/'),
        CoreBreadcrumbItem(label: 'Components', href: '/components'),
        CoreBreadcrumbItem(label: 'Breadcrumb'),
      ],
      onItemTap: (index) {},
    );
  }
}

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

  @override
  Widget build(BuildContext context) {
    return Breadcrumb(
      items: const [
        CoreBreadcrumbItem(label: 'Home', href: '/'),
        CoreBreadcrumbItem(label: 'Components', href: '/components'),
        CoreBreadcrumbItem(label: 'Breadcrumb'),
      ],
      onItemTap: (index) {},
    );
  }
}

사용 시기 (When to Use)#

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

• 3단계 이상의 계층 구조를 가진 페이지에서 현재 위치를 안내할 때
• 사용자가 상위 카테고리로 빠르게 돌아갈 수 있어야 할 때 (예: 이커머스 카테고리, 관리자 설정)
• 문서, 파일 탐색기처럼 깊은 계층 구조를 탐색할 때

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

• Tabs: 동일 레벨의 섹션을 전환할 때
• Navigation: 앱 주요 섹션 간 이동에는 네비게이션 사용
• Link: 단순 이전 페이지 이동 링크만 필요할 때

기본 사용법 (Basic Usage)#

Flutter / Web 모두 동일한 Breadcrumb API 를 사용합니다. 데이터-드리븐 — CoreBreadcrumbItem 리스트를 넘기면 마지막 항목이 자동으로 현재 위치(비탐색) 로 렌더링됩니다.

// 기본 브레드크럼
Breadcrumb(
  items: const [
    CoreBreadcrumbItem(label: '홈', href: '/'),
    CoreBreadcrumbItem(label: '카테고리', href: '/category'),
    CoreBreadcrumbItem(label: '상품 상세'),
  ],
  onItemTap: handleBreadcrumbNavigation,
)

// 기본 브레드크럼 (href로 <a> 링크 렌더링)
Breadcrumb(
  items: const [
    CoreBreadcrumbItem(label: '홈', href: '/'),
    CoreBreadcrumbItem(label: '카테고리', href: '/category'),
    CoreBreadcrumbItem(label: '상품 상세'),
  ],
  onItemTap: handleBreadcrumbNavigation,
)

Props / Parameters#

CoreBreadcrumbItem 은 label (필수) 과 href (선택) 를 가집니다. Web 에서는 href 가 <a> 태그로 렌더링되고, Flutter 에서는 onItemTap 콜백으로 탐색을 처리합니다.

스타일 시스템 (Style System)#

Breadcrumb 의 모든 chrome / dimensional / nested-slot 오버라이드는 CoreBreadcrumbStyle 단일 슬롯으로 흐릅니다. 시맨틱 / behaviour 필드 (items / onItemTap / variant) 는 위젯/컴포넌트 파라미터로 직접 전달합니다.

시맨틱 vs 스타일#

• 시맨틱 / behaviour: 위젯/컴포넌트 파라미터로 직접 (items, onItemTap, variant)
• chrome / dimensional / 슬롯 스타일: CoreBreadcrumbStyle 한 곳으로 (itemSeparatorGapStyle / currentItemColor / itemTextStyle / separatorIconStyle)

Resolve chain#

CoreBreadcrumbStyle.defaultX                   // design system default
  → CoreBreadcrumbTheme.style                  // 프로젝트 공통
  → widget.breadcrumbStyle                     // 인스턴스별

슬롯 매핑 (CoreBreadcrumbStyle 4 필드)#

변형 (Variants)#

Breadcrumb 은 현재 단일 시각 변형(standard) 을 가집니다. chevron(›) 구분자가 기본이며, separator 아이콘 크기 / 색은 breadcrumbStyle.separatorIconStyle 로 오버라이드합니다.

Breadcrumb(
  items: const [
    CoreBreadcrumbItem(label: '대시보드', href: '/'),
    CoreBreadcrumbItem(label: '프로젝트', href: '/projects'),
    CoreBreadcrumbItem(label: 'CoUI'),
  ],
  breadcrumbStyle: const CoreBreadcrumbStyle(
    itemSeparatorGapStyle: CoreGapStyle(size: CoreSpace.space12),
  ),
)

동작 스펙 (Behavior)#

인터랙션#

• 클릭/탭: 마지막 외 항목 클릭 시 onItemTap 콜백을 0-based 인덱스와 함께 호출 (마지막 항목은 현재 페이지이므로 비활성)
• 호버: 클릭 가능한 항목 호버 시 텍스트 색이 onSurface 로 전환 (150ms ease-in-out)

상태 전환#

• 마지막 항목은 현재 위치를 나타내며 onSurface 비활성 텍스트로 표시
• 앞 항목들은 onSurfaceVariant 링크 스타일로 표시 (클릭 가능)

애니메이션#

• 링크 호버 시 색상 전환 150ms ease-in-out

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

✅ Do#

Breadcrumb(
  items: const [
    CoreBreadcrumbItem(label: '홈', href: '/'),
    CoreBreadcrumbItem(label: '설정', href: '/settings'),
    CoreBreadcrumbItem(label: '보안'), // 마지막 = 현재 페이지
  ],
  onItemTap: handleNavigation,
)

❌ Don't#

// ❌ 단순 2단계 구조에 브레드크럼
Breadcrumb(
  items: const [
    CoreBreadcrumbItem(label: '홈', href: '/'),
    CoreBreadcrumbItem(label: '설정'),
  ],
)

✅ Do#

접근성 (Accessibility)#

키보드 인터랙션#

스크린 리더#

• Flutter: Semantics(role: 'navigation', label: '탐색 경로') 래핑
• Web: <nav aria-label="breadcrumb"> 자동 적용; 현재 페이지 항목에 aria-current="page" 추가

터치 타겟#

• 클릭 가능한 항목 최소 터치 타겟: 44x44dp
• 작은 구분자는 터치 영역에 포함하지 않음

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

관련 컴포넌트 (Related Components)#

• Navigation: 앱 주요 섹션 간 이동에 사용
• Tabs: 동일 계층의 콘텐츠를 탭으로 전환할 때 사용
• Link: 단일 이전 페이지 이동 링크가 필요할 때 사용