# Navigation Menu

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

NavigationMenu,
NavigationMenuContent,
NavigationMenuItem,
NavigationMenuLink,
NavigationMenuList,
NavigationMenuTrigger,
navigationMenuTriggerStyle,
} from "@/components/starwind/navigation-menu";

export const components = [
{
title: "Alert Dialog",
href: "/docs/components/alert-dialog/",
description:
  "A modal dialog that interrupts the user with important content and expects a response.",
},
{
title: "Hover Card",
href: "/docs/components/hover-card/",
description: "For sighted users to preview content available behind a link.",
},
{
title: "Progress",
href: "/docs/components/progress/",
description: "Displays an indicator showing the completion progress of a task.",
},
{
title: "Scroll Area",
href: "/docs/components/scroll-area/",
description: "Augments native scroll functionality for custom, cross-browser styling.",
},
{
title: "Tabs",
href: "/docs/components/tabs/",
description: "A set of layered sections of content displayed one at a time.",
},
{
title: "Tooltip",
href: "/docs/components/tooltip/",
description: "A popup that provides information when an element is focused or hovered.",
},
];

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import {
  NavigationMenu,
  NavigationMenuContent,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuTrigger,
  navigationMenuTriggerStyle,
} from "@/components/starwind/navigation-menu";
import AlertCircle from "@tabler/icons/outline/alert-circle.svg";
import CircleCheck from "@tabler/icons/outline/circle-check.svg";
import CircleDashed from "@tabler/icons/outline/circle-dashed.svg";

const components = [
  {
    title: "Alert Dialog",
    href: "/docs/components/alert-dialog/",
    description:
      "A modal dialog that interrupts the user with important content and expects a response.",
  },
  {
    title: "Hover Card",
    href: "/docs/components/hover-card/",
    description: "For sighted users to preview content available behind a link.",
  },
  {
    title: "Progress",
    href: "/docs/components/progress/",
    description: "Displays an indicator showing the completion progress of a task.",
  },
  {
    title: "Scroll Area",
    href: "/docs/components/scroll-area/",
    description: "Augments native scroll functionality for custom, cross-browser styling.",
  },
  {
    title: "Tabs",
    href: "/docs/components/tabs/",
    description: "A set of layered sections of content displayed one at a time.",
  },
  {
    title: "Tooltip",
    href: "/docs/components/tooltip/",
    description: "A popup that provides information when an element is focused or hovered.",
  },
];
---

<NavigationMenu aria-label="Documentation navigation">
  <NavigationMenuList>
    <NavigationMenuItem value="getting-started">
      <NavigationMenuTrigger>Getting started</NavigationMenuTrigger>
      <NavigationMenuContent>
        <ul class="w-96">
          <li>
            <NavigationMenuLink href="/docs/getting-started/introduction/">
              <div class="flex flex-col gap-1 text-sm">
                <div class="leading-none font-medium">Introduction</div>
                <div class="text-muted-foreground line-clamp-2">
                  Reusable components built with Tailwind CSS.
                </div>
              </div>
            </NavigationMenuLink>
          </li>
          <li>
            <NavigationMenuLink href="/docs/getting-started/installation/">
              <div class="flex flex-col gap-1 text-sm">
                <div class="leading-none font-medium">Installation</div>
                <div class="text-muted-foreground line-clamp-2">
                  How to install dependencies and structure your app.
                </div>
              </div>
            </NavigationMenuLink>
          </li>
          <li>
            <NavigationMenuLink href="/docs/getting-started/theming/">
              <div class="flex flex-col gap-1 text-sm">
                <div class="leading-none font-medium">Theming</div>
                <div class="text-muted-foreground line-clamp-2">
                  Customize colors, typography, and design tokens.
                </div>
              </div>
            </NavigationMenuLink>
          </li>
        </ul>
      </NavigationMenuContent>
    </NavigationMenuItem>
    <NavigationMenuItem value="components" class="hidden md:flex">
      <NavigationMenuTrigger>Components</NavigationMenuTrigger>
      <NavigationMenuContent>
        <ul class="grid w-[400px] gap-2 md:w-[500px] md:grid-cols-2 lg:w-[600px]">
          {components.map((component) => (
            <li>
              <NavigationMenuLink href={component.href}>
                <div class="flex flex-col gap-1 text-sm">
                  <div class="leading-none font-medium">{component.title}</div>
                  <div class="text-muted-foreground line-clamp-2">
                    {component.description}
                  </div>
                </div>
              </NavigationMenuLink>
            </li>
          ))}
        </ul>
      </NavigationMenuContent>
    </NavigationMenuItem>
    <NavigationMenuItem value="status">
      <NavigationMenuTrigger>With icon</NavigationMenuTrigger>
      <NavigationMenuContent>
        <ul class="grid w-[200px]">
          <li>
            <NavigationMenuLink href="#backlog" class="flex-row items-center gap-2">
              <AlertCircle />Backlog
            </NavigationMenuLink>
            <NavigationMenuLink href="#to-do" class="flex-row items-center gap-2">
              <CircleDashed />To Do
            </NavigationMenuLink>
            <NavigationMenuLink href="#done" class="flex-row items-center gap-2">
              <CircleCheck />Done
            </NavigationMenuLink>
          </li>
        </ul>
      </NavigationMenuContent>
    </NavigationMenuItem>
    <NavigationMenuItem>
      <NavigationMenuLink href="/docs/" class={navigationMenuTriggerStyle()}>
        Docs
      </NavigationMenuLink>
    </NavigationMenuItem>
  </NavigationMenuList>
</NavigationMenu>
```
  </div>
  <div slot="react">
```tsx
import {
      NavigationMenu,
      NavigationMenuContent,
      NavigationMenuItem,
      NavigationMenuLink,
      NavigationMenuList,
      NavigationMenuTrigger,
      navigationMenuTriggerStyle,
    } from "@/components/starwind/navigation-menu";
    import {
      IconAlertCircle as AlertCircle,
      IconCircleCheck as CircleCheck,
      IconCircleDashed as CircleDashed,
    } from "@tabler/icons-react";

    const components = [
      {
        title: "Alert Dialog",
        href: "/docs/components/alert-dialog/",
        description:
          "A modal dialog that interrupts the user with important content and expects a response.",
      },
      {
        title: "Hover Card",
        href: "/docs/components/hover-card/",
        description: "For sighted users to preview content available behind a link.",
      },
      {
        title: "Progress",
        href: "/docs/components/progress/",
        description: "Displays an indicator showing the completion progress of a task.",
      },
      {
        title: "Scroll Area",
        href: "/docs/components/scroll-area/",
        description: "Augments native scroll functionality for custom, cross-browser styling.",
      },
      {
        title: "Tabs",
        href: "/docs/components/tabs/",
        description: "A set of layered sections of content displayed one at a time.",
      },
      {
        title: "Tooltip",
        href: "/docs/components/tooltip/",
        description: "A popup that provides information when an element is focused or hovered.",
      },
    ];

export function Example() {
  return (
    <>
      <NavigationMenu aria-label="Documentation navigation">
            <NavigationMenuList>
              <NavigationMenuItem value="getting-started">
                <NavigationMenuTrigger>Getting started</NavigationMenuTrigger>
                <NavigationMenuContent>
                  <ul className="w-96">
                    <li>
                      <NavigationMenuLink href="/docs/getting-started/introduction/">
                        <div className="flex flex-col gap-1 text-sm">
                          <div className="leading-none font-medium">Introduction</div>
                          <div className="text-muted-foreground line-clamp-2">
                            Reusable components built with Tailwind CSS.
                          </div>
                        </div>
                      </NavigationMenuLink>
                    </li>
                    <li>
                      <NavigationMenuLink href="/docs/getting-started/installation/">
                        <div className="flex flex-col gap-1 text-sm">
                          <div className="leading-none font-medium">Installation</div>
                          <div className="text-muted-foreground line-clamp-2">
                            How to install dependencies and structure your app.
                          </div>
                        </div>
                      </NavigationMenuLink>
                    </li>
                    <li>
                      <NavigationMenuLink href="/docs/getting-started/theming/">
                        <div className="flex flex-col gap-1 text-sm">
                          <div className="leading-none font-medium">Theming</div>
                          <div className="text-muted-foreground line-clamp-2">
                            Customize colors, typography, and design tokens.
                          </div>
                        </div>
                      </NavigationMenuLink>
                    </li>
                  </ul>
                </NavigationMenuContent>
              </NavigationMenuItem>
              <NavigationMenuItem value="components" className="hidden md:flex">
                <NavigationMenuTrigger>Components</NavigationMenuTrigger>
                <NavigationMenuContent>
                  <ul className="grid w-[400px] gap-2 md:w-[500px] md:grid-cols-2 lg:w-[600px]">
                    {components.map((component) => (
                      <li key={`${component.href}-${component.title}`}>
                        <NavigationMenuLink href={component.href}>
                          <div className="flex flex-col gap-1 text-sm">
                            <div className="leading-none font-medium">{component.title}</div>
                            <div className="text-muted-foreground line-clamp-2">
                              {component.description}
                            </div>
                          </div>
                        </NavigationMenuLink>
                      </li>
                    ))}
                  </ul>
                </NavigationMenuContent>
              </NavigationMenuItem>
              <NavigationMenuItem value="status">
                <NavigationMenuTrigger>With icon</NavigationMenuTrigger>
                <NavigationMenuContent>
                  <ul className="grid w-[200px]">
                    <li>
                      <NavigationMenuLink href="#backlog" className="flex-row items-center gap-2">
                        <AlertCircle />Backlog
                      </NavigationMenuLink>
                      <NavigationMenuLink href="#to-do" className="flex-row items-center gap-2">
                        <CircleDashed />To Do
                      </NavigationMenuLink>
                      <NavigationMenuLink href="#done" className="flex-row items-center gap-2">
                        <CircleCheck />Done
                      </NavigationMenuLink>
                    </li>
                  </ul>
                </NavigationMenuContent>
              </NavigationMenuItem>
              <NavigationMenuItem>
                <NavigationMenuLink href="/docs/" className={navigationMenuTriggerStyle()}>
                  Docs
                </NavigationMenuLink>
              </NavigationMenuItem>
            </NavigationMenuList>
          </NavigationMenu>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add navigation-menu
```

## Usage

```astro
```

```astro
<NavigationMenu>
  <NavigationMenuList>
    <NavigationMenuItem value="item-one">
      <NavigationMenuTrigger>Item One</NavigationMenuTrigger>
      <NavigationMenuContent>
        <NavigationMenuLink href="/docs/">Link</NavigationMenuLink>
      </NavigationMenuContent>
    </NavigationMenuItem>
  </NavigationMenuList>
</NavigationMenu>
```

## Composition

Use the following composition to build a `NavigationMenu`:

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

## Framework Availability
Navigation Menu is available for Astro and React.
Astro available; React available
| Framework | Status | Notes |
| --- | --- | --- |
| Astro | available | - |
| React | available | - |
## API Reference
### NavigationMenu
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `align` | `"start" \| "center" \| "end"` | No | `"start"` | Wrapper prop | Aligns the component within its available axis. |
| `alignOffset` | `number` | No | `0` | Wrapper prop | Offsets the component from its selected alignment in pixels. |
| `avoidCollisions` | `boolean` | No | `true` | Wrapper prop | Repositions floating content to keep it inside the collision boundary. |
| `collisionPadding` | `number` | No | `8` | Wrapper prop | Sets the minimum space retained around a collision boundary. |
| `side` | `"top" \| "right" \| "bottom" \| "left"` | No | `"bottom"` | Wrapper prop | Selects the preferred side for floating content. |
| `sideOffset` | `number` | No | `8` | Wrapper prop | Sets the distance in pixels between floating content and its anchor. |
- Inherits nav attributes. Omits `defaultValue`, `onChange`, and `value`.

### NavigationMenuList
- Inherits ul attributes.

### NavigationMenuItem
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `value` | `string` | No | - | Wrapper prop | Controls or identifies the component value. |
- Inherits li attributes.

### NavigationMenuTrigger
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `asChild` | `boolean` | No | `false` | Primitive override | Merges the component behavior and props into its child element. |
| `closeDelay` | `number` | No | - | Primitive override | Sets the delay in milliseconds before closing. |
| `iconClass` | `string` | No | - | Wrapper prop | Adds classes to the component's generated icon. |
| `openDelay` | `number` | No | - | Primitive override | Sets the delay in milliseconds before opening. |
| `showIcon` | `boolean` | No | `true` | Wrapper prop | Shows the component's generated icon. |
- Inherits button attributes.

### NavigationMenuIndicator
- Inherits span attributes.

### NavigationMenuContent
- Inherits div attributes.

### NavigationMenuLink
- Inherits a attributes.

### NavigationMenuPositioner
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `sideOffset` | `number` | No | `8` | Primitive override | Sets the distance in pixels between floating content and its anchor. |
- Inherits div attributes.
### Primitive And Runtime API
Behavior, state, events, form participation, and imperative methods are documented in the lower-level references.
- Primitive: [Navigation Menu Primitive](/docs/primitives/navigation-menu/)
- Runtime factory: [`createNavigationMenu`](/docs/runtime/#create-navigation-menu) from `@starwind-ui/runtime/navigation-menu`

## Changelog

### v1.0.0

- Added the Runtime-backed Navigation Menu with keyboard navigation and shared viewport behavior.
- See the [Navigation Menu Primitive](/docs/primitives/navigation-menu/) for the underlying unstyled anatomy and behavior API.