Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Navigation

NavigationMenu

Semantic website navigation with disclosure content, active links, and managed keyboard focus.

Last changed in version 0.14.2: Improve keyboard navigation, action feedback, and selected colors across Vue components.

Interactive showcase

Install

Run in your project
bunx --bun @getweini/cli@latest add navigation-menu

Start with this example

Import the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.

Vue
<script setup lang="ts">
import NavigationMenu from './components/ui/navigation-menu/NavigationMenu.vue'
import NavigationMenuContent from './components/ui/navigation-menu/NavigationMenuContent.vue'
import NavigationMenuItem from './components/ui/navigation-menu/NavigationMenuItem.vue'
import NavigationMenuLink from './components/ui/navigation-menu/NavigationMenuLink.vue'
import NavigationMenuList from './components/ui/navigation-menu/NavigationMenuList.vue'
import NavigationMenuTrigger from './components/ui/navigation-menu/NavigationMenuTrigger.vue'
import NavigationMenuViewport from './components/ui/navigation-menu/NavigationMenuViewport.vue'
</script>

<template>
  <NavigationMenu label="Primary navigation">
    <NavigationMenuList>
      <NavigationMenuItem value="learn">
        <NavigationMenuTrigger>Learn</NavigationMenuTrigger>
        <NavigationMenuContent>
          <div class="grid gap-3 p-4">
            <NavigationMenuLink href="https://ui.weini.lu/guides/getting-started">
              Getting started
            </NavigationMenuLink>
            <NavigationMenuLink href="https://ui.weini.lu/guides/accessibility">
              Accessibility
            </NavigationMenuLink>
          </div>
        </NavigationMenuContent>
      </NavigationMenuItem>
    </NavigationMenuList>
    <NavigationMenuViewport />
  </NavigationMenu>
</template>

Dropdown content uses a compact 4px outer inset. Links keep 12px inline padding, 44px minimum row targets, and an 8px gap between an icon and its label stack.

When to use it

Product navigation

Group several destination links under a discoverable top-level section.

Documentation navigation

Offer a compact menu of guides while keeping direct links available.

More examples

Products menu

Use the viewport for a shared disclosure surface and mark the active page.

Products menu
<script setup lang="ts">
import NavigationMenu from './components/ui/navigation-menu/NavigationMenu.vue'
import NavigationMenuContent from './components/ui/navigation-menu/NavigationMenuContent.vue'
import NavigationMenuItem from './components/ui/navigation-menu/NavigationMenuItem.vue'
import NavigationMenuLink from './components/ui/navigation-menu/NavigationMenuLink.vue'
import NavigationMenuList from './components/ui/navigation-menu/NavigationMenuList.vue'
import NavigationMenuTrigger from './components/ui/navigation-menu/NavigationMenuTrigger.vue'
import NavigationMenuViewport from './components/ui/navigation-menu/NavigationMenuViewport.vue'
</script>

<template>
  <NavigationMenu label="Primary navigation">
    <NavigationMenuList>
      <NavigationMenuItem value="learn">
        <NavigationMenuTrigger>Learn</NavigationMenuTrigger>
        <NavigationMenuContent>
          <div class="grid gap-3 p-4">
            <NavigationMenuLink href="https://ui.weini.lu/guides/getting-started">
              Getting started
            </NavigationMenuLink>
            <NavigationMenuLink href="https://ui.weini.lu/guides/accessibility">
              Accessibility
            </NavigationMenuLink>
          </div>
        </NavigationMenuContent>
      </NavigationMenuItem>
    </NavigationMenuList>
    <NavigationMenuViewport />
  </NavigationMenu>
</template>

Guide categories

A second disclosure can contain another set of semantic links.

Guide categories
<script setup lang="ts">
import NavigationMenu from './components/ui/navigation-menu/NavigationMenu.vue'
import NavigationMenuContent from './components/ui/navigation-menu/NavigationMenuContent.vue'
import NavigationMenuItem from './components/ui/navigation-menu/NavigationMenuItem.vue'
import NavigationMenuLink from './components/ui/navigation-menu/NavigationMenuLink.vue'
import NavigationMenuList from './components/ui/navigation-menu/NavigationMenuList.vue'
import NavigationMenuTrigger from './components/ui/navigation-menu/NavigationMenuTrigger.vue'
import NavigationMenuViewport from './components/ui/navigation-menu/NavigationMenuViewport.vue'
</script>

<template>
  <NavigationMenu label="Guides" orientation="horizontal">
    <NavigationMenuList>
      <NavigationMenuItem value="guides">
        <NavigationMenuTrigger>Guides</NavigationMenuTrigger>
        <NavigationMenuContent>
          <div class="grid gap-2 p-4">
            <NavigationMenuLink href="/guides/getting-started">Getting started</NavigationMenuLink>
            <NavigationMenuLink href="/guides/accessibility">Accessibility</NavigationMenuLink>
          </div>
        </NavigationMenuContent>
      </NavigationMenuItem>
    </NavigationMenuList>
    <NavigationMenuViewport />
  </NavigationMenu>
</template>

Complete API

Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.

NavigationMenu

Complete API for NavigationMenu
NameType or signatureDefaultWhat it does
valuemodelstring | undefinedNot setValue represented by this control or option.
defaultValuepropstring | undefinedNot setStarting value when the parent does not control the value.
orientationpropNavigationMenuOrientation | undefined"horizontal"Arrange items horizontally or vertically.
dirpropNavigationMenuDirection | undefined"ltr"Set the text direction used for keyboard and layout behavior.
disabledpropboolean | undefinedfalsePrevent interaction and show the disabled state.
labelpropstring | undefinedNot setVisible or accessible name for this item.
valueChangeevent[value: string | undefined]—Emitted after this value or state changes.
update:valueevent[value: string | undefined]—Requests a new value value from the parent.
defaultslot(props: { value: string | undefined; setValue: (value: string | undefined) => void; }) => unknownRequiredContent shown inside NavigationMenu.
closeexposed() => void—Close this component from application code.
focusexposed() => void—Move keyboard focus to this control.

NavigationMenuContent

Complete API for NavigationMenuContent
NameType or signatureDefaultWhat it does
forceMountpropboolean | undefinedfalseKeep the content mounted even when it is closed.
defaultslot{ close: () => void; }OptionalContent shown inside NavigationMenuContent.

NavigationMenuIndicator

Complete API for NavigationMenuIndicator
NameType or signatureDefaultWhat it does
defaultslot{ value: string; }OptionalContent shown inside NavigationMenuIndicator.

NavigationMenuItem

Complete API for NavigationMenuItem
NameType or signatureDefaultWhat it does
valuepropstringRequiredValue represented by this control or option.
disabledpropboolean | undefinedfalsePrevent interaction and show the disabled state.
defaultslot{}OptionalContent shown inside NavigationMenuItem.
Complete API for NavigationMenuLink
NameType or signatureDefaultWhat it does

NavigationMenuList

Complete API for NavigationMenuList
NameType or signatureDefaultWhat it does
defaultslot{}OptionalContent shown inside NavigationMenuList.

NavigationMenuTrigger

Complete API for NavigationMenuTrigger
NameType or signatureDefaultWhat it does
disabledpropboolean | undefinedfalsePrevent interaction and show the disabled state.
defaultslot{ open: boolean; }OptionalContent shown inside NavigationMenuTrigger.

NavigationMenuViewport

Complete API for NavigationMenuViewport
NameType or signatureDefaultWhat it does
defaultslot{}OptionalContent shown inside NavigationMenuViewport.
Public type definitions
Public types
// packages/frameworks/vue/components/navigation-menu/types.ts
import type { Component } from 'vue'

export type NavigationMenuOrientation = 'horizontal' | 'vertical'
export type NavigationMenuDirection = 'ltr' | 'rtl'
export type NavigationMenuAriaCurrent = 'page' | 'step' | 'location' | 'date' | 'time'

export interface NavigationMenuProps {
  value?: string
  defaultValue?: string
  orientation?: NavigationMenuOrientation
  dir?: NavigationMenuDirection
  disabled?: boolean
  label?: string
}

export interface NavigationMenuItemProps {
  value: string
  disabled?: boolean
}

export interface NavigationMenuTriggerProps {
  disabled?: boolean
}

export interface NavigationMenuContentProps {
  forceMount?: boolean
}

export interface NavigationMenuLinkProps {
  href?: string
  as?: 'a' | Component
  asChild?: boolean
  active?: boolean
  ariaCurrent?: NavigationMenuAriaCurrent
}

Implementation notes

  • Put actual links inside NavigationMenuContent and let your router set active or ariaCurrent for the current destination.
  • Keep the panel layout in your own markup; content and viewport classes customize the surfaces.

Accessibility and localization

  • Give the navigation a meaningful label. Mouse, touch, and keyboard can open disclosures; use real anchors for destinations.

Source contract and editing guidance