Chapter 30: Navigation Menu

Core Idea

The site-navigation "mega menu" pattern — a horizontal List of Items whose Triggers open shared-panel Content inside one animated Viewport, sharing the same anchored-positioning family as Menu/Popover but built specifically for persistent top-level nav rather than transient action menus.

Key Concepts

• Anatomy: Root → List → Item → Trigger (+ Icon) → Content → Link; plus Portal → Backdrop, Positioner → Popup (Arrow, Viewport).
• Shared Viewport: unlike Menu's optional transition viewport, Navigation Menu's Viewport is core to the pattern — all Items' Content panels render into one shared, size-animated viewport rather than each getting a separate popup, so switching between menu items animates as a single panel resizing/cross-fading.
• Hover intent: Root-level delay/closeDelay control hover-open/close timing across all items uniformly (vs. Menu's per-trigger delay props).
• Content.data-activation-direction: which direction the panel transition should animate, based on the previous vs. newly active item's position in the List.
• Link.active/data-active: marks the nav link matching the current route — typically driven by your router (e.g. compare Link's href against the current pathname).

Reference Tables

Part	Notable props	Notable data attributes
Root	value/onValueChange, delay, closeDelay, orientation	—
Trigger	nativeButton	data-popup-open, data-pressed
Content	keepMounted	data-open, data-closed, data-activation-direction, data-starting-style/data-ending-style
Link	closeOnClick, active	data-active
Positioner	same anchored-positioning props as Menu/Popover	data-anchor-hidden, data-align, data-side

Key Takeaways

1. Use Navigation Menu specifically for persistent site navigation with rich dropdown panels; use plain Menu for transient action lists — mixing them up loses the shared-viewport animation Navigation Menu is built for.
2. Drive Link.active from your router's current-route state — it isn't automatic since Base UI has no router integration built in.
3. Configure Root-level delay/closeDelay once for the whole nav bar rather than per item — consistent hover timing across all top-level items is expected UX for this pattern.

Connects To

• ch027 (Menu): shares the anchored-positioning (Positioner) API family, but a different content-transition model (Viewport).
• ch028 (Menubar): also a horizontal multi-item bar, but for action menus rather than navigation content panels — pick based on whether items open actions (Menubar) or content panels (Navigation Menu).