React Navigation Menu Component

A navigation menu provides a clear visual structure for the primary links of a website or application. It is typically anchored to the top of the interface and includes triggers that reveal dropdown menus containing related sub-links.

This component is built on top of Base UI, ensuring it is fully accessible, supports keyboard navigation, and works seamlessly across different screen sizes.

Installation

Install the component using the Tailgrids CLI.

npx @tailgrids/cli add navigation-menu

Anatomy

Import the component parts and combine them to create a structured navigation menu.

import {
  NavigationMenu,
  NavigationMenuContent,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuTrigger,
  NavigationMenuIndicator,
  NavigationMenuPositioner
} from "@/registry/core/navigation-menu";

export const NavigationMenuExample = () => (
  <NavigationMenu>
    <NavigationMenuList>
      <NavigationMenuItem>
        <NavigationMenuTrigger>Item One</NavigationMenuTrigger>
        <NavigationMenuContent>
          <NavigationMenuLink href="/link1">Link One</NavigationMenuLink>
        </NavigationMenuContent>
      </NavigationMenuItem>
      <NavigationMenuItem>
        <NavigationMenuLink href="/link2">Direct Link Two</NavigationMenuLink>
      </NavigationMenuItem>
      <NavigationMenuIndicator />
    </NavigationMenuList>
    <NavigationMenuPositioner />
  </NavigationMenu>
);

Usage

Import the navigation menu components and compose them to build your menu structure. You can use NavigationMenuContent for dropdowns or NavigationMenuLink for direct links.

import {
  NavigationMenu,
  NavigationMenuContent,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuTrigger,
  NavigationMenuPositioner
} from "@/registry/core/navigation-menu";

export default function NavigationMenuExample() {
  return (
    <NavigationMenu>
      <NavigationMenuList>
        <NavigationMenuItem>
          <NavigationMenuTrigger>Products</NavigationMenuTrigger>
          <NavigationMenuContent>
            <NavigationMenuLink href="/analytics">Analytics</NavigationMenuLink>
          </NavigationMenuContent>
        </NavigationMenuItem>
        <NavigationMenuItem>
          <NavigationMenuLink href="/pricing">Pricing</NavigationMenuLink>
        </NavigationMenuItem>
      </NavigationMenuList>
      <NavigationMenuPositioner />
    </NavigationMenu>
  );
}

Prop	Type	Default	Description
`defaultValue`	`any`	`null`	The uncontrolled value of the item that should be initially selected.
`value`	`any`	`null`	The controlled value of the navigation menu item that should be currently open.
`onValueChange`	`(value: any) => void`	-	Callback fired when the value changes.
`delay`	`number`	`50`	How long to wait before opening the navigation menu (ms).
`closeDelay`	`number`	`50`	How long to wait before closing the navigation menu (ms).
`orientation`	`"horizontal" \| "vertical"`	`"horizontal"`	The orientation of the navigation menu.
`className`	`string`	-	Additional CSS classes.

NavigationMenuList

The container for the top-level menu items.

Prop	Type	Default	Description
`children`	`React.ReactNode`	-	`NavigationMenuItem` elements.
`className`	`string`	-	Additional CSS classes.

NavigationMenuItem

A single item in the navigation menu.

Prop	Type	Default	Description
`value`	`any`	-	A unique value that identifies this navigation menu item.
`className`	`string`	-	Additional CSS classes.

NavigationMenuTrigger

The button that opens the associated NavigationMenuContent.

Prop	Type	Default	Description
`nativeButton`	`boolean`	`true`	Whether the component renders a native `<button>` element.
`className`	`string`	-	Additional CSS classes.

NavigationMenuLink

An interactive link within the menu.

Prop	Type	Default	Description
`href`	`string`	-	The URL to link to.
`active`	`boolean`	`false`	Whether the link is the currently active page.
`closeOnClick`	`boolean`	`false`	Whether to close the navigation menu when the link is clicked.
`className`	`string`	-	Additional CSS classes.

NavigationMenuContent

The dropdown panel containing sub-links.

Prop	Type	Default	Description
`keepMounted`	`boolean`	`false`	Whether to keep the content mounted in the DOM while the popup is closed.
`className`	`string`	-	Additional CSS classes.

NavigationMenuPositioner

Positions the navigation menu against the currently active trigger.

Prop	Type	Default	Description
`side`	`"top" \| "bottom" \| "left" \| "right"`	`"bottom"`	Which side of the anchor element to align the popup against.
`sideOffset`	`number \| function`	`8`	Distance between the anchor and the popup in pixels.
`align`	`"start" \| "center" \| "end"`	`"start"`	How to align the popup relative to the specified side.
`alignOffset`	`number \| function`	`0`	Additional offset along the alignment axis in pixels.
`disableAnchorTracking`	`boolean`	`false`	Whether to disable tracking the layout shift of the anchor.
`arrowPadding`	`number`	`5`	Minimum distance between the arrow and the edge of the popup.
`anchor`	`Element \| VirtualElement \| React.RefObject<Element \| null> \| null`	-	Explicit anchor element to position against. Positions to trigger if not provided.
`collisionAvoidance`	`CollisionAvoidance Object`	-	Determines how to handle collisions.
`collisionBoundary`	`'clipping-ancestors' \| Element \| Element[] \| Rect`	`'clipping-ancestors'`	Area that the popup is confined to.
`collisionPadding`	`Padding Object \| number`	`5`	Additional space to maintain from the edge of the collision boundary.
`sticky`	`boolean`	`false`	Whether to maintain the popup in the viewport after the anchor element was scrolled out of view.
`positionMethod`	`'absolute' \| 'fixed'`	`'absolute'`	CSS positioning method to use.
`render`	`ReactElement \| function`	-	Replaces the rendered component with a custom element.
`className`	`string \| function`	-	Additional CSS classes.

NavigationMenuIndicator

An icon that indicates that the trigger button opens a menu.

Prop	Type	Default	Description
`className`	`string`	-	Additional CSS classes.

Accessibility

Built with Base UI: Ensures industry-standard accessible behaviors and keyboard navigation.
Keyboard Support: Full support for arrow keys to navigate between items, and Enter/Space to activate.
Focus Management: Focus is appropriately managed between the trigger and the dropdown content.
ARIA Roles: Uses proper ARIA roles like menubar, menuitem, and navigation out of the box.
Screen Readers: Correctly identifies expanding/collapsing states and active items for assistive technologies.

Navigation Menu

Installation

Anatomy

Usage

Examples

Simple Navigation Menu

Positioning

API Reference

NavigationMenu