Skip to main content

Starwind UI v3.0 is now available! Migration guide

On this page

Navigation Menu

View Markdown

Navigation Menu provides Runtime-backed navigation disclosure, focus management, and floating content positioning.

Installation

Usage

---
import {
  NavigationMenu,
  NavigationMenuContent,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuTrigger,
} from "@/components/starwind/navigation-menu";
---
<NavigationMenu>
  <NavigationMenuList>
    <NavigationMenuItem value="item-one">
      <NavigationMenuTrigger>Item One</NavigationMenuTrigger>
      <NavigationMenuContent>
        <NavigationMenuLink href="/docs/">Link</NavigationMenuLink>
      </NavigationMenuContent>
    </NavigationMenuItem>
  </NavigationMenuList>
</NavigationMenu>

Sizes

NavigationMenu defaults to size="md". Set size once to keep native triggers, List spacing, trigger-style Links, and portaled content aligned. Use contentSize only when the shared popup should intentionally use a different size.

Small (sm)
Medium (md)

Custom triggers

Native NavigationMenuTrigger elements merge ordinary class customization through their full recipe. With asChild, the child instead owns its complete appearance and markup; Navigation Menu adds behavior, accessibility/state attributes, and the Trigger’s consumer-provided class.

Composition

Use the following composition to build a NavigationMenu:

NavigationMenu
├── NavigationMenuList
│   ├── NavigationMenuItem
│   │   ├── NavigationMenuTrigger
│   │   └── NavigationMenuContent
│   │       ├── NavigationMenuLink
│   │       └── NavigationMenuLink
│   └── NavigationMenuItem
│       └── NavigationMenuLink
└── NavigationMenuIndicator

API Reference

Styled Component API

These props are added or materially changed by the installed styled component. Standard HTML attributes remain available through the inherited interfaces noted below. Expand a prop to see named type definitions and framework-specific imports. Follow the Primitive and Runtime links for lower-level behavior props.

Navigation Menu

Inherits nav attributes. Omits `defaultValue`, `onChange`, and `value`.

Contains the following additional props:

Prop Type Default Toggle details
align "start" | "center" | "end" "start"
Description
Aligns the component within its available axis.
Classification
Wrapper prop
alignOffset number 0
Description
Offsets the component from its selected alignment in pixels.
Classification
Wrapper prop
avoidCollisions boolean true
Description
Repositions floating content to keep it inside the collision boundary.
Classification
Wrapper prop
collisionPadding number 8
Description
Sets the minimum space retained around a collision boundary.
Classification
Wrapper prop
contentSize "sm" | "md" size
Description
Sets the independently portaled popup content size and defaults to the resolved Navigation Menu size.
Classification
Wrapper prop
side "top" | "right" | "bottom" | "left" "bottom"
Description
Selects the preferred side for floating content.
Classification
Wrapper prop
sideOffset number 8
Description
Sets the distance in pixels between floating content and its anchor.
Classification
Wrapper prop
size "sm" | "md" "md"
Description
Sets the visual size of native styled triggers, List spacing, indicators, and top-level Links using navigationMenuTriggerStyle().
Classification
Wrapper prop

Navigation Menu Item

Inherits li attributes.

Contains the following additional props:

Prop Type Default Toggle details
value string —
Description
Controls or identifies the component value.
Classification
Wrapper prop

Navigation Menu Trigger

Inherits button attributes.

Contains the following additional props:

Prop Type Default Toggle details
asChild boolean false
Description
Delegates markup and complete visual ownership to the child while retaining Navigation Menu behavior and accessibility wiring.
Classification
Primitive override
Primitive prop
navigation-menu.Trigger.asChild
closeDelay number —
Description
Sets the delay in milliseconds before closing.
Classification
Primitive override
Primitive prop
navigation-menu.Trigger.closeDelay
iconClass string —
Description
Adds classes to the component's generated icon.
Classification
Wrapper prop
openDelay number —
Description
Sets the delay in milliseconds before opening.
Classification
Primitive override
Primitive prop
navigation-menu.Trigger.openDelay
showIcon boolean true
Description
Shows the component's generated icon.
Classification
Wrapper prop

Navigation Menu Positioner

Inherits div attributes.

Contains the following additional props:

Prop Type Default Toggle details
sideOffset number 8
Description
Sets the distance in pixels between floating content and its anchor.
Classification
Primitive override
Primitive prop
navigation-menu.Positioner.sideOffset
size "sm" | "md" "md"
Description
Sets the popup content size when rendering NavigationMenuPositioner directly.
Classification
Wrapper prop

Primitive And Runtime API

Use these references when you need the lower-level behavior APIs behind Navigation Menu.

Runtime API

Navigation Menu primitive
createNavigationMenu from @starwind-ui/runtime/navigation-menu

Changelog

v1.1.1

  • Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

v1.1.0

  • Added root sm and md sizing plus independent contentSize control for the shared portaled popup. Omitted contentSize follows the resolved root size.
  • Corrected styled NavigationMenuTrigger asChild ownership: the composed child now keeps its own complete appearance and markup. Style and size the child directly, and add any desired icon inside it; Navigation Menu still supplies behavior and accessibility wiring.

v1.0.0

  • Added the Runtime-backed Navigation Menu with keyboard navigation and shared viewport behavior.
  • See the Navigation Menu Primitive for the underlying unstyled anatomy and behavior API.