Navigation Menu
newThe header your marketing team keeps asking for. Links and triggers whose panels open in one shared box that glides between them.
Open Props in the corner of the example to try variant and size.
size goes from xs (28px) to xl (48px) and scales the items, the panel links, their text and icons.
Installation
Usage
<script setup lang="ts">
import {
NavigationMenu,
NavigationMenuContent,
NavigationMenuItem,
NavigationMenuLink,
NavigationMenuList,
NavigationMenuTrigger,
} from '@/components/ui/navigation-menu'
</script>
<template>
<NavigationMenu aria-label="Main">
<NavigationMenuList>
<NavigationMenuItem value="products">
<NavigationMenuTrigger>Products</NavigationMenuTrigger>
<NavigationMenuContent>
<NavigationMenuLink href="/analytics">Analytics</NavigationMenuLink>
<NavigationMenuLink href="/reports">Reports</NavigationMenuLink>
</NavigationMenuContent>
</NavigationMenuItem>
<NavigationMenuItem>
<NavigationMenuLink href="/pricing">Pricing</NavigationMenuLink>
</NavigationMenuItem>
</NavigationMenuList>
</NavigationMenu>
</template>
NavigationMenu is Reka UI's navigation menu with kappa-ui's styles: a nav landmark of top-level items. An item holds either a trigger and its panel, or a single link. Panels open on hover after a short delay, on click and from the keyboard, and all of them open in one viewport under the list, which resizes and slides as you move between triggers.
It's for site navigation: links to pages. For a list of actions, use Menu; for switching panels in place, Tabs.
NavigationMenuLink styles itself by where it sits. At the top level it looks like a trigger; inside a panel it becomes a block with room for a title and a description under it. active marks the current page with aria-current="page".
Give the nav an aria-label when the page has more than one: screen readers list landmarks by name.
Examples
Link variant
variant="link" drops the hover fill and underlines instead, for a lighter header. The current page stays underlined. A disabled link stays focusable and announced, but a click does nothing.
Indicator
NavigationMenuIndicator inside the list draws an arrow under the open trigger that follows it from trigger to trigger.
Align
align lines the viewport up with the start, centre or end of the open trigger. start and end follow the reading direction, so under dir="rtl" start is the right edge. In a vertical menu they are the top and bottom edges, whatever the direction. Near the edge of the page the viewport moves back in, 10px from it.
Without a viewport
With :viewport="false", each panel opens under its own trigger instead of in a shared box, and there's no slide between them. Panels can hold anything, a form included: Space, Enter and the arrow keys work as usual in a text field, and the form submits like any other. Close the menu after a submit through v-model. NavigationMenuIndicator needs the viewport: in this mode it renders nothing, and warns once in development.
Controlled
v-model holds the value of the open item, or an empty string when none is. Set it to open a panel from elsewhere, or clear it to close.
Click only
Hover menus suit a marketing site. In an app, where a panel that opens as the pointer passes by gets in the way, disable-hover-trigger opens panels on click only and disable-pointer-leave-close keeps them open until a click outside or Escape.
A link inside a panel that starts with an icon lays the icon and text out in a row.
Your own links
as-child hands a link's attributes, classes and behaviour to your router's link, so a click changes the route without reloading the page and still closes the menu.
<NavigationMenuLink as-child :active="route.path === '/pricing'">
<RouterLink to="/pricing">Pricing</RouterLink>
</NavigationMenuLink>
NuxtLink works the same way. A RouterLink or a plain <a> used in place of NavigationMenuLink doesn't: the menu never hears that a link was chosen, so it stays open.
Keep panels mounted
By default a closed panel's content is removed from the page. With :unmount-on-hide="false", every panel stays in the page, hidden, so its links are there for crawlers and the browser's find in page.
Vertical
orientation="vertical" stacks the items in a column, and panels open beside it. ArrowUp and ArrowDown move between items, and ArrowRight (ArrowLeft in right-to-left text) enters an open panel.
A vertical trigger is w-full and justify-start; to change them, use the same variant prefix, for example group-data-[orientation=vertical]/navigation-menu:justify-center.
Responsive
A row of hover panels doesn't work on a phone. Swap it for a Drawer Menu under a breakpoint, with the same links in submenus.
Fixed here
Reka UI's navigation menu has four bugs, still there in 2.11, that kappa-ui's parts work around. Once they are fixed upstream, the workarounds do nothing.
- Reka finds the open trigger by checking whether its id contains the open value, so values such as
docsanddocs-api, or a short one likea, opened the wrong trigger's panel and indicator. Item values are now wrapped before they reach Reka, andv-modelstill sees your own. - In right-to-left text, ArrowLeft and ArrowRight moved the wrong way, both between top-level items and between the links in a panel.
NavigationMenuListandNavigationMenuContentswap them back; a text field in a panel keeps its arrows. - Without a viewport, Space anywhere in a panel closed the menu, so it couldn't be typed into a field or press a button.
NavigationMenuContentkeeps Space inside the panel. The side effect: a Space keydown inside such a panel no longer reaches listeners on the document.
Known limits
- The viewport lives inside the
nav, not in a portal. A header withoverflow: hiddenclips it, and a sticky header needs its ownz-index, as the panel can't rise above its header's stacking context. The upside: CSS variables set on the header reach the panel. See nuxt/ui#5439. - Keep the list on one line. On a list that wraps, the viewport opens under the whole list rather than under the trigger's row (reka-ui#1522). Switch to a drawer before it gets that narrow.
- Don't put a navigation menu in a Dialog or Drawer: the focus trap and the menu disagree and Tab skips the last link (reka-ui#1782). Use a Drawer Menu there.
- Once a panel is open, moving to another trigger or out of the menu waits 150ms, and a click right after a hover opens the panel is ignored for 300ms. Neither can be changed (reka-ui#1578);
delay-durationandskip-delay-durationonly set the first opening. - Trigger and link must be direct children of their item. Wrapped in a tooltip or a
span, the arrow keys skip them. orientationis read once, so the menu remounts and closes when it changes.- Arrow keys pressed on top-level items, and ArrowLeft and ArrowRight on a link in a right-to-left panel, don't reach keydown listeners on the document (reka-ui#2400).
- On reka-ui 2.10, an open trigger is followed by a focusable element hidden with
aria-hidden, which axe reports asaria-hidden-focus. Reka 2.11 fixes it (reka-ui#2163). - No submenus inside panels yet, and only one panel open at a time. For a sidebar with several open groups, use Accordion.
API Reference
Every part takes a class that merges with its own. On NavigationMenuList it lands on the ul.
NavigationMenu
| Prop | Default | Type and description |
|---|---|---|
| modelValue | undefined | stringThe |
| defaultValue | — | stringThe item open at first when |
| dir | — | Direction$3Reading direction. Inherits from a surrounding |
| orientation | "horizontal" | Orientation
|
| delayDuration | 200 | numberMilliseconds the pointer rests on a trigger before its panel opens. |
| skipDelayDuration | 300 | numberMilliseconds after a panel closes during which hovering another trigger opens it without the delay. |
| disableClickTrigger | — | booleanA mouse click no longer opens or closes a panel. Keyboard and touch still do. |
| disableHoverTrigger | — | booleanHovering a trigger no longer opens its panel; only a click or a key does. |
| disablePointerLeaveClose | — | booleanThe panel stays open when the pointer leaves the menu. |
| unmountOnHide | true | booleanRemoves a closed panel's content from the DOM. Turn it off to keep every panel's links in the page, hidden. |
| asChild | — | booleanRender the single child instead of the |
| as | "nav" | AsTag | ComponentThe element or component to render; a |
| size | "md" | NavigationMenuSizeItem height, from 28px for |
| variant | "ghost" | NavigationMenuVariant
|
| viewport | true | booleanOpens every panel in one shared viewport under the list, which resizes between them. Turn it off to open each panel under its own trigger. |
| align | "center" | "center" | "start" | "end"Where the shared viewport lines up with the open trigger. |
| Event | Payload and description |
|---|---|
| update:modelValue | [value: string]Fires with the item's |
| Slot | Scope and description |
|---|---|
| default | { modelValue: string; }The |
NavigationMenuList
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of the |
| as | — | AsTag | ComponentThe element or component to render; a |
| Slot | Scope and description |
|---|---|
| default | {}The items, and an optional |
NavigationMenuItem
| Prop | Default | Type and description |
|---|---|---|
| value | — | stringNames the item for |
| asChild | — | booleanRender the single child instead of the |
| as | — | AsTag | ComponentThe element or component to render; an |
| Slot | Scope and description |
|---|---|
| default | {}A |
NavigationMenuTrigger
| Prop | Default | Type and description |
|---|---|---|
| disabled | — | booleanDisables the trigger: it can't be focused or opened, and the arrow keys skip it. |
| asChild | — | booleanRender the single child instead of the |
| as | "button" | AsTag | ComponentThe element or component to render; a |
| Slot | Scope and description |
|---|---|
| default | {}The label, with an optional leading icon. |
| icon | {}Replaces the chevron after the label. |
NavigationMenuContent
| Prop | Default | Type and description |
|---|---|---|
| forceMount | — | booleanKeeps the panel mounted while closed, for animating it with your own code. |
| disableOutsidePointerEvents | — | booleanBlocks pointer events outside the panel while it is open. |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Event | Payload and description |
|---|---|
| escapeKeyDown | [event: KeyboardEvent]Fires on Escape. Call |
| pointerDownOutside | [event: PointerDownOutsideEvent]Fires on a press outside the panel. Call |
| focusOutside | [event: FocusOutsideEvent]Fires when focus moves outside the panel. Call |
| interactOutside | [event: PointerDownOutsideEvent | FocusOutsideEvent]Fires on a press or focus outside the panel. Call |
| Slot | Scope and description |
|---|---|
| default | {}The panel: links, and any other content, forms included. |
NavigationMenuLink
| Prop | Default | Type and description |
|---|---|---|
| active | — | booleanMarks the link as the current page with |
| asChild | — | booleanRender the single child, such as your router's link, merging the link's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render; an |
| disabled | — | booleanKeeps the link focusable and announced, with |
| Event | Payload and description |
|---|---|
| select | [payload: CustomEvent<{ originalEvent: Event; }>]Fires when the link is chosen by click or keyboard. Call |
| Slot | Scope and description |
|---|---|
| default | {}The link text. In a panel, a title and an optional description under it; a leading icon puts them in a row. |
NavigationMenuIndicator
| Prop | Default | Type and description |
|---|---|---|
| forceMount | — | booleanKeeps the indicator mounted while no panel is open, for animating it with your own code. |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}Replaces the arrow. |
NavigationMenuViewport
| Prop | Default | Type and description |
|---|---|---|
| forceMount | — | booleanKeeps the viewport mounted while no panel is open, for animating it with your own code. |
| align | "center" | "start" | "center" | "end"Where the viewport lines up with the open trigger. |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
Props
- modelValue
undefined stringThevalueof the item whose panel is open, bound withv-model. An empty string means none.- defaultValue
stringThe item open at first whenv-modelis not used.- dir
Direction$3Reading direction. Inherits from a surroundingConfigProviderwhen not set. Otherwiseltr. Arrow keys andalignfollow it.- orientation
"horizontal" Orientationhorizontallays the items out in a row with panels below;verticalin a column with panels beside it. Changing it remounts the menu, which closes it.- delayDuration
200 numberMilliseconds the pointer rests on a trigger before its panel opens.- skipDelayDuration
300 numberMilliseconds after a panel closes during which hovering another trigger opens it without the delay.- disableClickTrigger
booleanA mouse click no longer opens or closes a panel. Keyboard and touch still do.- disableHoverTrigger
booleanHovering a trigger no longer opens its panel; only a click or a key does.- disablePointerLeaveClose
booleanThe panel stays open when the pointer leaves the menu.- unmountOnHide
true booleanRemoves a closed panel's content from the DOM. Turn it off to keep every panel's links in the page, hidden.- asChild
booleanRender the single child instead of thenav, merging this part's attributes and classes onto it.- as
"nav" AsTag | ComponentThe element or component to render; anavby default.- size
"md" NavigationMenuSizeItem height, from 28px forxsto 48px forxl, with matching padding, text and icon size. Panel links follow it.- variant
"ghost" NavigationMenuVariantghostgives items a hover and current-page fill;linkunderlines them instead.- viewport
true booleanOpens every panel in one shared viewport under the list, which resizes between them. Turn it off to open each panel under its own trigger.- align
"center" "center" | "start" | "end"Where the shared viewport lines up with the open trigger.startandendfollow the reading direction; in a vertical menu they are the top and bottom edges.
Emits
- update:modelValue
[value: string]Fires with the item'svaluewhen a panel opens, and with an empty string when it closes.
Slots
- default
{ modelValue: string; }TheNavigationMenuList. ReceivesmodelValue. The viewport is added after it.
Props
- asChild
booleanRender the single child instead of theul, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render; aulby default.classlands on it, inside the wrapper that tracks the indicator.
Slots
- default
{}The items, and an optionalNavigationMenuIndicator.
Props
- value
stringNames the item forv-model. Generated when not set.- asChild
booleanRender the single child instead of theli, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render; anliby default.
Slots
- default
{}ANavigationMenuTriggerand itsNavigationMenuContent, or a singleNavigationMenuLink. Put them straight inside the item: the arrow keys skip anything wrapped.
Props
- disabled
booleanDisables the trigger: it can't be focused or opened, and the arrow keys skip it.- asChild
booleanRender the single child instead of thebutton, merging this part's attributes and classes onto it.- as
"button" AsTag | ComponentThe element or component to render; abuttonby default.
Slots
- default
{}The label, with an optional leading icon.- icon
{}Replaces the chevron after the label.
Props
- forceMount
booleanKeeps the panel mounted while closed, for animating it with your own code.- disableOutsidePointerEvents
booleanBlocks pointer events outside the panel while it is open.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Emits
- escapeKeyDown
[event: KeyboardEvent]Fires on Escape. Callevent.preventDefault()to keep the panel open.- pointerDownOutside
[event: PointerDownOutsideEvent]Fires on a press outside the panel. Callevent.preventDefault()to keep it open.- focusOutside
[event: FocusOutsideEvent]Fires when focus moves outside the panel. Callevent.preventDefault()to keep it open.- interactOutside
[event: PointerDownOutsideEvent | FocusOutsideEvent]Fires on a press or focus outside the panel. Callevent.preventDefault()to keep it open.
Slots
- default
{}The panel: links, and any other content, forms included.
Props
- active
booleanMarks the link as the current page witharia-current="page"and the selected look.- asChild
booleanRender the single child, such as your router's link, merging the link's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render; anaby default.- disabled
booleanKeeps the link focusable and announced, witharia-disabled, but a click neither follows it nor closes the menu.
Emits
- select
[payload: CustomEvent<{ originalEvent: Event; }>]Fires when the link is chosen by click or keyboard. Callevent.preventDefault()to keep the menu open.
Slots
- default
{}The link text. In a panel, a title and an optional description under it; a leading icon puts them in a row.
Props
- forceMount
booleanKeeps the indicator mounted while no panel is open, for animating it with your own code.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{}Replaces the arrow.
Props
- forceMount
booleanKeeps the viewport mounted while no panel is open, for animating it with your own code.- align
"center" "start" | "center" | "end"Where the viewport lines up with the open trigger.startandendfollow the reading direction; in a vertical menu they are the top and bottom edges.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
navigationMenuTriggerStyle({ size, variant }) returns a trigger's classes, to give your own element the same look.
Data attributes
| data-slot | Attributes | Description |
|---|---|---|
| navigation-menu | data-size, data-variant, data-viewport, data-orientation | The nav. data-viewport is true or false. |
| navigation-menu-list | data-orientation | The ul of top-level items. |
| navigation-menu-item | — | An li. |
| navigation-menu-trigger | data-state, data-disabled, aria-expanded | The button that opens a panel. data-state is open or closed. |
| navigation-menu-content | data-state, data-motion, data-orientation | A panel. data-motion is from-start, from-end, to-start or to-end while it slides in or out as you switch triggers. |
| navigation-menu-link | data-active, aria-current, aria-disabled | A link, at the top level or in a panel. |
| navigation-menu-indicator | data-state, data-orientation | The arrow under the open trigger. data-state is visible or hidden. |
| navigation-menu-viewport-wrapper | — | The positioned box the viewport sits in. |
| navigation-menu-viewport | data-state, data-orientation | The shared box panels open in. Carries --reka-navigation-menu-viewport-width, -height, -left and -top. |
CSS variables
| Variable | Default | Description |
|---|---|---|
| --nav-offset | 4px | The gap between the list and a panel or the viewport, below a horizontal menu and beside a vertical one. Set it on NavigationMenu; the indicator's arrow follows it. A margin class on NavigationMenuContent still wins for one panel. |
Accessibility
It follows the WAI disclosure navigation pattern, not a menu: the root is a nav landmark, each trigger a button with aria-expanded and aria-controls, and each panel is labelled by its trigger. Links are ordinary links, so screen readers list them with the page's other links. Focus is never trapped.
| Key | Action |
|---|---|
| Tab | Moves through the top-level items. From an open trigger, moves into its panel, and past the panel's last link on to the next item. |
| Enter / Space | Opens or closes the focused trigger's panel, or follows the focused link. |
| ArrowDown | On an open trigger, moves into its panel. In a vertical menu, the key is ArrowRight, or ArrowLeft in right-to-left text. |
| → ← | Moves to the next or previous top-level item, without wrapping; inside a panel, to the next or previous link, except in a text field. In right-to-left text they swap. |
| ↓ ↑ | Moves to the next or previous top-level item; inside a panel, to the next or previous link, except in a text field. |
| Home / End | Moves to the first or last top-level item. |
| Escape | Closes the panel and returns focus to its trigger. |