NavigationMenu | CoUI

NavigationMenu#

호버 또는 클릭으로 콘텐츠 패널이 펼쳐지는 가로 메가-메뉴 컴포넌트입니다. 각 상위 항목은 콘텐츠 패널을 가지거나, 직접 링크이거나, 액션 콜백을 가질 수 있습니다.

NavigationMenu는 데이터 기반 컴포넌트입니다. CoreNavigationMenuItem 목록을 넘기면 각 항목이 가로 트리거 바에 라벨로 표시되고, content가 있는 항목은 호버/클릭 시 드롭다운 패널로 펼쳐집니다. Flutter와 Web이 동일한 파라미터 이름·동작을 갖습니다.

Live Preview#

default

Web

Flutter

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

  @override
  Component build(BuildContext context) {
    return NavigationMenu(
      items: [
        CoreNavigationMenuItem(
          label: 'Products',
          content: div(
            [
              Text('Web Apps').titleSmall.medium,
              Text('Build modern web experiences').bodySmall.onSurfaceVariant,
              Text('Mobile Apps').titleSmall.medium,
              Text('Native iOS and Android apps').bodySmall.onSurfaceVariant,
            ],
            styles: const Styles(
              display: Display.flex,
              flexDirection: FlexDirection.column,
              gap: Gap.all(Unit.pixels(CoreSpace.space8)),
            ),
          ),
        ),
        CoreNavigationMenuItem(
          label: 'Solutions',
          content: div(
            [
              Text('For Startups').titleSmall.medium,
              Text('Scale from zero to launch').bodySmall.onSurfaceVariant,
              Text('For Enterprise').titleSmall.medium,
              Text('Security and compliance built in').bodySmall
                  .onSurfaceVariant,
            ],
            styles: const Styles(
              display: Display.flex,
              flexDirection: FlexDirection.column,
              gap: Gap.all(Unit.pixels(CoreSpace.space8)),
            ),
          ),
        ),
        CoreNavigationMenuItem(label: 'Pricing', onTap: () {}),
        CoreNavigationMenuItem(label: 'About', onTap: () {}),
      ],
    );
  }
}

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

  @override
  Widget build(BuildContext context) {
    return NavigationMenu(
      items: [
        CoreNavigationMenuItem(
          label: 'Products',
          content: Column(
            mainAxisSize: MainAxisSize.min,
            crossAxisAlignment: CrossAxisAlignment.start,
            spacing: CoreSpace.space8,
            children: [
              Text('Web Apps').titleSmall.medium,
              Text('Build modern web experiences').bodySmall.onSurfaceVariant,
              Text('Mobile Apps').titleSmall.medium,
              Text('Native iOS and Android apps').bodySmall.onSurfaceVariant,
            ],
          ),
        ),
        CoreNavigationMenuItem(
          label: 'Solutions',
          content: Column(
            mainAxisSize: MainAxisSize.min,
            crossAxisAlignment: CrossAxisAlignment.start,
            spacing: CoreSpace.space8,
            children: [
              Text('For Startups').titleSmall.medium,
              Text('Scale from zero to launch').bodySmall.onSurfaceVariant,
              Text('For Enterprise').titleSmall.medium,
              Text('Security and compliance built in').bodySmall
                  .onSurfaceVariant,
            ],
          ),
        ),
        CoreNavigationMenuItem(label: 'Pricing', onTap: () {}),
        CoreNavigationMenuItem(label: 'About', onTap: () {}),
      ],
    );
  }
}

chain

Web

Flutter

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

  @override
  Component build(BuildContext context) {
    return NavigationMenu(
      items: [
        CoreNavigationMenuItem(
          label: 'Products',
          content: div(
            [
              Text('Web Apps').titleSmall.medium,
              Text('Build modern web experiences').bodySmall.onSurfaceVariant,
              Text('Mobile Apps').titleSmall.medium,
              Text('Native iOS and Android apps').bodySmall.onSurfaceVariant,
            ],
            styles: const Styles(
              display: Display.flex,
              flexDirection: FlexDirection.column,
              gap: jaspr_dom.Gap.all(Unit.pixels(CoreSpace.space8)),
            ),
          ),
        ),
        CoreNavigationMenuItem(
          label: 'Solutions',
          content: div(
            [
              Text('For Startups').titleSmall.medium,
              Text('Scale from zero to launch').bodySmall.onSurfaceVariant,
              Text('For Enterprise').titleSmall.medium,
              Text('Security and compliance built in').bodySmall.onSurfaceVariant,
            ],
            styles: const Styles(
              display: Display.flex,
              flexDirection: FlexDirection.column,
              gap: jaspr_dom.Gap.all(Unit.pixels(CoreSpace.space8)),
            ),
          ),
        ),
        CoreNavigationMenuItem(label: 'Pricing', onTap: () {}),
        CoreNavigationMenuItem(label: 'About', onTap: () {}),
      ],
    ).withStyle(
      const CoreNavigationMenuStyle(
        triggerPadding: CoreEdgeInsets.symmetric(
          horizontal: CoreSpace.space20,
          vertical: CoreSpace.space12,
        ),
        triggerBorderRadius: CoreBorderRadius.all(CoreRadius.radius24),
        triggerHoverColor: CoreColor.token(CoreColors.secondaryContainer),
        triggerSpacing: CoreSpace.space12,
      ),
    );
  }
}

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

  @override
  Widget build(BuildContext context) {
    return NavigationMenu(
      items: [
        CoreNavigationMenuItem(
          label: 'Products',
          content: Column(
            mainAxisSize: MainAxisSize.min,
            crossAxisAlignment: CrossAxisAlignment.start,
            spacing: CoreSpace.space8,
            children: [
              Text('Web Apps').titleSmall.medium,
              Text('Build modern web experiences').bodySmall.onSurfaceVariant,
              Text('Mobile Apps').titleSmall.medium,
              Text('Native iOS and Android apps').bodySmall.onSurfaceVariant,
            ],
          ),
        ),
        CoreNavigationMenuItem(
          label: 'Solutions',
          content: Column(
            mainAxisSize: MainAxisSize.min,
            crossAxisAlignment: CrossAxisAlignment.start,
            spacing: CoreSpace.space8,
            children: [
              Text('For Startups').titleSmall.medium,
              Text('Scale from zero to launch').bodySmall.onSurfaceVariant,
              Text('For Enterprise').titleSmall.medium,
              Text('Security and compliance built in').bodySmall.onSurfaceVariant,
            ],
          ),
        ),
        CoreNavigationMenuItem(label: 'Pricing', onTap: () {}),
        CoreNavigationMenuItem(label: 'About', onTap: () {}),
      ],
    ).withStyle(
      const CoreNavigationMenuStyle(
        triggerPadding: CoreEdgeInsets.symmetric(
          horizontal: CoreSpace.space20,
          vertical: CoreSpace.space12,
        ),
        triggerBorderRadius: CoreBorderRadius.all(CoreRadius.radius24),
        triggerHoverColor: CoreColor.token(CoreColors.secondaryContainer),
        triggerSpacing: CoreSpace.space12,
      ),
    );
  }
}

사용 시기 (When to Use)#

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

사이트 전역 네비게이션에서 카테고리별 풍부한 콘텐츠 패널이 필요할 때
마케팅 사이트의 헤더처럼 제품/솔루션을 메가-메뉴로 정리할 때
호버로 미리보기를 제공하면서 클릭으로도 동작해야 할 때

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

Menubar: 데스크탑 앱 스타일의 파일/편집 메뉴 바에
DropdownMenu: 단일 버튼의 드롭다운 액션 목록에
Menu: 사이드바 형태의 일반 메뉴에

기본 사용법 (Basic Usage)#

NavigationMenu(
  items: [
    CoreNavigationMenuItem(
      label: 'Products',
      content: const Text('Browse the product catalog'),
    ),
    CoreNavigationMenuItem(label: 'Pricing', href: '/pricing'),
    CoreNavigationMenuItem(label: 'About', onTap: () {}),
  ],
)

NavigationMenu(
  items: [
    CoreNavigationMenuItem(
      label: 'Products',
      content: const Text('Browse the product catalog'),
    ),
    CoreNavigationMenuItem(label: 'Pricing', href: '/pricing'),
    CoreNavigationMenuItem(label: 'About', onTap: () {}),
  ],
)

빠른 오버라이드 (Chain)#

이미 만든 NavigationMenu 인스턴스에 스타일을 빠르게 덧붙이고 싶다면 withStyle 체인을 쓸 수 있습니다. 생성자의 style 슬롯 인자와 동일하게 동작하지만, 이미 구성된 위젯 위에서 바로 이어 쓸 수 있습니다.

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

  @override
  Widget build(BuildContext context) {
    return NavigationMenu(
      items: [
        CoreNavigationMenuItem(
          label: 'Products',
          content: Column(
            mainAxisSize: MainAxisSize.min,
            crossAxisAlignment: CrossAxisAlignment.start,
            spacing: CoreSpace.space8,
            children: [
              Text('Web Apps').titleSmall.medium,
              Text('Build modern web experiences').bodySmall.onSurfaceVariant,
              Text('Mobile Apps').titleSmall.medium,
              Text('Native iOS and Android apps').bodySmall.onSurfaceVariant,
            ],
          ),
        ),
        CoreNavigationMenuItem(
          label: 'Solutions',
          content: Column(
            mainAxisSize: MainAxisSize.min,
            crossAxisAlignment: CrossAxisAlignment.start,
            spacing: CoreSpace.space8,
            children: [
              Text('For Startups').titleSmall.medium,
              Text('Scale from zero to launch').bodySmall.onSurfaceVariant,
              Text('For Enterprise').titleSmall.medium,
              Text('Security and compliance built in').bodySmall.onSurfaceVariant,
            ],
          ),
        ),
        CoreNavigationMenuItem(label: 'Pricing', onTap: () {}),
        CoreNavigationMenuItem(label: 'About', onTap: () {}),
      ],
    ).withStyle(
      const CoreNavigationMenuStyle(
        triggerPadding: CoreEdgeInsets.symmetric(
          horizontal: CoreSpace.space20,
          vertical: CoreSpace.space12,
        ),
        triggerBorderRadius: CoreBorderRadius.all(CoreRadius.radius24),
        triggerHoverColor: CoreColor.token(CoreColors.secondaryContainer),
        triggerSpacing: CoreSpace.space12,
      ),
    );
  }
}

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

  @override
  Component build(BuildContext context) {
    return NavigationMenu(
      items: [
        CoreNavigationMenuItem(
          label: 'Products',
          content: div(
            [
              Text('Web Apps').titleSmall.medium,
              Text('Build modern web experiences').bodySmall.onSurfaceVariant,
              Text('Mobile Apps').titleSmall.medium,
              Text('Native iOS and Android apps').bodySmall.onSurfaceVariant,
            ],
            styles: const Styles(
              display: Display.flex,
              flexDirection: FlexDirection.column,
              gap: jaspr_dom.Gap.all(Unit.pixels(CoreSpace.space8)),
            ),
          ),
        ),
        CoreNavigationMenuItem(
          label: 'Solutions',
          content: div(
            [
              Text('For Startups').titleSmall.medium,
              Text('Scale from zero to launch').bodySmall.onSurfaceVariant,
              Text('For Enterprise').titleSmall.medium,
              Text('Security and compliance built in').bodySmall.onSurfaceVariant,
            ],
            styles: const Styles(
              display: Display.flex,
              flexDirection: FlexDirection.column,
              gap: jaspr_dom.Gap.all(Unit.pixels(CoreSpace.space8)),
            ),
          ),
        ),
        CoreNavigationMenuItem(label: 'Pricing', onTap: () {}),
        CoreNavigationMenuItem(label: 'About', onTap: () {}),
      ],
    ).withStyle(
      const CoreNavigationMenuStyle(
        triggerPadding: CoreEdgeInsets.symmetric(
          horizontal: CoreSpace.space20,
          vertical: CoreSpace.space12,
        ),
        triggerBorderRadius: CoreBorderRadius.all(CoreRadius.radius24),
        triggerHoverColor: CoreColor.token(CoreColors.secondaryContainer),
        triggerSpacing: CoreSpace.space12,
      ),
    );
  }
}

Props / Parameters#

NavigationMenu#

속성	타입	기본값	설명
`items`	`List<CoreNavigationMenuItem>`	필수	가로 트리거 바에 표시되는 상위 항목 목록
`activeIndex`	`int?`	`null`	활성 항목 인덱스. 지정 시 제어 모드, 생략 시 내부 상태 관리
`onActiveIndexChanged`	`void Function(int?)?`	`null`	활성 항목이 바뀔 때 호출 (`null`이면 닫힘)
`variant`	`CoreNavigationMenuVariant`	`standard`	시각 변형
`navigationMenuStyle`	`CoreNavigationMenuStyle?`	`null`	인스턴스별 chrome / 치수 스타일

CoreNavigationMenuItem#

속성	타입	기본값	설명
`label`	`String`	필수	가로 트리거 바에 표시되는 라벨
`content`	`Widget?` / `Component?`	`null`	펼쳐지는 드롭다운 콘텐츠 (콘텐츠 항목)
`href`	`String?`	`null`	직접 링크 URL (링크 항목)
`onTap`	`CoreVoidCallback?`	`null`	액션 항목 활성화 시 호출

스타일 시스템 (Style System)#

NavigationMenu의 모든 chrome / 치수 오버라이드는 단일 CoreNavigationMenuStyle 슬롯으로 흐릅니다. 가로 트리거 바와 드롭다운 패널 chrome을 모두 한 클래스가 받습니다.

시맨틱 vs 스타일#

시맨틱 / behaviour: 위젯 파라미터로 직접 (variant, items, activeIndex)
chrome / dimensional: navigationMenuStyle: CoreNavigationMenuStyle? 한 곳으로

Resolve chain#

CoreNavigationMenuStyle.defaultX                       // 디자인 시스템 기본값
  → CoreNavigationMenuTheme.style                       // 프로젝트 공통
  → CoreNavigationMenuTheme.variantStyles[variant]      // variant별 공통
  → widget.navigationMenuStyle                          // 인스턴스별

`CoreNavigationMenuStyle` 필드#

필드	타입	설명
`triggerPadding`	`CoreEdgeInsets?`	Padding applied to each top-level trigger.
`triggerBorderRadius`	`CoreBorderRadius?`	Corner radius of a top-level trigger.
`triggerHoverColor`	`CoreColor?`	Hover / active background colour of a trigger.
`triggerButtonStyle`	`CoreButtonStyle?`	Nested style for the top-level trigger `Button(variant: menubar)` — the single source for the trigger's button chrome (padding + radius). Resolvers raw-forward `defaultTriggerButtonStyle.merge(this)` to the composed `Button` (no resolver-side assembly). `null` falls back to [defaultTriggerButtonStyle].
`triggerSpacing`	`double?`	Inter-trigger spacing (logical px, pre-scaling). Used both for the gap between adjacent top-level triggers (bar level) and for the per-trigger label → chevron gap. Flows directly into `Row.spacing` (Flutter) / inline CSS `gap` (Web) — both native paint-API forms that consume raw doubles, so the slot stays scalar ( `double?` ). Falls back to [defaultTriggerSpacing] when null.
`triggerTextStyle`	`CoreTextStyle?`	Top-level trigger label text style override. Typography role + weight + colour are carried in this single [CoreTextStyle] slot (sb-text-style-repackage). Text colour is carried via [CoreTextStyle.color] inside this slot. Overlaid on [defaultTriggerTextStyle] ( `labelLarge` role + medium weight + `onSurface` colour) when null.
`chevronIconStyle`	`CoreIconStyle?`	Chevron disclosure icon style of a content trigger. Falls back to [defaultChevronIconStyle] when null.
`panelStyle`	`CorePopupStyle?`	Nested panel-box chrome for the dropdown content panel — the panel is a `Popup` , so the resolver raw-forwards this (merged over [defaultPanelStyle] + the variant's [defaultsByVariant] colours) to the composed `Popup` 's `popupStyle` ; the popup resolver fills the rest from [CorePopupStyle]'s own defaults. Overlaid by the per-instance value.
`menuOffset`	`double?`	Vertical gap between the trigger bar and a dropdown panel (logical px).
`duration`	`Duration?`	Open / close colour-transition duration.
`closeDelay`	`Duration?`	Grace period between the pointer leaving the menu and the panel closing. Falls back to [defaultCloseDelay] when null.
`panelSwitchDuration`	`Duration?`	Duration of the panel's slide when the open menu moves from one trigger to another. Falls back to [defaultPanelSwitchDuration] when null.

`CoreNavigationMenuStyle` 변형별 기본값 (`CorePopupStyle`)#

필드	`standard`
`backgroundColor`	surface
`borderColor`	outlineVariant (fallback: outline)

사용 예 (Flutter / Web 동일)#

NavigationMenu(
  navigationMenuStyle: const CoreNavigationMenuStyle(
    panelBorderRadius: CoreBorderRadius.all(CoreRadius.radius16),
    panelBackgroundColor: CoreColor.token(CoreColors.surface),
  ),
  items: [
    CoreNavigationMenuItem(
      label: 'Products',
      content: const Text('Browse the product catalog'),
    ),
  ],
)

동작 스펙 (Behavior)#

인터랙션#

호버: content를 가진 트리거에 호버하면 패널이 펼쳐짐
클릭: content 트리거 클릭 시 토글, href 트리거는 링크 이동, onTap 트리거는 콜백 호출
외부 클릭: 메뉴 외부 클릭 시 닫힘
Escape: 열린 패널 닫힘
호버 이탈: 트리거나 패널을 벗어나면 closeDelay(기본 200ms) 후 닫힘. 그 사이 메뉴 어느 부분으로든 다시 들어오면 취소됩니다 — 트리거와 패널 사이 간극을 건너는 동안 패널이 깜빡이며 닫히지 않도록.

상태 전환#

closed → open: 콘텐츠 트리거 호버 / 클릭
open → open (다른 항목): 다른 콘텐츠 트리거 호버 / 클릭. 패널은 마운트를 유지한 채 이동합니다 — 닫혔다 다시 열리지 않습니다.
open → closed: 외부 클릭, Escape, closeDelay 경과

애니메이션#

트리거 hover 배경: 150ms 색상 전환 (CoreDuration.ms150)
chevron 회전: 활성 시 180° (CoreDuration.ms150)
패널 전환(트리거 → 트리거): panelSwitchDuration(기본 300ms, CoreEasing.move) 동안 패널이 이전 위치에서 새 위치로 이동하고, 콘텐츠는 이동 방향에 따라 방향성 크로스페이드로 교차합니다. 처음 열기와 완전히 닫기의 모션은 이와 별개로 패널 Popup 의 CorePopupStyle 이 소유합니다.

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

✅ Do#

항목 종류(콘텐츠 / 링크 / 액션)를 하나만 지정하기

CoreNavigationMenuItem(
  label: 'Pricing',
  href: '/pricing',
  onTap: () => context.go('/pricing'), // Flutter 라우팅은 onTap 이 담당
)

Web은 href로 실제 <a href>를 렌더해 브라우저 네비게이션이 일어나지만, Flutter는 href를 Semantics(link: true) 표시에만 쓰고 실제 이동 로직이 없습니다 — onTap이 없으면 Flutter에서는 클릭해도 아무 일도 일어나지 않습니다.

❌ Don't#

content와 href를 같은 항목에 동시에 지정하지 않기

// ❌ content 와 href 를 동시에
CoreNavigationMenuItem(
  label: 'Docs',
  href: '/docs',
  content: const Text('Docs preview'),
)

Web은 href가 있으면 무조건 실제 <a href>를 렌더해 content를 아예 그리지 않는 반면, Flutter는 content가 있으면 탭이 항상 드롭다운을 토글하고 href는 접근성 표시에만 쓰입니다 — 같은 코드가 Web에선 "링크", Flutter에선 "드롭다운"으로 다르게 동작합니다.

접근성 (Accessibility)#

시맨틱 역할#

가로 바: role="menubar" + aria-orientation="horizontal"
콘텐츠 트리거: role="menuitem" + aria-haspopup + aria-expanded
링크 트리거: <a role="menuitem">
드롭다운 패널: role="menu"

키보드 인터랙션#

키	동작
`Escape`	열린 패널 닫기

스크린 리더#

Flutter: Semantics로 navigation / button / link / expanded 상태 전달
Web: role="menubar" / role="menuitem" / role="menu" 자동 적용

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

NavigationMenu는 Flutter와 Web이 동일한 items / activeIndex / onActiveIndexChanged / variant / navigationMenuStyle API와 동작을 갖습니다. 드롭다운 패널은 Flutter에서는 OverlayPortal, Web에서는 루트 OverlayHost의 menu 레이어로 portal되어 양쪽 모두 ancestor overflow에 잘리지 않습니다.

패널 전환 모션도 양쪽 동작이 같습니다 — 같은 panelSwitchDuration 과 CoreEasing.move 를 읽고, 같은 방향으로 콘텐츠가 교차합니다. 전달 수단만 렌더 엔진을 따릅니다: Flutter 는 보간(TweenAnimationBuilder + Transform.translate), Web 은 CSS 키프레임(co-overlay-switch / co-overlay-swap-*)입니다. Web 이 transition 대신 키프레임을 쓰는 이유는 포털이 패널 DOM 노드를 매 렌더 재생성해 transition 이 발화하지 않기 때문입니다.

Menubar: 데스크탑 앱 스타일의 메뉴 바
Menu: 사이드바 형태의 일반 메뉴
Navigation: 페이지 이동을 위한 네비게이션 바

NavigationMenu

NavigationMenu#

Live Preview#

사용 시기 (When to Use)#

기본 사용법 (Basic Usage)#

빠른 오버라이드 (Chain)#

Props / Parameters#

NavigationMenu#

CoreNavigationMenuItem#

스타일 시스템 (Style System)#

시맨틱 vs 스타일#

Resolve chain#

CoreNavigationMenuStyle 필드#

CoreNavigationMenuStyle 변형별 기본값 (CorePopupStyle)#

사용 예 (Flutter / Web 동일)#

동작 스펙 (Behavior)#

인터랙션#

상태 전환#

애니메이션#

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

✅ Do#

❌ Don't#

접근성 (Accessibility)#

시맨틱 역할#

키보드 인터랙션#

스크린 리더#

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

관련 컴포넌트 (Related Components)#

`CoreNavigationMenuStyle` 필드#

`CoreNavigationMenuStyle` 변형별 기본값 (`CorePopupStyle`)#