---
title: Navigation Menu
description: Navigate a website through links and animated shared panels.
package: moraine
version: 0.11.0
repository: https://github.com/subframe7536/moraine
---

# Navigation Menu

> Navigate a website through links and animated shared panels.

## Anatomy

```text
NavigationMenu [component; slot=root]
├── NavigationMenu.List [part; slot=list]
│   └── NavigationMenu.Item [part; slot=item]
│       └── NavigationMenu.Trigger [part; slot=trigger]
│           └── triggerIcon [slot]
└── NavigationMenu.Content [part; slot=content]
    └── NavigationMenu.Link [part; slot=link]
```

## Usage

Use NavigationMenu for website destinations, with direct links and expandable link panels. Use
[DropdownMenu](https://moraine.subf.dev/components/dropdown-menu.md) for a menu of actions. Use [Tabs](https://moraine.subf.dev/components/tabs.md) for
peer panels that stay on the same page.

```tsx
import { NavigationMenu } from 'moraine'

export function Example() {
  return (
    <NavigationMenu aria-label="Main navigation">
      <NavigationMenu.List>
        <NavigationMenu.Item value="products">
          <NavigationMenu.Trigger>Products</NavigationMenu.Trigger>
          <NavigationMenu.Content>
            <NavigationMenu.Link href="/overview" closeOnSelect>
              Overview
            </NavigationMenu.Link>
          </NavigationMenu.Content>
        </NavigationMenu.Item>
        <NavigationMenu.Item>
          <NavigationMenu.Link href="/docs">Documentation</NavigationMenu.Link>
        </NavigationMenu.Item>
      </NavigationMenu.List>
    </NavigationMenu>
  )
}
```

### Panels and direct links

Combine expandable panels with direct links. Use `NavigationMenu.Content` for each panel and
`NavigationMenu.Link` for its destinations; a link can also sit directly in a `NavigationMenu.Item`.
`active` marks the current page with `aria-current="page"`. `closeOnSelect` defaults to `false`;
enable it to close the panel on activation. A click handler that calls `preventDefault()` cancels
the close. A disabled link loses its `href` and gets `aria-disabled`.

```tsx
<NavigationMenu.Item value="products">
  <NavigationMenu.Trigger>Products</NavigationMenu.Trigger>
  <NavigationMenu.Content>
    <NavigationMenu.Link href="/overview" closeOnSelect>
      Overview
    </NavigationMenu.Link>
  </NavigationMenu.Content>
</NavigationMenu.Item>
<NavigationMenu.Item>
  <NavigationMenu.Link href="/docs" active>
    Documentation
  </NavigationMenu.Link>
</NavigationMenu.Item>
```

The root renders a navigation landmark. Give it an accessible name when the page has several
navigation landmarks. This version supports one level of panels.

### Controlled state

Give each item a stable `value`, then control the open item with `value` and `onValueChange`.
`onValueChange` receives the value of the item to open, or `undefined` to close, and you write it
back to `value`. A value that matches no enabled item with content leaves the menu closed, so
disabled or removed items cannot keep a panel open. For uncontrolled state, `defaultValue` opens an
item after hydration. `disabled` on the root disables every trigger and link and closes the
open panel; on an `Item` it disables only that item's trigger or direct links.

```tsx
<NavigationMenu value={value()} onValueChange={setValue} disabled={disabled()}>
  <NavigationMenu.List>
    <NavigationMenu.Item value="account">
      <NavigationMenu.Trigger>Account</NavigationMenu.Trigger>
      <NavigationMenu.Content>...</NavigationMenu.Content>
    </NavigationMenu.Item>
  </NavigationMenu.List>
</NavigationMenu>
```

### Orientation

Set `orientation="vertical"` for a vertical list. Use `placement="right"` to place its panels beside
the triggers.

```tsx
<NavigationMenu aria-label="Docs navigation" orientation="vertical" placement="right">
  <NavigationMenu.List>...</NavigationMenu.List>
</NavigationMenu>
```

### Hover timing and positioning

Panels open on hover after `openDelay` (default `50` ms) while no panel is open; hovering another
trigger while a panel is open switches immediately, and click or keyboard activation never waits.
The open panel closes `closeDelay` (default `50` ms) after the pointer leaves the menu, and stays
open while focus is inside it. `placement` (default `'bottom'`), `align` (default `'center'`),
`gutter` (default `8`), `shift`, `flip`, and `slide` position the shared panel relative to the
active trigger.

### RTL

Set `dir="rtl"` on a surrounding container for right-to-left navigation. Arrow keys follow that
direction, including the key that opens a panel from a vertical menu.

```tsx
<div dir="rtl">
  <NavigationMenu aria-label="Main navigation">
    <NavigationMenu.List>...</NavigationMenu.List>
  </NavigationMenu>
</div>
```

### Custom links

Use `linkRender` for a router's link component. Forward the supplied attributes, events, children,
object style, and ref to the anchor.

```tsx
<NavigationMenu.Link linkRender={RouterLink} href="/components/button">
  Button
</NavigationMenu.Link>
```

### Keyboard interaction

Arrow keys along the list axis move focus without opening a panel. Home and End focus the first and last enabled navigation controls. Enter and Space activate a trigger. ArrowDown opens a horizontal menu and enters its content; ArrowRight does the same for a vertical LTR menu, and ArrowLeft for RTL.

Tab and Shift+Tab preserve the order between the trigger, its portaled content and the following navigation control. Arrow keys and Home/End move between panel links, while inputs retain their editing keys. Escape closes the panel and returns focus to its trigger. Outside click and focus close the panel without taking focus away from the destination.

## Examples

### Product and docs header

Mix a two-column product panel, a shorter guides panel, and a direct Documentation link. Mark the
current page with `active`.

```tsx
import { NavigationMenu } from 'moraine'

export function Basic() {
  return (
    <div class="pt-4 flex min-h-64 w-full justify-center">
      <NavigationMenu aria-label="Example navigation">
        <NavigationMenu.List>
          <NavigationMenu.Item value="products">
            <NavigationMenu.Trigger>Products</NavigationMenu.Trigger>
            <NavigationMenu.Content>
              <div class="gap-2 grid w-[min(28rem,calc(100vw-2rem))] sm:grid-cols-2">
                <NavigationMenu.Link href="#overview" closeOnSelect>
                  <span class="font-medium">Overview</span>
                  <span class="text-muted-foreground">Explore the component library.</span>
                </NavigationMenu.Link>
                <NavigationMenu.Link href="#themes" closeOnSelect>
                  <span class="font-medium">Themes</span>
                  <span class="text-muted-foreground">Make the library fit your product.</span>
                </NavigationMenu.Link>
                <NavigationMenu.Link href="#accessibility" closeOnSelect>
                  <span class="font-medium">Accessibility</span>
                  <span class="text-muted-foreground">Keyboard and screen reader support.</span>
                </NavigationMenu.Link>
                <NavigationMenu.Link href="#getting-started" closeOnSelect>
                  <span class="font-medium">Getting started</span>
                  <span class="text-muted-foreground">Install your first component.</span>
                </NavigationMenu.Link>
              </div>
            </NavigationMenu.Content>
          </NavigationMenu.Item>
          <NavigationMenu.Item value="guides">
            <NavigationMenu.Trigger>Guides</NavigationMenu.Trigger>
            <NavigationMenu.Content>
              <div class="w-48">
                <NavigationMenu.Link href="#installation" closeOnSelect>
                  Installation
                </NavigationMenu.Link>
                <NavigationMenu.Link href="#composition" closeOnSelect>
                  Composition
                </NavigationMenu.Link>
                <NavigationMenu.Link href="#styling" closeOnSelect>
                  Styling
                </NavigationMenu.Link>
              </div>
            </NavigationMenu.Content>
          </NavigationMenu.Item>
          <NavigationMenu.Item>
            <NavigationMenu.Link href="#documentation" active>
              Documentation
            </NavigationMenu.Link>
          </NavigationMenu.Item>
        </NavigationMenu.List>
      </NavigationMenu>
    </div>
  )
}
```

### Open the account panel from page state

Drive the open item with `value` and `onValueChange`. Close with `null`. A disabled Billing item
cannot stay open.

```tsx
import { Button, NavigationMenu } from 'moraine'
import { createSignal } from 'solid-js'

export function Controlled() {
  const [value, setValue] = createSignal<string | undefined>(undefined)
  const [disabled, setDisabled] = createSignal(false)
  return (
    <div class="min-h-56 space-y-4">
      <div class="flex flex-wrap gap-2">
        <Button size="sm" variant="outline" onClick={() => setValue('account')}>
          Open account
        </Button>
        <Button size="sm" variant="outline" onClick={() => setValue(undefined)}>
          Close
        </Button>
        <Button size="sm" variant="outline" onClick={() => setDisabled((value) => !value)}>
          Toggle disabled
        </Button>
      </div>
      <NavigationMenu
        aria-label="Account navigation"
        value={value()}
        onValueChange={setValue}
        disabled={disabled()}
      >
        <NavigationMenu.List>
          <NavigationMenu.Item value="account">
            <NavigationMenu.Trigger>Account</NavigationMenu.Trigger>
            <NavigationMenu.Content>
              <div class="w-48">
                <NavigationMenu.Link href="#profile" closeOnSelect>
                  Profile
                </NavigationMenu.Link>
                <NavigationMenu.Link href="#settings" closeOnSelect>
                  Settings
                </NavigationMenu.Link>
              </div>
            </NavigationMenu.Content>
          </NavigationMenu.Item>
          <NavigationMenu.Item value="billing" disabled>
            <NavigationMenu.Trigger>Billing</NavigationMenu.Trigger>
            <NavigationMenu.Content>Billing is unavailable.</NavigationMenu.Content>
          </NavigationMenu.Item>
        </NavigationMenu.List>
      </NavigationMenu>
      <p class="text-xs text-muted-foreground">Open item: {value() ?? 'none'}</p>
    </div>
  )
}
```

### Vertical docs navigation

Stack triggers in a vertical list and place panels to the right.

```tsx
import { NavigationMenu } from 'moraine'

export function Orientation() {
  return (
    <div class="min-h-56 w-full">
      <NavigationMenu aria-label="Vertical navigation" orientation="vertical" placement="right">
        <NavigationMenu.List>
          <NavigationMenu.Item value="products">
            <NavigationMenu.Trigger>Products</NavigationMenu.Trigger>
            <NavigationMenu.Content>
              <div class="w-40">
                <NavigationMenu.Link href="#overview" closeOnSelect>
                  Overview
                </NavigationMenu.Link>
                <NavigationMenu.Link href="#features" closeOnSelect>
                  Features
                </NavigationMenu.Link>
              </div>
            </NavigationMenu.Content>
          </NavigationMenu.Item>
          <NavigationMenu.Item value="resources">
            <NavigationMenu.Trigger>Resources</NavigationMenu.Trigger>
            <NavigationMenu.Content>
              <div class="w-40">
                <NavigationMenu.Link href="#guides" closeOnSelect>
                  Guides
                </NavigationMenu.Link>
                <NavigationMenu.Link href="#support" closeOnSelect>
                  Support
                </NavigationMenu.Link>
              </div>
            </NavigationMenu.Content>
          </NavigationMenu.Item>
        </NavigationMenu.List>
      </NavigationMenu>
    </div>
  )
}
```

### Route documentation links

Forward NavigationMenu link props through Solid Router's `A`. Keep `href` on `NavigationMenu.Link`.

```tsx
import { A } from '@solidjs/router'
import { NavigationMenu } from 'moraine'
import type { NavigationMenuT } from 'moraine'

const RouterLink = (props: NavigationMenuT.LinkRenderProps) => (
  <A {...props} href={props.href ?? '#'} />
)

export function RouterLinkExample() {
  return (
    <NavigationMenu aria-label="Documentation navigation">
      <NavigationMenu.List>
        <NavigationMenu.Item>
          <NavigationMenu.Link linkRender={RouterLink} href="/components/button">
            Button
          </NavigationMenu.Link>
        </NavigationMenu.Item>
        <NavigationMenu.Item>
          <NavigationMenu.Link linkRender={RouterLink} href="/components/tabs">
            Tabs
          </NavigationMenu.Link>
        </NavigationMenu.Item>
      </NavigationMenu.List>
    </NavigationMenu>
  )
}
```

### Inherit RTL for a product header

Wrap the menu in `dir="rtl"`. Triggers, panels, and links follow the writing direction without extra
props.

```tsx
import { NavigationMenu } from 'moraine'

export function Rtl() {
  return (
    <div dir="rtl" class="min-h-56 w-full">
      <NavigationMenu aria-label="RTL navigation">
        <NavigationMenu.List>
          <NavigationMenu.Item value="products">
            <NavigationMenu.Trigger>المنتجات</NavigationMenu.Trigger>
            <NavigationMenu.Content>
              <div class="w-40">
                <NavigationMenu.Link href="#overview" closeOnSelect>
                  نظرة عامة
                </NavigationMenu.Link>
                <NavigationMenu.Link href="#features" closeOnSelect>
                  الميزات
                </NavigationMenu.Link>
              </div>
            </NavigationMenu.Content>
          </NavigationMenu.Item>
          <NavigationMenu.Item value="resources">
            <NavigationMenu.Trigger>الموارد</NavigationMenu.Trigger>
            <NavigationMenu.Content>
              <NavigationMenu.Link href="#guides" closeOnSelect>
                الأدلة
              </NavigationMenu.Link>
            </NavigationMenu.Content>
          </NavigationMenu.Item>
        </NavigationMenu.List>
      </NavigationMenu>
    </div>
  )
}
```

## API Reference

### Attributes

| Attributes | Slot | Description |
| --- | --- | --- |
| `data-disabled` | `navigation-menu`, `navigation-menu-item`, `navigation-menu-trigger`, `navigation-menu-link` | Present when the component, slot, or item is disabled. |
| `data-orientation` | `navigation-menu`, `navigation-menu-list`, `navigation-menu-content` | Stores the rendered orientation (horizontal or vertical). |
| `data-expanded` | `navigation-menu-item`, `navigation-menu-trigger`, `navigation-menu-trigger-icon`, `navigation-menu-content` | Present when the panel, accordion, or menu is expanded. |
| `data-closed` | `navigation-menu-content` | Present when disclosure or transition content is closed. |
| `data-active` | `navigation-menu-link` | Present when the item or trigger is active. |

### Props

#### NavigationMenu

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| align | 'start' \| 'center' \| 'end' \| undefined | center | Alignment of the panel relative to the active trigger: `'start'`, `'center'` or `'end'`. |
| closeDelay | number \| undefined | 50 | Delay in milliseconds between the pointer leaving the menu and the open panel closing. The<br>panel stays open while focus is inside it, and moving across the gap toward the panel is<br>tolerated. |
| defaultValue | string \| undefined | undefined | `value` of the item that is open initially when uncontrolled; omit to start closed. Ignored<br>when `value` is set. |
| disabled | boolean \| undefined | false | Disables every trigger and link in the menu: panels cannot open (an open panel closes) and<br>links lose their `href` and are marked `aria-disabled`. |
| flip | boolean \| string \| undefined | true | Whether the content moves to another side when the preferred `placement` does not fit in the<br>viewport. `false` keeps the side fixed. A string is a space-delimited list of fallback<br>placements tried in order, each `top`, `right`, `bottom` or `left`, optionally suffixed with<br>`-start` or `-end`; any other entry throws an error. |
| gutter | number \| undefined | 8 | Gap between the trigger and panel, in pixels. |
| onValueChange | ((value: string \| undefined) => void) \| undefined | — | Called with the `value` of the item that should open, or `undefined` when the menu should<br>close, after hover, click, keyboard or dismissal. It only fires when the value changes and<br>fires in controlled mode too, so a controlled menu must write it back to `value`. |
| openDelay | number \| undefined | 50 | Delay in milliseconds between a mouse pointer entering a trigger and its panel opening while<br>no panel is open. Hovering another trigger while a panel is open switches immediately, and<br>click or keyboard activation never waits. |
| orientation | 'horizontal' \| 'vertical' \| undefined | 'horizontal' | Axis of the top-level navigation list. |
| overflowPadding | number \| undefined | 4 | Padding in pixels between positioned content and the viewport boundary. |
| placement | 'top' \| 'right' \| 'bottom' \| 'left' \| undefined | 'bottom' | Side of the trigger the content opens on. The rendered side can differ when `flip` moves it to<br>fit the viewport; read it from `data-side` on the content. |
| shift | number \| undefined | 0 | Offset in pixels along the trigger edge (horizontal for `top` and `bottom` placements,<br>vertical for `left` and `right`), added to the position given by `align`. |
| slide | boolean \| undefined | true | Whether the content slides along the trigger edge (horizontally for `top` and `bottom`<br>placements, vertically for `left` and `right`) to stay inside the viewport, keeping<br>`overflowPadding` from the edge, instead of overflowing. |
| value | string \| undefined | — | Controlled `value` of the open `NavigationMenu.Item`. While `undefined` the menu is<br>uncontrolled and follows `defaultValue`; a value that matches no enabled item with content<br>leaves the menu closed. Update it from `onValueChange`. |
| children | JSX.Element \| undefined | — | Composed navigation parts. |
| class | SlotClassValue \| undefined | — | Class applied to the component root or trigger element. |
| classes | Classes \| undefined | — | Family slot class defaults for this instance. |
| style | SlotStyleValue \| undefined | — | Style applied to the component root or trigger element. |
| styles | Styles \| undefined | — | Family slot style defaults for this instance. |

**`flip` example**

```tsx
import { Button, Popover } from 'moraine'

<Popover placement="bottom" flip="top bottom-end">
  <Popover.Trigger as={Button}>Details</Popover.Trigger>
  <Popover.Content>More information</Popover.Content>
</Popover>
```

#### NavigationMenu.List

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children | JSX.Element \| undefined | — | Content rendered inside the element. |
| class | SlotClassValue \| undefined | — | Class applied to the component root or trigger element. |
| style | SlotStyleValue \| undefined | — | Style applied to the component root or trigger element. |

#### NavigationMenu.Item

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| disabled | boolean \| undefined | false | Disable this item's trigger or direct links. |
| value | string \| undefined | — | Unique item value. Generated when omitted; set explicitly for controlled usage. |
| children | JSX.Element \| undefined | — | Content rendered inside the element. |
| class | SlotClassValue \| undefined | — | Class applied to the component root or trigger element. |
| style | SlotStyleValue \| undefined | — | Style applied to the component root or trigger element. |

#### NavigationMenu.Trigger

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| disabled | boolean \| undefined | — | Whether this trigger is disabled. |
| as | T \| undefined | 'button' | Element or component to render as. A tag name (`'a'`) renders that element and narrows the<br>other props to its attributes; a Solid component receives the props the trigger would put on<br>its element, so it should spread them onto its root and forward `ref`. Own styles and state<br>attributes are kept. |
| children | JSX.Element \| undefined | — | Trigger label and visual content. |
| class | SlotClassValue \| undefined | — | Class applied to the component root or trigger element. |
| style | SlotStyleValue \| undefined | — | Style applied to the component root or trigger element. |

**`as` example**

```tsx
import { Button } from 'moraine'

<Button as="a" href="/docs" target="_blank">Docs</Button>
```

#### NavigationMenu.Content

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children | JSX.Element \| undefined | — | Content rendered inside the element. |
| class | SlotClassValue \| undefined | — | Class applied to the component root or trigger element. |
| style | SlotStyleValue \| undefined | — | Style applied to the component root or trigger element. |

#### NavigationMenu.Link

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| active | boolean \| undefined | false | Marks this link as the current page by setting `aria-current="page"`. |
| closeOnSelect | boolean \| undefined | false | Closes the open panel when the link is clicked, unless a click handler calls<br>`preventDefault()`. |
| disabled | boolean \| undefined | false | Disables the link: it loses its `href`, gets `aria-disabled` and `tabIndex={-1}`, and clicks<br>are prevented. A link is also disabled when its `NavigationMenu` or `NavigationMenu.Item` is. |
| linkRender | Component<LinkRenderProps> \| undefined | — | Renders the link with a custom component, such as a router link, instead of `<a>`. It is<br>mounted as a component and receives the merged anchor props (`href`, `class`, `ref`, ARIA<br>attributes and event handlers), all of which it must forward to its anchor. |
| children | JSX.Element \| undefined | — | Content rendered inside the element. |
| class | SlotClassValue \| undefined | — | Class applied to the component root or trigger element. |
| style | SlotStyleValue \| undefined | — | Style applied to the component root or trigger element. |

**`linkRender` example**

```tsx
import { NavigationMenu } from 'moraine'
import type { NavigationMenuT } from 'moraine'

const RouterLink = (props: NavigationMenuT.LinkRenderProps) => <a {...props} />

<NavigationMenu aria-label="Main navigation">
  <NavigationMenu.List>
    <NavigationMenu.Item>
      <NavigationMenu.Link href="/docs" linkRender={RouterLink}>
        Documentation
      </NavigationMenu.Link>
    </NavigationMenu.Item>
  </NavigationMenu.List>
</NavigationMenu>
```
