NavigationBar | CoUI
LogoCoUI

NavigationBar

가로 바 / 세로 레일 / 사이드바 세 가지 모드를 지원하는 통합 네비게이션 컨테이너 컴포넌트

NavigationBar#

NavigationBar는 주요 섹션 간 이동을 위한 통합 네비게이션 컨테이너입니다. mode 한 가지로 가로 바(bar), 세로 레일(rail), 확장 사이드바(sidebar) 세 가지 레이아웃을 모두 표현하며, 아이템은 단일 CoreNavigationBarItem 데이터 모델로 구성합니다.

Live Preview#

default
Web
Flutter
Loading Flutter... 
class NavigationBarDefaultExample extends StatefulComponent {
  const NavigationBarDefaultExample({super.key});

  @override
  State<NavigationBarDefaultExample> createState() =>
      _NavigationBarDefaultExampleState();
}

class _NavigationBarDefaultExampleState
    extends State<NavigationBarDefaultExample> {
  int _selectedIndex = 0;

  @override
  Component build(BuildContext context) {
    return NavigationBar(
      mode: CoreNavigationBarMode.bar,
      selectedIndex: _selectedIndex,
      onSelected: (index) => setState(() => _selectedIndex = index),
      labelMode: CoreNavigationLabelMode.all,
      items: const [
        CoreNavigationBarItem.destination(
          icon: Icon(LucideIcons.house),
          label: 'Home',
        ),
        CoreNavigationBarItem.destination(
          icon: Icon(LucideIcons.search),
          label: 'Search',
        ),
        CoreNavigationBarItem.destination(
          icon: Icon(LucideIcons.bell),
          label: 'Alerts',
        ),
        CoreNavigationBarItem.destination(
          icon: Icon(LucideIcons.user),
          label: 'Profile',
        ),
      ],
    );
  }
}
class NavigationBarDefaultExample extends StatefulWidget {
  const NavigationBarDefaultExample({super.key});

  @override
  State<NavigationBarDefaultExample> createState() =>
      _NavigationBarDefaultExampleState();
}

class _NavigationBarDefaultExampleState
    extends State<NavigationBarDefaultExample> {
  int _selectedIndex = 0;

  @override
  Widget build(BuildContext context) {
    return NavigationBar(
      mode: CoreNavigationBarMode.bar,
      selectedIndex: _selectedIndex,
      onSelected: (index) => setState(() => _selectedIndex = index),
      labelMode: CoreNavigationLabelMode.all,
      items: const [
        CoreNavigationBarItem.destination(
          icon: Icon(LucideIcons.house),
          label: 'Home',
        ),
        CoreNavigationBarItem.destination(
          icon: Icon(LucideIcons.search),
          label: 'Search',
        ),
        CoreNavigationBarItem.destination(
          icon: Icon(LucideIcons.bell),
          label: 'Alerts',
        ),
        CoreNavigationBarItem.destination(
          icon: Icon(LucideIcons.user),
          label: 'Profile',
        ),
      ],
    );
  }
}
rail
Web
Flutter
Loading Flutter... 
class NavigationBarRailExample extends StatefulComponent {
  const NavigationBarRailExample({super.key});

  @override
  State<NavigationBarRailExample> createState() =>
      _NavigationBarRailExampleState();
}

class _NavigationBarRailExampleState extends State<NavigationBarRailExample> {
  int _selectedIndex = 0;

  @override
  Component build(BuildContext context) {
    return NavigationBar(
      mode: CoreNavigationBarMode.rail,
      selectedIndex: _selectedIndex,
      onSelected: (index) => setState(() => _selectedIndex = index),
      labelMode: CoreNavigationLabelMode.selected,
      items: const [
        CoreNavigationBarItem.destination(
          icon: Icon(LucideIcons.house),
          label: 'Home',
        ),
        CoreNavigationBarItem.destination(
          icon: Icon(LucideIcons.search),
          label: 'Search',
        ),
        CoreNavigationBarItem.destination(
          icon: Icon(LucideIcons.bell),
          label: 'Alerts',
        ),
        CoreNavigationBarItem.destination(
          icon: Icon(LucideIcons.user),
          label: 'Profile',
        ),
      ],
    );
  }
}
class NavigationBarRailExample extends StatefulWidget {
  const NavigationBarRailExample({super.key});

  @override
  State<NavigationBarRailExample> createState() =>
      _NavigationBarRailExampleState();
}

class _NavigationBarRailExampleState extends State<NavigationBarRailExample> {
  int _selectedIndex = 0;

  @override
  Widget build(BuildContext context) {
    return NavigationBar(
      mode: CoreNavigationBarMode.rail,
      selectedIndex: _selectedIndex,
      onSelected: (index) => setState(() => _selectedIndex = index),
      labelMode: CoreNavigationLabelMode.selected,
      items: const [
        CoreNavigationBarItem.destination(
          icon: Icon(LucideIcons.house),
          label: 'Home',
        ),
        CoreNavigationBarItem.destination(
          icon: Icon(LucideIcons.search),
          label: 'Search',
        ),
        CoreNavigationBarItem.destination(
          icon: Icon(LucideIcons.bell),
          label: 'Alerts',
        ),
        CoreNavigationBarItem.destination(
          icon: Icon(LucideIcons.user),
          label: 'Profile',
        ),
      ],
    );
  }
}
sidebar
Web
Flutter
Loading Flutter... 
class NavigationBarSidebarExample extends StatefulComponent {
  const NavigationBarSidebarExample({super.key});

  @override
  State<NavigationBarSidebarExample> createState() =>
      _NavigationBarSidebarExampleState();
}

class _NavigationBarSidebarExampleState
    extends State<NavigationBarSidebarExample> {
  int _selectedIndex = 0;

  @override
  Component build(BuildContext context) {
    return NavigationBar(
      mode: CoreNavigationBarMode.sidebar,
      selectedIndex: _selectedIndex,
      onSelected: (index) => setState(() => _selectedIndex = index),
      items: const [
        CoreNavigationBarItem.label('Main'),
        CoreNavigationBarItem.destination(
          icon: Icon(LucideIcons.house),
          label: 'Dashboard',
        ),
        CoreNavigationBarItem.destination(
          icon: Icon(LucideIcons.search),
          label: 'Explore',
        ),
        CoreNavigationBarItem.divider(),
        CoreNavigationBarItem.label('Account'),
        CoreNavigationBarItem.destination(
          icon: Icon(LucideIcons.bell),
          label: 'Notifications',
        ),
        CoreNavigationBarItem.destination(
          icon: Icon(LucideIcons.settings),
          label: 'Settings',
        ),
      ],
    );
  }
}
class NavigationBarSidebarExample extends StatefulWidget {
  const NavigationBarSidebarExample({super.key});

  @override
  State<NavigationBarSidebarExample> createState() =>
      _NavigationBarSidebarExampleState();
}

class _NavigationBarSidebarExampleState
    extends State<NavigationBarSidebarExample> {
  int _selectedIndex = 0;

  @override
  Widget build(BuildContext context) {
    return NavigationBar(
      mode: CoreNavigationBarMode.sidebar,
      selectedIndex: _selectedIndex,
      onSelected: (index) => setState(() => _selectedIndex = index),
      items: const [
        CoreNavigationBarItem.label('Main'),
        CoreNavigationBarItem.destination(
          icon: Icon(LucideIcons.house),
          label: 'Dashboard',
        ),
        CoreNavigationBarItem.destination(
          icon: Icon(LucideIcons.search),
          label: 'Explore',
        ),
        CoreNavigationBarItem.divider(),
        CoreNavigationBarItem.label('Account'),
        CoreNavigationBarItem.destination(
          icon: Icon(LucideIcons.bell),
          label: 'Notifications',
        ),
        CoreNavigationBarItem.destination(
          icon: Icon(LucideIcons.settings),
          label: 'Settings',
        ),
      ],
    );
  }
}

사용 시기 (When to Use)#

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

  • 모바일 앱 하단의 주요 3~5개 섹션 이동(bar 모드)
  • 데스크톱/태블릿 측면의 컴팩트 네비게이션(rail 모드)
  • 라벨이 강조된 풀-너비 사이드바 네비게이션(sidebar 모드)

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

  • NavigationMenu: 드롭다운 패널이 있는 가로 메가 메뉴가 필요할 때
  • Tabs: 동일 화면 내에서 콘텐츠 탭을 전환할 때

기본 사용법 (Basic Usage)#

NavigationBar(
  mode: CoreNavigationBarMode.bar,
  selectedIndex: _selectedIndex,
  onSelected: (index) => setState(() => _selectedIndex = index),
  labelMode: CoreNavigationLabelMode.all,
  items: const [
    CoreNavigationBarItem.destination(
      icon: Icon(LucideIcons.house),
      label: 'Home',
    ),
    CoreNavigationBarItem.destination(
      icon: Icon(LucideIcons.search),
      label: 'Search',
    ),
    CoreNavigationBarItem.destination(
      icon: Icon(LucideIcons.user),
      label: 'Profile',
    ),
  ],
)

NavigationBar(
  mode: CoreNavigationBarMode.bar,
  selectedIndex: _selectedIndex,
  onSelected: (index) => setState(() => _selectedIndex = index),
  labelMode: CoreNavigationLabelMode.all,
  items: const [
    CoreNavigationBarItem.destination(
      icon: Icon(LucideIcons.house),
      label: 'Home',
    ),
    CoreNavigationBarItem.destination(
      icon: Icon(LucideIcons.search),
      label: 'Search',
    ),
    CoreNavigationBarItem.destination(
      icon: Icon(LucideIcons.user),
      label: 'Profile',
    ),
  ],
)

Props / Parameters#

속성타입기본값설명
items List<CoreNavigationBarItem> 필수 네비게이션 엔트리 목록
selectedIndex int? null 현재 선택된 destination 인덱스 (destination만 카운트)
onSelected void Function(int)? null destination 선택 핸들러
mode CoreNavigationBarMode bar 레이아웃 모드 (bar / rail / sidebar)
variant CoreNavigationBarVariant standard 시각 변형
labelMode CoreNavigationLabelMode? 모드별 기본값 라벨 표시 시점 (all / selected / none)
labelPosition CoreNavigationLabelPosition? 모드별 기본값 아이콘 대비 라벨 위치 (bottom / top / start / end)
alignment CoreNavigationAlignment center 메인 축 정렬
overflow CoreNavigationOverflow ellipsis 라벨 오버플로 처리
navigationBarStyle CoreNavigationBarStyle? null 크롬 / 치수 스타일 오버라이드

CoreNavigationBarItem#

팩토리설명
CoreNavigationBarItem.destination({icon, label, tooltip, enabled}) 선택 가능한 네비게이션 목적지
CoreNavigationBarItem.label(String)비선택 섹션 헤더 라벨
CoreNavigationBarItem.divider()구분선
CoreNavigationBarItem.gap(double)빈 간격

모드 (Modes)#

Bar#

가로 바 레이아웃입니다. 모바일 앱 하단 네비게이션에 적합합니다.

NavigationBar(mode: CoreNavigationBarMode.bar, items: [...])

Rail#

세로 컴팩트 레일 레이아웃입니다. 측면 네비게이션에 적합합니다.

NavigationBar(mode: CoreNavigationBarMode.rail, items: [...])

확장 세로 사이드바 레이아웃입니다. 섹션 라벨과 구분선으로 계층 구조를 표현합니다.

NavigationBar(
  mode: CoreNavigationBarMode.sidebar,
  items: const [
    CoreNavigationBarItem.label('Main'),
    CoreNavigationBarItem.destination(label: 'Dashboard'),
    CoreNavigationBarItem.divider(),
    CoreNavigationBarItem.label('Account'),
    CoreNavigationBarItem.destination(label: 'Settings'),
  ],
)

동작 스펙 (Behavior)#

인터랙션#

  • 선택: destination 활성화 시 onSelected(index) 호출 (destination만 인덱싱)
  • 호버: destination 호버 시 배경색 약한 강조
  • 키보드: 포커스된 destination에서 Enter / Space로 활성화

애니메이션#

  • 활성/호버 전환: 배경·전경색 변경 150ms ease-in-out

접근성 (Accessibility)#

키보드 인터랙션#

키동작
Tab다음 네비게이션 항목으로 포커스
Enter / Space포커스된 항목 활성화

스크린 리더#

  • Flutter: Semantics(selected: isSelected, button: true, label: itemLabel) 자동 적용
  • Web: <nav aria-label="Navigation"> + 각 항목 role="button" + 선택 시 aria-current="page" 적용

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

항목FlutterWeb
클래스명NavigationBarNavigationBar
렌더 루트 ColoredBox + SingleChildScrollView <nav> (flex)
라벨 오버플로TextOverflowCSS text-overflow

관련 컴포넌트 (Related Components)#

  • NavigationMenu: 드롭다운 패널이 있는 가로 메가 메뉴
  • Tabs: 화면 내 콘텐츠 섹션 전환에 사용