Navigation Menu | Surflane

Preview

Local preview. It doesn't affect real accounts, environments, or run data.

Compare the same example at each size and density. Switching keeps input values and selection state. Size guidance and comparisons

RTL previewVertical navigationDisable LearnCancel changes

Open section: none. Current product: workspace.

Usage

Group links and sub-navigation to products, docs, and sections. It keeps the native nav, ul, li, and a structure. Trigger opens sub-links, and Link navigates. Set Link.active to mark the current destination. A vertical list also serves as a table of contents: mark the section in view with aria-current="location", which draws as the current page does, and a label that wraps keeps its room above and below. Page tabs that may not fit, as on a phone, take overflow='scroll': the list stays on one line and scrolls sideways, and the current link stays in view.

Use Menu or Menubar for commands, and Tabs for switching panels on one screen. Keep links native, and don't give nav role=menu. Don't make it hover-only. Provide click and keyboard paths, on small screens too.

Size: SizeProvider size="small" resizes the whole composition, including portals. The default size is Default. Size guidance and comparisons

Anatomy

Root(nav) → List(ul) → Item(li) → Trigger + Content; Portal → Positioner → Popup(nav) → Viewport

Keyboard and accessibility

Once a Trigger's sub-links are open, Tab moves into them. Tab and arrow keys move through the sub-links.
Arrow keys move between top-level items. In a horizontal layout, ArrowDown also opens a Trigger's sub-links.
Enter or Space opens a Trigger's sub-links. Enter on a sub-link navigates.
Escape closes the sub-links.
For RTL, set both DirectionProvider and the DOM dir.
For a vertical layout, set orientation=vertical. It changes both semantics and layout.

Give each control a name that describes its purpose. Connect error messages to their controls, and signal state with more than color. Automated checks don't replace manual keyboard and assistive technology testing.

Example code

Shared components take their styles from design tokens. Each example sets its own composition and accessibility attributes. The calling screen defines callbacks, refs, and product data.

import { NavigationMenu } from '@surflane/ui'

<NavigationMenu.Root aria-label='Platform navigation'>
  <NavigationMenu.List>
    <NavigationMenu.Item value='products'>
      <NavigationMenu.Trigger>Products</NavigationMenu.Trigger>
      <NavigationMenu.Content>
        <NavigationMenu.Link href='/workspace' active closeOnClick>
          Workspace
        </NavigationMenu.Link>
        <NavigationMenu.Link href='/docs' closeOnClick>
          Documentation
        </NavigationMenu.Link>
      </NavigationMenu.Content>
    </NavigationMenu.Item>
  </NavigationMenu.List>
  <NavigationMenu.Portal>
    <NavigationMenu.Positioner
      align='start'
      sideOffset={8}
      collisionPadding={12}
    >
      <NavigationMenu.Popup aria-label='Product destinations'>
        <NavigationMenu.Viewport />
      </NavigationMenu.Popup>
    </NavigationMenu.Positioner>
  </NavigationMenu.Portal>
</NavigationMenu.Root>

Key API

Navigation Menu — common wrapper props
Prop	Contract	Default
`Root.value / defaultValue / onValueChange`	generic item value \| null; event.cancel()	null
`Root.orientation`	horizontal \| vertical; layout and keyboard direction	horizontal
`Root.overflow`	scroll keeps a horizontal list on one line in a ScrollArea where its links don't fit, such as page tabs on a phone, and keeps the current link in view as fonts load and the width changes	the list keeps its width
`Root.delay / closeDelay`	hover open / close delay in milliseconds	50 / 50
`Trigger.disabled / indicator`	disable opening; custom indicator or false	false / SVG chevron
`Link.href / active / closeOnClick`	native navigation; aria-current=page, or location for a section of this page; close on selection	— / false / false
`Content.keepMounted`	preserve hidden content and SSR links	false
`Positioner / Popup / Viewport`	explicit Popup anatomy; anchor and collision options; measured size	required for popup composition
`LinkTitle / LinkDescription`	a destination's name and a quieter line under it, inside a Link	—
`render / ref / className`	Base UI composition, DOM element ref, and state callback	—

The table lists the common wrapper's main props. See the package type declarations for the full types.