NavigationMenu

Rich navigation menu for site headers with dropdown content panels, animated viewport transitions, and automatic mobile drawer. Supports structured links with titles, descriptions, and icons.

Setup

import { NavigationMenu } from '@fragments-sdk/ui';

Examples

Default

Two trigger items with dropdown content and one direct link

Loading preview...

With Rich Content

Grid layout with icons, titles, and descriptions

Loading preview...

With Simple Links

Mix of triggers with simple link lists and plain links

Loading preview...

With Featured Card

Highlighted featured item alongside regular links

Loading preview...

Vertical

Vertical orientation with content panels to the right

Loading preview...

Props

PropTypeDefaultDescription
childrenRequirednodeNot setNavigationMenu.List, NavigationMenu.Viewport, and optionally NavigationMenu.MobileContent
valuestringNot setControlled open item value
defaultValuestring''Default open item value
onValueChangefunctionNot setCallback when open item changes
orientationenumhorizontalverticalhorizontal'horizontal' | 'vertical'
delayDurationnumber200Hover delay before opening (ms)
skipDelayDurationnumber300Duration after close during which moving to another trigger opens instantly (ms)
iconsobjectNot setOptional icon overrides for triggerChevron, mobileMenu, mobileClose, and drawerClose controls

Usage Guidelines

When to use

  • Site-level header navigation with rich dropdown content
  • Navigation with titles, descriptions, and icons in dropdowns
  • Responsive navigation that converts to a mobile drawer automatically
  • Multi-section navigation requiring animated viewport transitions

When not to use

  • Simple flat navigation without dropdowns (use Header.Nav)
  • Application menus with actions like cut/paste (use Menu)
  • Sidebar navigation (use Sidebar)
  • Breadcrumb trail navigation (use Breadcrumbs)

Best practices

  • Place inside Header component for site-level navigation
  • Use NavigationMenu.Viewport for animated content panel transitions
  • Use NavigationMenu.MobileContent to add extra sections to the mobile drawer
  • Use structured links (title + description) for rich dropdown content
  • Use simple NavigationMenu.Link for items without dropdown content
  • NavigationMenu.Link asChild composes click handlers and respects event.preventDefault()
  • Triggers open on hover (desktop) with configurable delay
  • Use the icons prop to replace trigger chevrons and mobile drawer controls with icons from any package
Accessibility
  • Uses disclosure pattern (not menu role) per W3C guidance
  • Keyboard: Arrow keys navigate between triggers, Enter/Space toggles, Escape closes
  • Content panels have role="region" with aria-labelledby pointing to trigger
  • Mobile drawer has focus trap, Escape to close, and aria-modal
  • Supports prefers-reduced-motion for all animations