On this page

NavigationMenu Primitive

Navigation Menu coordinates a single active top-level item, shared viewport content, hover timing, keyboard movement, and link close behavior for site navigation.

Usage Guidelines

Use Navigation Menu for top-level site or product navigation. Use it when a row or column of triggers reveals rich panels that share one viewport.
Use Menu or Popover for isolated actions. Navigation Menu is value-driven and viewport-driven, so it is heavier than a single contextual popup.

Anatomy

Use the Astro primitive adapter to render NavigationMenu anatomy with the Runtime wiring included.

---
import { NavigationMenu } from "@starwind-ui/astro/navigation-menu";
---

<NavigationMenu.Root>
  <NavigationMenu.List>
    <NavigationMenu.Item value="products">
      <NavigationMenu.Trigger>
        <NavigationMenu.Icon>v</NavigationMenu.Icon>
      </NavigationMenu.Trigger>
      <NavigationMenu.Content>
        <NavigationMenu.Link href="/docs">Docs</NavigationMenu.Link>
      </NavigationMenu.Content>
    </NavigationMenu.Item>
  </NavigationMenu.List>
  <NavigationMenu.Portal>
    <NavigationMenu.Positioner>
      <NavigationMenu.Popup>
        <NavigationMenu.Viewport />
        <NavigationMenu.Arrow />
      </NavigationMenu.Popup>
    </NavigationMenu.Positioner>
  </NavigationMenu.Portal>
</NavigationMenu.Root>

Use the React primitive adapter when NavigationMenu state participates in React rendering.

import { NavigationMenu } from "@starwind-ui/react/navigation-menu";

export function Example() {
  return (
    <NavigationMenu.Root>
      <NavigationMenu.List>
        <NavigationMenu.Item value="products">
          <NavigationMenu.Trigger>
            <NavigationMenu.Icon>v</NavigationMenu.Icon>
          </NavigationMenu.Trigger>
          <NavigationMenu.Content>
            <NavigationMenu.Link href="/docs">Docs</NavigationMenu.Link>
          </NavigationMenu.Content>
        </NavigationMenu.Item>
      </NavigationMenu.List>
      <NavigationMenu.Portal>
        <NavigationMenu.Positioner>
          <NavigationMenu.Popup>
            <NavigationMenu.Viewport />
            <NavigationMenu.Arrow />
          </NavigationMenu.Popup>
        </NavigationMenu.Positioner>
      </NavigationMenu.Portal>
    </NavigationMenu.Root>
  );
}

Render the NavigationMenu data-sw-* contract yourself, then initialize createNavigationMenu.

<nav data-sw-nav-menu>
  <ul data-sw-nav-menu-list>
    <li data-sw-nav-menu-item data-value="products">
      <button data-sw-nav-menu-trigger type="button" aria-haspopup="menu">
        <span data-sw-nav-menu-icon aria-hidden="true">v</span>
      </button>
      <div data-sw-nav-menu-content hidden>
        <a data-sw-nav-menu-link href="/docs">Docs</a>
      </div>
    </li>
  </ul>
  <div data-sw-nav-menu-portal>
    <div data-sw-nav-menu-positioner>
      <div data-sw-nav-menu-popup hidden>
        <div data-sw-nav-menu-viewport hidden></div>
        <div data-sw-nav-menu-arrow aria-hidden="true"></div>
      </div>
    </div>
  </div>
</nav>

<script type="module">
  import { createNavigationMenu } from "@starwind-ui/runtime/navigation-menu";

  const root = document.querySelector("[data-sw-nav-menu]");
  if (root) {
    createNavigationMenu(root);
  }
</script>

Shared Viewport

Content panels are authored inside items, then moved into the shared viewport while active so the popup can animate size and direction consistently.

Floating Behavior

Fact	Value
Anchor part	trigger
Positioner part	positioner
Popup part	popup
Portal part	portal
Option props	side, align, sideOffset, alignOffset, avoidCollisions, collisionPadding

API Reference

Root

The navigation landmark that owns the active value, orientation, hover timing, dismissal options, and Runtime instance.

Default element: nav
Discovery hook: data-sw-nav-menu
Role: -

Props

Prop Type Default

value string | null -

Description: Controls the active item value when a framework adapter owns state.
Kind: control
Targets: root
Full type: string | null

defaultValue string | null null

Description: Sets the initial uncontrolled active item value.
Kind: control
Targets: root
Full type: string | null

openDelay number 50

Description: Sets the default hover-open delay in milliseconds.
Kind: option
Targets: root, trigger
Full type: number

closeDelay number 50

Description: Sets the default hover-close delay in milliseconds.
Kind: option
Targets: root, trigger
Full type: number

closeOnEscape boolean true

Description: Closes NavigationMenu when Escape is pressed.
Kind: option
Targets: -
Full type: boolean

closeOnOutsideInteract boolean true

Description: Closes NavigationMenu when the user interacts outside it.
Kind: option
Targets: -
Full type: boolean

onValueChange (value: string | null, details: NavigationMenuValueChangeDetails) => void -

Description: Runs when the NavigationMenu value changes.
Kind: callback
Targets: -
Full type: (value: string | null, details: NavigationMenuValueChangeDetails) => void

orientation "horizontal" | "vertical" "horizontal"

Description: Sets horizontal or vertical trigger keyboard movement.
Kind: option
Targets: root
Full type: "horizontal" | "vertical"

Events

Event Callback Value

valueChange onValueChange value: string | null

Description: Fires when the value changes for NavigationMenu.
DOM event: starwind:value-change
Details type: NavigationMenuValueChangeDetails
Timing: before-state-commit
Cancelable: Yes

State

State Type Props

value string | null value / defaultValue

Description: Tracks the current NavigationMenu value.
Initial attribute: data-default-value
Runtime getter: getValue
Runtime setter: setValue
State control support: React supports controlled and default state with value and defaultValue props. Runtime/HTML reads initial state from data-default-value, emits starwind:value-change, and updates with setValue. Astro adapters render initial/default state, but do not expose reactive controlled-state props for this state.

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-nav-menu - Runtime discovery hook for the Navigation Menu root.

State

Attribute Value Description

data-state - Reflects whether any item is open.

Metadata

Attribute Value Description

data-value - Reflects the value prop on the Root part.

data-controlled-value - Reflects the controlled value prop on the Root part.

data-default-value - Initial uncontrolled active item value.

data-open-delay - Reflects the open delay prop on the Root part.

data-close-delay - Reflects the close delay prop on the Root part.

data-close-on-escape - Reflects the close on escape prop on the Root part.

data-close-on-outside-interact - Reflects the close on outside interact prop on the Root part.

data-orientation - Reflects the orientation prop on the Root part.

List

The list of selectable NavigationMenu items.

Default element: ul
Discovery hook: data-sw-nav-menu-list
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-nav-menu-list - Marks the List part so Starwind Runtime can find it.

Item

An interactive item inside the NavigationMenu collection.

Default element: li
Discovery hook: data-sw-nav-menu-item
Role: -

Props

Prop Type Default

value string -

Description: Controls the current NavigationMenu value.
Kind: option
Targets: item
Full type: string

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-nav-menu-item - Marks the Item part so Starwind Runtime can find it.

State

Attribute Value Description

data-state - Reflects the current state on the Item part.

Metadata

Attribute Value Description

data-value - Reflects the value prop on the Item part.

Trigger

The button or asChild control that opens, closes, and keyboard-targets a content panel.

Default element: button
Discovery hook: data-sw-nav-menu-trigger
Role: -

Props

Prop Type Default

openDelay number 50

Description: Overrides root hover-open timing for this trigger.
Kind: option
Targets: root, trigger
Full type: number

closeDelay number 50

Description: Overrides root hover-close timing for this trigger.
Kind: option
Targets: root, trigger
Full type: number

asChild boolean -

Description: Merges trigger behavior into the slotted child control.
Kind: rendering
Targets: trigger
Full type: boolean

disabled boolean false

Description: Prevents trigger interaction and removes it from roving trigger movement.
Kind: option
Targets: trigger
Full type: boolean

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-nav-menu-trigger - Runtime discovery hook for the trigger part.

State

Attribute Value Description

data-state - Reflects whether this trigger's item is open.

Metadata

Attribute Value Description

data-as-child - Reflects the as child prop on the Trigger part.

data-open-delay - Reflects the open delay prop on the Trigger part.

data-close-delay - Reflects the close delay prop on the Trigger part.

data-disabled - Reflects the disabled prop on the Trigger part.

Icon

Decorative icon rendered by NavigationMenu.

Default element: span
Discovery hook: data-sw-nav-menu-icon
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-nav-menu-icon - Marks the Icon part so Starwind Runtime can find it.

State

Attribute Value Description

data-state - Reflects the current state on the Icon part.

Content

The authored item panel. The Runtime moves the active content into the shared viewport.

Default element: div
Discovery hook: data-sw-nav-menu-content
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-nav-menu-content - Runtime discovery hook for the content part.

State

Attribute Value Description

data-state - Reflects whether this content panel is active.

Link

A navigation link inside content. Links close the active menu by default and can mark current-page state.

Default element: a
Discovery hook: data-sw-nav-menu-link
Role: -

Props

Prop Type Default

href string -

Description: Sets the href attribute on the Link part.
Kind: attribute
Targets: link
Full type: string

active boolean false

Description: Marks the link as active and sets aria-current.
Kind: option
Targets: link
Full type: boolean

closeOnClick boolean true

Description: Controls whether clicking the link closes the menu.
Kind: option
Targets: link
Full type: boolean

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-nav-menu-link - Runtime discovery hook for the link part.

Metadata

Attribute Value Description

data-active - Present when the link is active.

data-close-on-click - Set to false to keep the menu open after link activation.

Portal

Moves NavigationMenu overlay content to the document body when needed.

Default element: div
Discovery hook: data-sw-nav-menu-portal
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-nav-menu-portal - Marks the Portal part so Starwind Runtime can find it.

Positioner

The floating positioning part for the shared popup.

Default element: div
Discovery hook: data-sw-nav-menu-positioner
Role: -

Props

Prop Type Default

side "top" | "right" | "bottom" | "left" "bottom"

Description: Sets the preferred side for the popup.
Kind: option
Targets: positioner, popup
Full type: "top" | "right" | "bottom" | "left"

align "start" | "center" | "end" "start"

Description: Sets popup alignment relative to the active trigger.
Kind: option
Targets: positioner, popup
Full type: "start" | "center" | "end"

sideOffset number 4

Description: Sets the distance between the popup and trigger.
Kind: option
Targets: positioner
Full type: number

alignOffset number 0

Description: Adjusts the cross-axis alignment offset for NavigationMenu content.
Kind: option
Targets: positioner
Full type: number

avoidCollisions boolean true

Description: Allows the popup to shift or flip to remain visible.
Kind: option
Targets: positioner
Full type: boolean

collisionPadding number 8

Description: Configures the collision padding option for the Positioner part.
Kind: option
Targets: positioner
Full type: number

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-nav-menu-positioner - Runtime discovery hook for the positioner part.

State

Attribute Value Description

data-state - Reflects the current state on the Positioner part.

Metadata

Attribute Value Description

data-side - Reflects the resolved floating side.

data-align - Reflects the resolved floating alignment.

data-side-offset - Reflects the side offset prop on the Positioner part.

data-align-offset - Reflects the align offset prop on the Positioner part.

data-avoid-collisions - Reflects the avoid collisions prop on the Positioner part.

data-collision-padding - Reflects the collision padding prop on the Positioner part.

The floating content container for NavigationMenu.

Default element: div
Discovery hook: data-sw-nav-menu-popup
Role: -

Props

Prop Type Default

side "top" | "right" | "bottom" | "left" "bottom"

Description: Sets the preferred side for NavigationMenu content.
Kind: option
Targets: positioner, popup
Full type: "top" | "right" | "bottom" | "left"

align "start" | "center" | "end" "start"

Description: Sets how NavigationMenu content aligns to its trigger.
Kind: option
Targets: positioner, popup
Full type: "start" | "center" | "end"

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-nav-menu-popup - Marks the Popup part so Starwind Runtime can find it.

State

Attribute Value Description

data-state - Reflects the current state on the Popup part.

Metadata

Attribute Value Description

data-side - Reflects the side prop on the Popup part.

data-align - Reflects the align prop on the Popup part.

Viewport

The shared visible container that receives active item content and carries measured size state.

Default element: div
Discovery hook: data-sw-nav-menu-viewport
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-nav-menu-viewport - Runtime discovery hook for the viewport part.

State

Attribute Value Description

data-state - Reflects whether any content is visible.

Arrow

The arrow element that visually points to the trigger.

Default element: div
Discovery hook: data-sw-nav-menu-arrow
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-nav-menu-arrow - Marks the Arrow part so Starwind Runtime can find it.

State

Attribute Value Description

data-state - Reflects the current state on the Arrow part.

Runtime API

Factory: createNavigationMenu
Import: @starwind-ui/runtime/navigation-menu
Root hook: root data-sw-nav-menu
Option props: closeDelay, closeOnEscape, closeOnOutsideInteract, defaultValue, onValueChange, openDelay, value

Option Lifecycles

Option	Lifecycle
closeDelay	constructor-only
closeOnEscape	constructor-only
closeOnOutsideInteract	constructor-only
defaultValue	constructor-only
onValueChange	constructor-only
openDelay	constructor-only
value	setter-backed

Runtime Setters

Method Target Description

setValue state: value Updates the current NavigationMenu value from Runtime code.

Component Relationship

Navigation Menu Direct primitive

Layer Metadata

Navigation Menu Primitive uses createNavigationMenu. Styled components: Navigation Menu.

primitive Navigation Menu Primitive Navigation Menu Primitive uses createNavigationMenu. Styled components: Navigation Menu. Runtime primitive Primitive adapter Astro Primitive adapters React Primitive adapters navigation-menu Navigation Menu Floating Value Control Value controls with popup selection surfaces and floating placement. /docs/primitives/navigation-menu/ createNavigationMenu @starwind-ui/runtime/navigation-menu /docs/runtime/#create-navigation-menu root closeDelay closeOnEscape closeOnOutsideInteract defaultValue onValueChange openDelay value raw-html astro react solid svelte vue HTML Astro React Solid Svelte Vue Raw HTML Render the NavigationMenu data-sw-* contract yourself, then initialize createNavigationMenu. html Use the Astro primitive adapter to render NavigationMenu anatomy with the Runtime wiring included. Use the React primitive adapter when NavigationMenu state participates in React rendering. tsx nav data-sw-nav-menu string | null Controls the active item value when a framework adapter owns state. Sets the initial uncontrolled active item value. number Sets the default hover-open delay in milliseconds. Sets the default hover-close delay in milliseconds. boolean Closes NavigationMenu when Escape is pressed. Closes NavigationMenu when the user interacts outside it. (value: string | null, details: NavigationMenuValueChangeDetails) => void NavigationMenuValueChangeDetails Runs when the NavigationMenu value changes. orientation "horizontal" | "vertical" Sets horizontal or vertical trigger keyboard movement. runtime Runtime discovery hook for the Navigation Menu root. data-value prop Reflects the value prop on the Root part. data-controlled-value Reflects the controlled value prop on the Root part. data-default-value Initial uncontrolled active item value. data-open-delay Reflects the open delay prop on the Root part. data-close-delay Reflects the close delay prop on the Root part. data-close-on-escape Reflects the close on escape prop on the Root part. data-close-on-outside-interact Reflects the close on outside interact prop on the Root part. data-orientation Reflects the orientation prop on the Root part. data-state state Reflects whether any item is open. getValue setValue valueChange starwind:value-change list ul data-sw-nav-menu-list Marks the List part so Starwind Runtime can find it. item li data-sw-nav-menu-item string Controls the current NavigationMenu value. Marks the Item part so Starwind Runtime can find it. Reflects the value prop on the Item part. Reflects the current state on the Item part. trigger button data-sw-nav-menu-trigger Overrides root hover-open timing for this trigger. Overrides root hover-close timing for this trigger. asChild Merges trigger behavior into the slotted child control. disabled Prevents trigger interaction and removes it from roving trigger movement. Runtime discovery hook for the trigger part. data-as-child Reflects the as child prop on the Trigger part. Reflects the open delay prop on the Trigger part. Reflects the close delay prop on the Trigger part. data-disabled Reflects the disabled prop on the Trigger part. Reflects whether this trigger's item is open. icon span data-sw-nav-menu-icon Marks the Icon part so Starwind Runtime can find it. Reflects the current state on the Icon part. content div data-sw-nav-menu-content Runtime discovery hook for the content part. Reflects whether this content panel is active. link a data-sw-nav-menu-link href Sets the href attribute on the Link part. active Marks the link as active and sets aria-current. closeOnClick Controls whether clicking the link closes the menu. Runtime discovery hook for the link part. data-active Present when the link is active. data-close-on-click Set to false to keep the menu open after link activation. portal data-sw-nav-menu-portal Marks the Portal part so Starwind Runtime can find it. positioner data-sw-nav-menu-positioner side "top" | "right" | "bottom" | "left" Sets the preferred side for the popup. align "start" | "center" | "end" Sets popup alignment relative to the active trigger. sideOffset Sets the distance between the popup and trigger. alignOffset Adjusts the cross-axis alignment offset for NavigationMenu content. avoidCollisions Allows the popup to shift or flip to remain visible. collisionPadding Configures the collision padding option for the Positioner part. Runtime discovery hook for the positioner part. Reflects the current state on the Positioner part. data-side Reflects the resolved floating side. data-align Reflects the resolved floating alignment. data-side-offset Reflects the side offset prop on the Positioner part. data-align-offset Reflects the align offset prop on the Positioner part. data-avoid-collisions Reflects the avoid collisions prop on the Positioner part. data-collision-padding Reflects the collision padding prop on the Positioner part. popup data-sw-nav-menu-popup Sets the preferred side for NavigationMenu content. Sets how NavigationMenu content aligns to its trigger. Marks the Popup part so Starwind Runtime can find it. Reflects the current state on the Popup part. Reflects the side prop on the Popup part. Reflects the align prop on the Popup part. viewport data-sw-nav-menu-viewport Runtime discovery hook for the viewport part. Reflects whether any content is visible. arrow data-sw-nav-menu-arrow Marks the Arrow part so Starwind Runtime can find it. Reflects the current state on the Arrow part. Root List Item Trigger type aria-haspopup aria-expanded Icon aria-hidden Content hidden Link aria-current Portal Positioner Popup Viewport Arrow @starwind-ui/astro @starwind-ui/astro/navigation-menu Render static uncontrolled anatomy and self-initialize; use explicit item values for defaultValue and stable app state. Runtime treats an empty string as a valid NavigationMenuValue; open state is value !== null. Navigation Menu roots nested inside Content are intentionally not auto-initialized; use static links or lists for second-level panels. @starwind-ui/react @starwind-ui/react/navigation-menu Render static anatomy and initialize the runtime in a layout effect; controlled value is setter-backed and should use explicit item values. /docs/components/navigation-menu/ Direct primitive direct-primitive Styled component Navigation Menu

NavigationMenu Primitive

Usage Guidelines

Anatomy

Shared Viewport

Floating Behavior

API Reference

Root

Props

Events

State

Data Attributes

Runtime hooks

State

Metadata

List

Data Attributes

Runtime hooks

Item

Props

Data Attributes

Runtime hooks

State

Metadata

Trigger

Props

Data Attributes

Runtime hooks

State

Metadata

Icon

Data Attributes

Runtime hooks

State

Content

Data Attributes

Runtime hooks

State

Link

Props

Data Attributes

Runtime hooks

Metadata

Portal

Data Attributes

Runtime hooks

Positioner

Props

Data Attributes

Runtime hooks

State

Metadata

Popup

Props

Data Attributes

Runtime hooks

State

Metadata

Viewport

Data Attributes

Runtime hooks

State

Arrow

Data Attributes

Runtime hooks

State

Runtime API

Option Lifecycles

Runtime Setters

Related Styled Components