Navigation Menu

new

The header your marketing team keeps asking for. Links and triggers whose panels open in one shared box that glides between them.

Demo

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

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.

Link variant

Indicator

NavigationMenuIndicator inside the list draws an arrow under the open trigger that follows it from trigger to trigger.

Indicator

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.

Align

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.

Without a viewport

Nothing searched yet

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.

Controlled
Open: none

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.

Click only

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.

With your own links

Route: /

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.

Vertical

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.

Responsive
Acme

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 docs and docs-api, or a short one like a, opened the wrong trigger's panel and indicator. Item values are now wrapped before they reach Reka, and v-model still 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. NavigationMenuList and NavigationMenuContent swap 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. NavigationMenuContent keeps 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 with overflow: hidden clips it, and a sticky header needs its own z-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-duration and skip-delay-duration only 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.
  • orientation is 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 as aria-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.

navigationMenuTriggerStyle({ size, variant }) returns a trigger's classes, to give your own element the same look.

Data attributes

data-slotAttributesDescription
navigation-menudata-size, data-variant, data-viewport, data-orientationThe nav. data-viewport is true or false.
navigation-menu-listdata-orientationThe ul of top-level items.
navigation-menu-item—An li.
navigation-menu-triggerdata-state, data-disabled, aria-expandedThe button that opens a panel. data-state is open or closed.
navigation-menu-contentdata-state, data-motion, data-orientationA 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-linkdata-active, aria-current, aria-disabledA link, at the top level or in a panel.
navigation-menu-indicatordata-state, data-orientationThe arrow under the open trigger. data-state is visible or hidden.
navigation-menu-viewport-wrapper—The positioned box the viewport sits in.
navigation-menu-viewportdata-state, data-orientationThe shared box panels open in. Carries --reka-navigation-menu-viewport-width, -height, -left and -top.

CSS variables

VariableDefaultDescription
--nav-offset4pxThe 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.

KeyAction
TabMoves 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 / SpaceOpens or closes the focused trigger's panel, or follows the focused link.
ArrowDownOn 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 / EndMoves to the first or last top-level item.
EscapeCloses the panel and returns focus to its trigger.

Changelog

  1. registry 0.22.0

    fb216dc — NavigationMenuIndicator renders nothing in a NavigationMenu with :viewport="false", where it used to sit under the first item whichever trigger was open, and warns once about it in development.

    0f77a24 — NavigationMenu: the gap between the list and a panel is the root variable --nav-offset (4px), read through plain margins, so a margin class on NavigationMenuContent wins and [--nav-offset:…] on NavigationMenu moves the viewport and the indicator's arrow together. The page now shows how to change a vertical trigger's alignment.

  2. registry 0.21.0

    95a0fa1 — Parts follow their root's size through CSS variables instead of the context, so a class on a part wins over the size. PinInput sets --pin-input-slot, TagsInput --tags-input-line and --tags-input-delete, and PinInput, InputNumber, TagsInput and InputGroup set --control-text and --control-text-leading for the field inside (textControlText and textControlInnerText in @/ui/input). NavigationMenu's triggers and links read the --nav-* variables of the menu instead of setting their own, and DataTable's sort buttons and row toggles shrink at xs through the table's variables. PinInput's slots now sit --control-gap-* apart (2px wider at sm, lg and xl); nothing else moves. inputNumberInputVariants, tagsInputInputVariants and tagsInputItemDeleteVariants became the strings inputNumberInput, tagsInputInput and tagsInputItemDelete, inputGroupControlText is gone, and pinInputSlotVariants lost its size key.

  3. registry 0.13.0

    65ef2c8 — New navigation-menu item: NavigationMenu, NavigationMenuList, NavigationMenuItem, NavigationMenuTrigger, NavigationMenuContent, NavigationMenuLink, NavigationMenuIndicator, NavigationMenuViewport and navigationMenuTriggerStyle, Reka UI's navigation menu with shadcn-vue's part names. Panels open on hover, click or key in one viewport under the list that resizes and slides between them, or under their own trigger with :viewport="false". The root takes size (xs to xl on the control scale, default md), variant (ghost or link), a logical align and orientation="vertical" for a column with panels beside it. NavigationMenuLink looks like a trigger at the top level and like a block with a title and a description in a panel, marks the current page with active and takes disabled. It works around Reka bugs still in 2.11: values that contain each other (docs and docs-api) opening the wrong panel, ArrowLeft and ArrowRight moving the wrong way in right-to-left text, between top-level items and between a panel's links, and Space closing a panel without a viewport instead of reaching its field or button. Needs the @kappa-ui/core release with navigation-menu-motion.