Skip to Content
ComponentsFoundationNavigationMenu

NavigationMenu

여러 콘텐츠 섹션으로 이동하는 링크 모음을 제공하는 내비게이션 메뉴 컴포넌트

개요

NavigationMenu 컴포넌트는 base-ui의 NavigationMenu Primitive를 기반으로 구축된 내비게이션 메뉴입니다. 트리거에 호버 또는 클릭하면 드롭다운 콘텐츠가 부드러운 애니메이션과 함께 표시되며, 뷰포트 기반 전환 효과를 지원합니다.

주요 특징

  • ✅ 컴파운드 컴포넌트: List, Item, Trigger, Content, Link 등 유연한 구성
  • ✅ 뷰포트 애니메이션: 메뉴 전환 시 크기/위치 애니메이션 자동 적용
  • ✅ 호버/포커스 인터랙션: 마우스 호버와 키보드 포커스 모두 지원
  • ✅ 활성 링크 표시: data-active 속성으로 현재 페이지 링크 강조
  • ✅ 접근성: role="navigation", ARIA 속성 자동 관리
  • ✅ 디자인 토큰: 테마 커스터마이징 지원

구조 (Anatomy)

<NavigationMenu>
  <NavigationMenuList>
    <NavigationMenuItem>
      <NavigationMenuTrigger>메뉴명</NavigationMenuTrigger>
      <NavigationMenuContent>
        <NavigationMenuLink href="#">링크</NavigationMenuLink>
      </NavigationMenuContent>
    </NavigationMenuItem>
    <NavigationMenuItem>
      <NavigationMenuLink href="#">단일 링크</NavigationMenuLink>
    </NavigationMenuItem>
  </NavigationMenuList>
</NavigationMenu>

사용 예시

기본 사용

트리거에 호버하거나 클릭하면 콘텐츠가 표시됩니다.

단순 링크 메뉴

드롭다운 없이 단일 링크만으로 구성할 수 있습니다.

API Reference

내비게이션 메뉴의 루트 컴포넌트입니다. base-ui NavigationMenu.Root를 래핑하며, 팝업 포지셔너와 뷰포트를 내부에 포함합니다.

PropTypeDefaultDescription
defaultValueany-초기 활성 아이템 값
valueany-제어 모드 활성 아이템 값
onValueChange(value: any) => void-활성 아이템 변경 콜백
delaynumber-호버 시 메뉴 열림 지연(ms)
closeDelaynumber-호버 해제 시 닫힘 지연(ms)
orientation"horizontal" | "vertical"-메뉴 방향
align"start" | "center" | "end""start"팝업 정렬 방향
classNamestring-추가 CSS 클래스

메뉴 아이템들을 나열하는 컨테이너입니다.

PropTypeDefaultDescription
classNamestring-추가 CSS 클래스

개별 메뉴 항목입니다. Trigger + Content 또는 단일 Link를 자식으로 가집니다.

PropTypeDefaultDescription
valueany-아이템 식별 값
classNamestring-추가 CSS 클래스

드롭다운 콘텐츠를 여는 트리거 버튼입니다. 셰브론 아이콘이 자동으로 포함되며 열림 시 회전합니다.

PropTypeDefaultDescription
classNamestring-추가 CSS 클래스

트리거 활성화 시 표시되는 드롭다운 콘텐츠입니다.

PropTypeDefaultDescription
classNamestring-추가 CSS 클래스

내비게이션 링크입니다. data-active="true"로 현재 페이지를 표시할 수 있습니다.

PropTypeDefaultDescription
hrefstring-링크 URL
activeboolean-활성 링크 여부
classNamestring-추가 CSS 클래스

기본 사용법

import {
  NavigationMenu,
  NavigationMenuList,
  NavigationMenuItem,
  NavigationMenuTrigger,
  NavigationMenuContent,
  NavigationMenuLink,
} from "@vortex/ui-foundation"
 
<NavigationMenu>
  <NavigationMenuList>
    <NavigationMenuItem>
      <NavigationMenuTrigger>메뉴</NavigationMenuTrigger>
      <NavigationMenuContent>
        <NavigationMenuLink href="/docs">문서</NavigationMenuLink>
      </NavigationMenuContent>
    </NavigationMenuItem>
  </NavigationMenuList>
</NavigationMenu>

접근성

시맨틱 마크업

  • base-ui NavigationMenu 기반으로 role="navigation" 및 ARIA 속성 자동 적용
  • Trigger에 aria-expanded 상태가 자동 설정

키보드 네비게이션

  • Tab: 메뉴 아이템 간 이동
  • Enter / Space: 트리거 활성화, 링크 이동
  • Arrow Keys: 콘텐츠 내 링크 탐색
  • Esc: 열린 콘텐츠 닫기

권장 사항

  • ✅ 사이트 주요 내비게이션에 사용
  • ✅ 현재 페이지 링크에 active 속성으로 활성 상태 표시
  • ❌ 단순 액션 메뉴에는 DropdownMenu 또는 Menubar 사용

관련 컴포넌트

Last updated on
NativeSelectOverlayLoading