Skip to content

Navigation Menu

Build navigation links with flyouts or expandable groups.

Demos

Size

Usage

vue
<script setup lang="ts">
import { Accordion } from '~/components/ui/accordion'

const items = [
  { value: 'source', label: 'Do I own the source?', content: 'Yes. Copy and adapt the files.' },
]
</script>

<template>
  <Accordion :items="items" />
</template>

Flyouts sit 2px from their trigger. Flyout links stack their title above the description. The hover highlight slides between top-level controls in 180ms and follows keyboard focus. Hovering a link without children closes the previous flyout. Reduced motion disables the slide.

Installation

Complete the shared installation. Copy NavigationMenu.vue and index.ts into app/components/ui/navigation-menu/.

API

Variants and defaults

PropValuesDefault
sizexs, sm, md, lg, xlsm

Models

ModelTypeDefaultDescription
v-modelstring | nulldefaultValueSelected leaf value. Falls back to a string to, href, then label.
v-model:openstring | nullnullActive horizontal or side flyout item.
v-model:expandedstring[]defaultExpanded and item defaultsExpanded inline item values. Multiple branches may remain open.

Props

Use highlight-mode="selection" to keep the shared indicator on the current item; the default hover mode follows pointer and focus movement. Use selection-hover to retain selection and track hover with a separate marker. Sidebar uses these modes for its line and rail designs.

PropTypeDefaultDescription
itemsNavigationMenuItem[]requiredTop-level navigation items.
defaultValuestring | nullnullInitially selected value when v-model is uncontrolled.
orientation"horizontal" | "vertical""horizontal"Top-level layout and keyboard direction.
contentMode"auto" | "flyout" | "inline""auto"Child presentation. Auto uses horizontal flyouts, vertical inline expansion, and collapsed vertical side flyouts.
collapsedbooleanfalseEnables icon-rail behavior and automatic side flyouts for vertical navigation.
tooltipbooleanfalseShows accessible flyout labels for collapsed items without children.
defaultExpandedstring[][]Initially expanded inline item values.
loopbooleantrueArrow-key focus wraps.
dir"ltr" | "rtl""ltr"Horizontal direction and vertical flyout side.
disabledbooleanfalseDisables trigger interaction.
openDelaynumber80Pointer-open delay in milliseconds.
closeDelaynumber150Pointer-close delay in milliseconds.
sideOffsetnumber2Distance between a flyout and its trigger.
teleportstring | falseautomaticFlyout Teleport target. Defaults to body for collapsed vertical navigation and no Teleport otherwise.
ariaLabelstring"Primary"Accessible nav label.
uiNavigationMenuUi—Classes for structural parts.

Slots

SlotPropsDescription
triggerNavigationMenuSlotPropsTop-level flyout trigger content.
linkNavigationMenuSlotPropsTop-level direct-link content.
itemNavigationMenuSlotPropsFlyout item or complete vertical row content.
item-leadingNavigationMenuSlotPropsLeading icon/content for generated rows.
item-labelNavigationMenuSlotPropsGenerated label replacement.
item-trailingNavigationMenuSlotPropsTrailing action or metadata.
child-indicatorNavigationMenuSlotPropsExpansion indicator for child-bearing items.
[item.slot]NavigationMenuSlotPropsPer-item complete-content override.

NavigationMenuSlotProps exposes item, isOpen, isActive, depth, collapsed, and a native-handler-safe toggle action.

Events

EventPayloadDescription
open-change(value: string | null, details)Fired before active flyout changes.
expanded-change(values: string[], details)Fired before inline expansion changes. Details include item and expanded; call details.cancel() to reject it.
value-change(value, details)Fired before the selected value changes. Details include item; call details.cancel() to reject it.
select(item, details)Fired when a link/item is selected.

Keyboard

KeyBehavior
ArrowRight / ArrowLeftMove between horizontal items. In vertical inline mode, expand/collapse a branch or return to its parent. In vertical flyout mode, open toward the reading direction.
ArrowDown / ArrowUpMove through vertical inline rows, vertical flyout triggers, or flyout links.
ArrowDown / Enter / SpaceOpen a horizontal flyout item. Enter/Space also toggles inline disclosure buttons.
Home / EndFocus first/last enabled top-level item.
Character keysTypeahead across flyout triggers.
ArrowDown / ArrowUp in flyoutMove through enabled flyout links.
EscapeClose the active flyout.