Navigation Menu Primitive

View Markdown

Navigation Menu coordinates a single active top-level item, shared viewport content, hover timing, keyboard movement, and link close behavior for site navigation. Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.

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

React

Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.

value
defaultValue
onValueChange

Astro

Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.

value
defaultValue
starwind:value-change
setValue

Runtime / HTML

Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates.

data-default-value
starwind:value-change
setValue

defaultValue string | null null

Description

Sets the initial uncontrolled active item value.

Kind

control

Targets

root

Full type

string | null

React

Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.

value
defaultValue
onValueChange

Astro

Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.

value
defaultValue
starwind:value-change
setValue

Runtime / HTML

Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates.

data-default-value
starwind:value-change
setValue

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 Navigation Menu when Escape is pressed.
Kind: option
Targets: -
Full type: boolean

closeOnOutsideInteract boolean true

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

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

Description

Runs when the Navigation Menu value changes.

Kind

callback

Targets

Full type

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

React

Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.

value
defaultValue
onValueChange

Astro

Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.

value
defaultValue
starwind:value-change
setValue

Runtime / HTML

Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates.

data-default-value
starwind:value-change
setValue

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 Navigation Menu.

DOM event

starwind:value-change

Details type

NavigationMenuValueChangeDetails

Timing

before-state-commit

Cancelable

Yes

Cancellation sequence

Check internal eligibility and intent.
Create one details object for the proposal.
Call the Runtime callback with the details object when the controller exposes one.
Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.
Read details.isCanceled, including cancellation caused by preventDefault().
Apply the accepted state.
Notify Runtime subscribers and other accepted-only observers.

State

State Type Props

value string | null value / defaultValue

Description

Tracks the current Navigation Menu value.

Initial attribute

data-default-value

Runtime getter

getValue

Runtime setter

setValue

React

Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.

value
defaultValue
onValueChange

Astro

Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.

value
defaultValue
starwind:value-change
setValue

Runtime / HTML

Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates.

data-default-value
starwind:value-change
setValue

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 Navigation Menu 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 Navigation Menu collection.

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

Props

Prop Type Default

value string -

Description

Controls the current Navigation Menu value.

Kind

option

Targets

item

Full type

string

React

Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.

value
defaultValue
onValueChange

Astro

Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.

value
defaultValue
starwind:value-change
setValue

Runtime / HTML

Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates.

data-default-value
starwind:value-change
setValue

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 Navigation Menu.

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 Navigation Menu 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 Navigation Menu 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 Navigation Menu.

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 Navigation Menu content.
Kind: option
Targets: positioner, popup
Full type: "top" | "right" | "bottom" | "left"

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

Description: Sets how Navigation Menu 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 Navigation Menu value from Runtime code.

Component Relationship

Navigation Menu Direct primitive

Changelog

View version history v1.0.0 3 releases

v1.0.0

Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.

v0.1.1

Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.

v0.1.0

Introduced navigation-menu state, keyboard interaction, indicator positioning, and shared viewport behavior.

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 Navigation Menu when Escape is pressed. Closes Navigation Menu when the user interacts outside it. (value: string | null, details: NavigationMenuValueChangeDetails) => void NavigationMenuValueChangeDetails Runs when the Navigation Menu 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 Navigation Menu 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 Navigation Menu 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 Navigation Menu content. Sets how Navigation Menu 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

Navigation Menu 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

Changelog

v1.0.0

v0.1.1

v0.1.0