Sidebar

Sidebar 는 화면의 읽는 방향 시작 쪽에 붙는 고정 폭 내비게이션입니다. 위에 앱의 신원(워크스페이스)과 검색, 가운데에 메뉴 행, 아래에 도움말과 로그인한 사람을 둡니다. 사이드바는 영역만 나누고 행을 직접 그리지 않습니다 — 행은 부품 컴포넌트를 조합해 넣습니다.

기본 사용법 (Basic Usage)#

Sidebar(
  header: SidebarHeader(
    leading: const Avatar(initials: 'NA'),
    title: const Text('나음 병원'),
    subtitle: const Text('본원 · 관리자'),
    trailing: const Icon(LucideIcons.chevronsUpDown),
    onPressed: () {},
  ),
  search: SidebarSearch(
    placeholder: '검색',
    shortcut: const ['⌘', 'K'],
    onPressed: () {},
  ),
  children: [
    SidebarItem(
      leading: const Icon(LucideIcons.house),
      label: const Text('홈'),
      selected: true,
      onPressed: () {},
    ),
    const SidebarSection(label: Text('업무')),
    SidebarGroup(
      leading: const Icon(LucideIcons.folder),
      label: const Text('프로젝트'),
      children: [
        SidebarItem(
          level: CoreSidebarItemLevel.nested,
          label: const Text('디자인 시스템'),
          onPressed: () {},
        ),
      ],
    ),
  ],
)

Sidebar(
  header: SidebarHeader(
    leading: Avatar(initials: 'NA'),
    title: Text('나음 병원'),
    subtitle: Text('본원 · 관리자'),
    trailing: Icon(LucideIcons.chevronsUpDown),
    onPressed: () {},
  ),
  search: SidebarSearch(
    placeholder: '검색',
    shortcut: ['⌘', 'K'],
    onPressed: () {},
  ),
  children: [
    SidebarItem(
      leading: Icon(LucideIcons.house),
      label: Text('홈'),
      selected: true,
      onPressed: () {},
    ),
    SidebarSection(label: Text('업무')),
    SidebarGroup(
      leading: Icon(LucideIcons.folder),
      label: Text('프로젝트'),
      children: [
        SidebarItem(
          level: CoreSidebarItemLevel.nested,
          label: Text('디자인 시스템'),
          onPressed: () {},
        ),
      ],
    ),
  ],
)

Live Preview#

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

  @override
  Component build(BuildContext context) {
    // A standard sidebar — identity, search, the rows, help and the person.
    return div(classes: 'h-${CoreLayout.scale.layout640}', [
      Sidebar(
        semanticLabel: '주 메뉴',
        header: SidebarHeader(
          leading: Avatar(initials: 'NA'),
          title: Text('나음 병원'),
          subtitle: Text('본원 · 관리자'),
          trailing: Icon(LucideIcons.chevronsUpDown),
          onPressed: () {},
        ),
        search: SidebarSearch(
          placeholder: '검색',
          shortcut: ['⌘', 'K'],
          onPressed: () {},
        ),
        help: SidebarItem(
          leading: Icon(LucideIcons.lifeBuoy),
          label: Text('도움말'),
          onPressed: () {},
        ),
        user: SidebarHeader(
          variant: CoreSidebarHeaderVariant.card,
          leading: Avatar(initials: 'KH'),
          title: Text('김하나'),
          subtitle: Text('hana@example.com'),
        ),
        children: [
          SidebarItem(
            leading: Icon(LucideIcons.house),
            label: Text('홈'),
            selected: true,
            onPressed: () {},
          ),
          SidebarItem(
            leading: Icon(LucideIcons.inbox),
            label: Text('받은 편지함'),
            dot: true,
            onPressed: () {},
          ),
          SidebarSection(label: Text('업무')),
          SidebarGroup(
            leading: Icon(LucideIcons.folder),
            label: Text('프로젝트'),
            children: [
              SidebarItem(
                level: CoreSidebarItemLevel.nested,
                label: Text('디자인 시스템'),
                onPressed: () {},
              ),
              SidebarItem(
                level: CoreSidebarItemLevel.nested,
                label: Text('웹사이트'),
                onPressed: () {},
              ),
            ],
          ),
          SidebarItem(
            leading: Icon(LucideIcons.calendar),
            label: Text('일정'),
            onPressed: () {},
          ),
        ],
      ),
    ]);
  }
}

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

  @override
  Widget build(BuildContext context) {
    // A standard sidebar — identity, search, the rows, help and the person.
    return SizedBox(
      height: CoreLayout.layout640,
      child: Sidebar(
        semanticLabel: '주 메뉴',
        header: SidebarHeader(
          leading: const Avatar(initials: 'NA'),
          title: const Text('나음 병원'),
          subtitle: const Text('본원 · 관리자'),
          trailing: const Icon(LucideIcons.chevronsUpDown),
          onPressed: () {},
        ),
        search: SidebarSearch(
          placeholder: '검색',
          shortcut: const ['⌘', 'K'],
          onPressed: () {},
        ),
        help: SidebarItem(
          leading: const Icon(LucideIcons.lifeBuoy),
          label: const Text('도움말'),
          onPressed: () {},
        ),
        user: const SidebarHeader(
          variant: CoreSidebarHeaderVariant.card,
          leading: Avatar(initials: 'KH'),
          title: Text('김하나'),
          subtitle: Text('hana@example.com'),
        ),
        children: [
          SidebarItem(
            leading: const Icon(LucideIcons.house),
            label: const Text('홈'),
            selected: true,
            onPressed: () {},
          ),
          SidebarItem(
            leading: const Icon(LucideIcons.inbox),
            label: const Text('받은 편지함'),
            dot: true,
            onPressed: () {},
          ),
          const SidebarSection(label: Text('업무')),
          SidebarGroup(
            leading: const Icon(LucideIcons.folder),
            label: const Text('프로젝트'),
            children: [
              SidebarItem(
                level: CoreSidebarItemLevel.nested,
                label: const Text('디자인 시스템'),
                onPressed: () {},
              ),
              SidebarItem(
                level: CoreSidebarItemLevel.nested,
                label: const Text('웹사이트'),
                onPressed: () {},
              ),
            ],
          ),
          SidebarItem(
            leading: const Icon(LucideIcons.calendar),
            label: const Text('일정'),
            onPressed: () {},
          ),
        ],
      ),
    );
  }
}

구조 (Anatomy)#

standard    패널  top    header · search
                  body   children (스크롤)
                  bottom footer · help · user
twoPane     레일  railHeader · railItems · railFooter
            패널  top    panelTitle · panelAction · search
                  body   children (스크롤)
                  bottom footer · help · user
collapsed   레일  railHeader · railItems · railFooter

• 패널의 위아래 영역은 고정되고 가운데 본문만 스크롤됩니다.
• 페이지와 맞닿는 끝쪽 경계선은 가장 바깥 열이 그립니다 — collapsed 는 레일, 나머지는 패널.

Figma: CoUI 라이브러리 ❖ Sidebar 페이지.

사용 시기 (When to Use)#

• 메뉴가 많고 구역 · 그룹 · 2단 메뉴가 필요한 관리자 · 업무 화면.
• 화면 왼쪽(오른쪽에서 왼쪽으로 쓰는 언어는 오른쪽)에 늘 머무는 내비게이션.

모바일의 아래 탭 바는 NavigationBar 를, 화면 일부의 탭 전환은 Tabs 를 씁니다.

Props / Parameters#

Sidebar#

SidebarItem#

나머지 부품#

CoreSidebarStyle 필드#

스타일 시스템 (Style System)#

모든 chrome 은 각 컴포넌트의 단일 Style 슬롯으로만 들어갑니다. 사이드바는 틀(면 · 경계 · 폭 · 영역 여백)만, 행은 자기 Style 을 가집니다.

Resolve chain#

CoreSidebarStyle.defaultX → defaultsByType[type]
  → CoreSidebarTheme.style
  → CoreSidebarTheme.variantStyles[type]
  → widget.sidebarStyle

CoreSidebarItemStyle.defaultX → defaultsByLevel[level]
  → CoreSidebarItemTheme.style
  → CoreSidebarItemTheme.variantStyles[level]
  → widget.sidebarItemStyle

테마로 덮어쓰기#

CoreComponentTheme(
  sidebar: CoreSidebarTheme(
    style: CoreSidebarStyle(panelWidth: CoreLayout.layout280),
  ),
  sidebarItem: CoreSidebarItemTheme(
    variantStyles: {
      CoreSidebarItemLevel.nested: CoreSidebarItemStyle(
        minHeight: CoreSize.size28,
      ),
    },
  ),
)

변형 (Variants)#

type: standard#

한 패널. 폭 248, 바탕 surfaceContainerLow, 끝쪽 경계 outlineVariant.

type: twoPane#

64 레일 옆에 240 패널. 레일은 한 단 깊은 surfaceContainer 로 칠해져 두 열로 읽힙니다. 패널 위에는 레일에서 고른 영역의 제목(panelTitle)이 옵니다.

type: collapsed#

레일만 남깁니다. 각 목적지의 이름은 툴팁과 접근성 이름이 말합니다.

동작 스펙 (Behavior)#

인터랙션#

• SidebarItem · SidebarRailItem · SidebarSearch 와 onPressed 가 있는 SidebarHeader 는 누를 수 있습니다. hover · focus · press 는 onSurface 상태 레이어(3 %)로 표시합니다.
• SidebarGroup 의 행을 누르면 하위 행이 열리고 닫힙니다.

상태 전환#

• 미선택 행의 글자와 아이콘은 onSurfaceSubtle, 지금 있는 곳은 surfaceContainer 바탕에 onSurface 600 입니다.
• 비활성 행은 disabledContent 로 칠해지고, 선택돼 있어도 선택으로 그리지 않습니다.

애니메이션#

• 행 바탕 전환은 Clickable 의 시계를 따릅니다.
• 그룹이 열고 닫히는 시간은 CoreDuration.normal(200ms) 이며 동작 줄이기에서 0 이 됩니다.

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

Do#

Don't#

접근성 (Accessibility)#

역할#

• Sidebar 는 내비게이션 랜드마크입니다 (Web <nav>, Flutter navigation 시맨틱). semanticLabel 로 이름을 붙입니다.
• 지금 있는 곳은 Web 에서 aria-current="page", Flutter 에서 selected 로 알립니다.
• SidebarGroup 의 행은 aria-expanded 로 열림을 알립니다. 닫힌 하위 행은 Web 에서 inert 라 키보드와 보조 기술에 닿지 않습니다.
• SidebarSection 은 제목(heading)입니다.

키보드#

• Tab 으로 누를 수 있는 부품을 차례로 지나고, 위 · 아래 화살표로 행 사이를 옮깁니다.
• Enter · Space 로 행을 누릅니다.

스크린 리더#

• SidebarRailItem 은 보이는 이름이 없어 label 이 접근성 이름입니다.
• SidebarSearch 는 placeholder 가 접근성 이름이고 단축키는 Web 에서 aria-keyshortcuts 로 알립니다.

포커스 관리#

포커스 링은 각 행의 모서리를 따릅니다(Clickable).

알려진 제약#

• 미선택 행의 onSurfaceSubtle 은 라이트 테마의 surfaceContainerLow 위에서 4.5 : 1 아래로 내려갑니다. Tabs 의 미선택 글자와 같이 받아들인 예외입니다. 지금 있는 곳은 onSurface 라 이 제약 밖입니다.

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

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

추가 차이 없음 — 이름 · 기본값 · 순서는 두 플랫폼이 같습니다.

관련 컴포넌트 (Related Components)#

• NavigationBar: 화면 아래 탭 바와 레일
• Tabs: 화면 일부의 탭 전환
• Kbd: SidebarSearch 의 단축키

조합 예제#

Sidebar(
  footer: Card(
    child: Progress(value: 0.6),
  ),
  children: [...],
)