// apps/docs/examples/ui/navigation-menu.tsx'use client';
import {  NavigationMenu,  NavigationMenuContent,  NavigationMenuItem,  NavigationMenuLink,  NavigationMenuList,  NavigationMenuTrigger,} from '@workspace/active-ui/components/primitives/navigation-menu';
// Invented sections; the links point to anchors, nothing navigates.const SECTIONS = [  {    trigger: 'Pension',    links: [      {title: 'Participants', description: 'Active and deferred members.'},      {title: 'Schemes', description: 'Accrual rules per scheme.'},      {title: 'Calculations', description: 'Batches and their results.'},    ],  },  {    trigger: 'Relations',    links: [      {title: 'Persons', description: 'The register of people.'},      {title: 'Organisations', description: 'Employers and providers.'},    ],  },] as const;
const anchor = (title: string) =>  `#nav-${title.toLowerCase().replaceAll(' ', '-')}`;
/** * The main navigation of a site: sections whose links open in a panel below * the bar, and a plain link beside them. Moving from one section to the * next keeps the panel open and slides it to the new content. */export default function NavigationMenuExample() {  return (    <NavigationMenu aria-label="Main">      <NavigationMenuList>        {SECTIONS.map((section) => (          <NavigationMenuItem key={section.trigger}>            <NavigationMenuTrigger>{section.trigger}</NavigationMenuTrigger>            <NavigationMenuContent>              <ul className="grid w-72 gap-1">                {section.links.map((link) => (                  <li key={link.title}>                    <NavigationMenuLink                      href={anchor(link.title)}                      className="flex-col items-start gap-0.5"                    >                      <span className="font-medium">{link.title}</span>                      <span className="text-muted-foreground">                        {link.description}                      </span>                    </NavigationMenuLink>                  </li>                ))}              </ul>            </NavigationMenuContent>          </NavigationMenuItem>        ))}        <NavigationMenuItem>          <NavigationMenuLink href={anchor('Reports')}>            Reports          </NavigationMenuLink>        </NavigationMenuItem>      </NavigationMenuList>    </NavigationMenu>  );}

Usage#

TSX

import {  NavigationMenu,  NavigationMenuContent,  NavigationMenuItem,  NavigationMenuLink,  NavigationMenuList,  NavigationMenuTrigger,} from '@workspace/active-ui/components/primitives/navigation-menu';
<NavigationMenu aria-label="Main">  <NavigationMenuList>    <NavigationMenuItem>      <NavigationMenuTrigger>Pension</NavigationMenuTrigger>      <NavigationMenuContent>        <NavigationMenuLink href="/participants">          Participants        </NavigationMenuLink>      </NavigationMenuContent>    </NavigationMenuItem>  </NavigationMenuList></NavigationMenu>;

Anatomy#

NavigationMenu: the <nav>. align (default start) places the panel under its trigger. It renders the panel's positioner itself.
NavigationMenuList with a NavigationMenuItem per section or link.
NavigationMenuTrigger and NavigationMenuContent: a section and its panel. Moving between triggers with a panel open slides the panel to the new content.
NavigationMenuLink: a link, in a panel or directly in the list. render makes your router's link the element. navigationMenuTriggerStyle() gives another element the look of a trigger.
NavigationMenuPositioner: the positioner of the panel, which NavigationMenu renders itself.
NavigationMenuIndicator: an optional pointer, a small rotated square, for a trigger of your own design; the menu does not render it.

What your application provides#

A name for the <nav> (aria-label), the sections and their links.
The current page: give its link active, which marks it (data-active).

Accessibility and keyboard#

Tab moves through the triggers and links; Enter, Space or ↓ opens a panel and Tab continues into its links.
Escape closes the panel and returns the focus to its trigger.
On a small screen, a bar of panels needs room it does not have: offer the same links in a sheet or a drawer instead.

API#

NavigationMenu#

Import from @workspace/active-ui/components/primitives/navigation-menu

All props come from the Base UI part this component is built on.

Props

value

Type: any
Default: null

The controlled value of the navigation menu item that should be currently open. When non-nullish, the menu will be open. When nullish, the menu will be closed.

To render an uncontrolled navigation menu, use the defaultValue prop instead.

defaultValue

Type: any
Default: null

The uncontrolled value of the item that should be initially selected.

To render a controlled navigation menu, use the value prop instead.

align

Type: Align
Default: 'center'

How to align the popup relative to the specified side.

closeDelay

Type: number
Default: 50

How long to wait before closing the navigation popup. Specified in milliseconds.

delay

Type: number
Default: 50

How long to wait before opening the navigation popup. Specified in milliseconds.

orientation

Type: "horizontal""vertical"
Default: 'horizontal'

The orientation of the navigation menu.

actionsRef

Type: RefObject<…>

A ref to imperative actions.

unmount: Ends the closing phase of the navigation menu popup after an externally controlled closing animation finishes. Call preventUnmountOnClose() in onValueChange first, otherwise the navigation menu popup completes closing on its own. Whether it leaves the DOM is decided by keepMounted on the portal.
close: Closes the navigation menu imperatively when called.

render

Type: ComponentRenderFn<…>ReactElement<…>

Allows you to replace the component's HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.

Events

Called by the component when something happens.

onValueChange

Type: (value, eventDetails) => void

Callback fired when the value changes.

onOpenChangeComplete

Type: (open: boolean) => void

Event handler called after any animations complete when the navigation menu is closed.

Other props, such as the standard attributes of the underlying element, className and ref, are passed through.

Other parts#

NavigationMenuContent

All props come from the Base UI part this component is built on.

Props

keepMounted

Type: boolean
Default: false

Whether to keep the content mounted in the DOM while the popup is closed. Ensures the content is present during server-side rendering for web crawlers.

render

Type: ComponentRenderFn<…>ReactElement<…>

Allows you to replace the component's HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.

Other props, such as the standard attributes of the underlying element, className and ref, are passed through.

NavigationMenuItem

All props come from the Base UI part this component is built on.

Props

value

Type: any

A unique value that identifies this navigation menu item. If no value is provided, a unique ID will be generated automatically. Use when controlling the navigation menu programmatically.

render

Type: ComponentRenderFn<…>ReactElement<…>

Allows you to replace the component's HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.

Other props, such as the standard attributes of the underlying element, className and ref, are passed through.

NavigationMenuLink

All props come from the Base UI part this component is built on.

Props

active

Type: boolean
Default: false

Whether the link is the currently active page.

closeOnClick

Type: boolean
Default: false

Whether to close the navigation menu when the link is clicked.

render

Type: ComponentRenderFn<…>ReactElement<…>

Allows you to replace the component's HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.

Other props, such as the standard attributes of the underlying element, className and ref, are passed through.

NavigationMenuTrigger

All props come from the Base UI part this component is built on.

Props

disabled

Type: boolean
Default: false

Whether the component should ignore user interaction.

nativeButton

Type: boolean
Default: true

Whether the component renders a native <button> element when replacing it via the render prop. Set to false if the rendered element is not a button (for example, <div>).

render

Type: ComponentRenderFn<…>ReactElement<…>

Allows you to replace the component's HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.

Other props, such as the standard attributes of the underlying element, className and ref, are passed through.

NavigationMenuPositioner

All props come from the Base UI part this component is built on.

Props

align

Type: Align
Default: 'center'

How to align the popup relative to the specified side.

alignOffset

Type: number | OffsetFunction
Default: 0

Additional offset along the alignment axis in pixels. Also accepts a function that returns the offset to read the dimensions of the anchor and positioner elements, along with its side and alignment.

The function takes a data object parameter with the following properties:

data.anchor: the dimensions of the anchor element with properties width and height.
data.positioner: the dimensions of the positioner element with properties width and height.
data.side: which side of the anchor element the positioner is aligned against.
data.align: how the positioner is aligned relative to the specified side.

anchor

Type: ElementRefObject<Element | null>VirtualElement() => …null

An element to position the popup against. By default, the popup will be positioned against the trigger.

arrowPadding

Type: number
Default: 5

Minimum distance to maintain between the arrow and the edges of the popup.

Use it to prevent the arrow element from hanging out of the rounded corners of a popup.

collisionAvoidance

Type: CollisionAvoidance

Determines how to handle collisions when positioning the popup.

side controls overflow on the preferred placement axis (top/bottom or left/right):

'flip': keep the requested side when it fits; otherwise try the opposite side (top and bottom, or left and right).
'shift': never change side; keep the requested side and move the popup within the clipping boundary so it stays visible.
'none': do not correct side-axis overflow.

align controls overflow on the alignment axis (start/center/end):

'flip': keep side, but swap start and end when the requested alignment overflows.
'shift': keep side and requested alignment, then nudge the popup along the alignment axis to fit.
'none': do not correct alignment-axis overflow.

fallbackAxisSide controls fallback behavior on the perpendicular axis when the preferred axis cannot fit:

'start': allow perpendicular fallback and try the logical start side first (top before bottom, or left before right in LTR).
'end': allow perpendicular fallback and try the logical end side first (bottom before top, or right before left in LTR).
'none': do not fallback to the perpendicular axis.

When side is 'shift', explicitly setting align only supports 'shift' or 'none'. If align is omitted, it defaults to 'flip'.

collisionBoundary

Type: Boundary
Default: 'clipping-ancestors'

An element or a rectangle that delimits the area that the popup is confined to.

collisionPadding

Type: Padding
Default: 5

Additional space to maintain from the edge of the collision boundary.

disableAnchorTracking

Type: boolean
Default: false

Whether to disable the popup from tracking any layout shift of its positioning anchor.

positionMethod

Type: "absolute""fixed"
Default: 'absolute'

Determines which CSS position property to use.

side

Type: Side
Default: 'bottom'

Which side of the anchor element to align the popup against. May automatically change to avoid collisions.

sideOffset

Type: number | OffsetFunction
Default: 0

Distance between the anchor and the popup in pixels. Also accepts a function that returns the distance to read the dimensions of the anchor and positioner elements, along with its side and alignment.

The function takes a data object parameter with the following properties:

data.anchor: the dimensions of the anchor element with properties width and height.
data.positioner: the dimensions of the positioner element with properties width and height.
data.side: which side of the anchor element the positioner is aligned against.
data.align: how the positioner is aligned relative to the specified side.

sticky

Type: boolean
Default: false

Whether to maintain the popup in the viewport after the anchor element was scrolled out of view.

render

Type: ComponentRenderFn<…>ReactElement<…>

Allows you to replace the component's HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.

Other props, such as the standard attributes of the underlying element, className and ref, are passed through.

Parts that take only their element’s attributes

NavigationMenuIndicator: the attributes of its element, with className and ref, and Base UI's render to use your own element.
NavigationMenuList: the attributes of its element, with className and ref, and Base UI's render to use your own element.

Functions, hooks and constants

Based on shadcn/ui

This page adapts the Navigation Menu documentation of shadcn/ui (MIT licence) to this package; see Third-party notices.