Navigation Menu

A row of site links whose triggers open panels of further links.

import { visibility } from "@/theme/visibility"
import type { ReactNode } from "react"
import * as stylex from "@stylexjs/stylex"
import { WarningCircleIcon } from "@phosphor-icons/react/dist/csr/WarningCircle"
import { CheckCircleIcon } from "@phosphor-icons/react/dist/csr/CheckCircle"
import { CircleDashedIcon } from "@phosphor-icons/react/dist/csr/CircleDashed"
import {
  NavigationMenu,
  NavigationMenuContent,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuTrigger,
  navigationMenuStyles,
} from "@/components/ui/navigation-menu"
import { VStack } from "@/components/ui/stack"
import { breakpoints } from "@/theme/breakpoints.stylex"
import { color, space } from "@/theme/tokens.stylex"

const styles = stylex.create({
  list: { width: "24rem" },
  grid: {
    display: "grid",
    gap: space.s2,
    width: { default: "25rem", [breakpoints.md]: "31.25rem", [breakpoints.lg]: "37.5rem" },
    gridTemplateColumns: { default: "1fr", [breakpoints.md]: "repeat(2, 1fr)" },
  },
  narrow: { width: "12.5rem" },
  title: { fontWeight: 500, lineHeight: 1 },
  description: {
    display: "-webkit-box",
    WebkitLineClamp: 2,
    WebkitBoxOrient: "vertical",
    overflow: "hidden",
    color: color.mutedForeground,
  },
})

const components: { title: string; href: string; description: string }[] = [
  {
    title: "Alert Dialog",
    href: "/docs/components/alert-dialog",
    description: "Asks the user to confirm or cancel an action before it runs.",
  },
  {
    title: "Hover Card",
    href: "/docs/components/hover-card",
    description: "Previews the page behind a link while the pointer rests on it.",
  },
  {
    title: "Progress",
    href: "/docs/components/progress",
    description: "Shows how much of a task is done, as a bar that fills from the start.",
  },
  {
    title: "Scroll Area",
    href: "/docs/components/scroll-area",
    description: "A scrolling region with a scrollbar that looks the same in every browser.",
  },
  {
    title: "Tabs",
    href: "/docs/components/tabs",
    description: "Switches between panels of content that share one place on the page.",
  },
  {
    title: "Tooltip",
    href: "/docs/components/tooltip",
    description: "A short label that appears beside an element on hover or keyboard focus.",
  },
]

export default function NavigationMenuDemo() {
  return (
    <NavigationMenu>
      <NavigationMenuList>
        <NavigationMenuItem>
          <NavigationMenuTrigger>Guides</NavigationMenuTrigger>
          <NavigationMenuContent>
            <ul {...stylex.props(styles.list)}>
              <ListItem href="/docs/installation" title="Installation">
                Add the theme, the tokens and the StyleX compiler to a Vite app.
              </ListItem>
              <ListItem href="/docs/styling" title="Styling">
                Override a component through xstyle and retheme it through tokens.
              </ListItem>
              <ListItem href="/docs/components/stack" title="Stack">
                Direction, gap, padding and alignment on one closed scale.
              </ListItem>
            </ul>
          </NavigationMenuContent>
        </NavigationMenuItem>
        <NavigationMenuItem xstyle={visibility.flexFromMd}>
          <NavigationMenuTrigger>Components</NavigationMenuTrigger>
          <NavigationMenuContent>
            <ul {...stylex.props(styles.grid)}>
              {components.map((component) => (
                <ListItem key={component.title} title={component.title} href={component.href}>
                  {component.description}
                </ListItem>
              ))}
            </ul>
          </NavigationMenuContent>
        </NavigationMenuItem>
        <NavigationMenuItem>
          <NavigationMenuTrigger>Status</NavigationMenuTrigger>
          <NavigationMenuContent>
            <ul {...stylex.props(styles.narrow)}>
              <li>
                <NavigationMenuLink href="#">
                  <WarningCircleIcon aria-hidden="true" />
                  Needs review
                </NavigationMenuLink>
                <NavigationMenuLink href="#">
                  <CircleDashedIcon aria-hidden="true" />
                  Draft
                </NavigationMenuLink>
                <NavigationMenuLink href="#">
                  <CheckCircleIcon aria-hidden="true" />
                  Shipped
                </NavigationMenuLink>
              </li>
            </ul>
          </NavigationMenuContent>
        </NavigationMenuItem>
        <NavigationMenuItem>
          <NavigationMenuLink href="/docs/installation" xstyle={navigationMenuStyles.trigger}>
            Docs
          </NavigationMenuLink>
        </NavigationMenuItem>
      </NavigationMenuList>
    </NavigationMenu>
  )
}

function ListItem({ title, children, href }: { title: string; children: ReactNode; href: string }) {
  return (
    <li>
      <NavigationMenuLink href={href}>
        <VStack gap={1}>
          <span {...stylex.props(styles.title)}>{title}</span>
          <span {...stylex.props(styles.description)}>{children}</span>
        </VStack>
      </NavigationMenuLink>
    </li>
  )
}

Installation

pnpm dlx shadcn@latest add @arene/navigation-menu

Needs the arene setup first.

Usage

import {
  NavigationMenu,
  NavigationMenuContent,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuTrigger,
} from "@/components/ui/navigation-menu"
<NavigationMenu>
  <NavigationMenuList>
    <NavigationMenuItem>
      <NavigationMenuTrigger>Guides</NavigationMenuTrigger>
      <NavigationMenuContent>
        <NavigationMenuLink href="/docs/installation">Installation</NavigationMenuLink>
      </NavigationMenuContent>
    </NavigationMenuItem>
  </NavigationMenuList>
</NavigationMenu>

Composition

NavigationMenu                      nav + portal, positioner, popup, viewport
└── NavigationMenuList
    ├── NavigationMenuItem
    │   ├── NavigationMenuTrigger
    │   └── NavigationMenuContent
    │       ├── NavigationMenuLink
    │       └── NavigationMenuLink
    └── NavigationMenuItem
        └── NavigationMenuLink

There is one popup for the whole menu. NavigationMenu renders it, and every NavigationMenuContent is shown inside it in turn, so the panel resizes and slides between triggers instead of closing and reopening.

There is no NavigationMenuIndicator. shadcn's is a Radix arrow rendered through Base UI's Icon part, which is the trigger's chevron here.

Use the render prop to hand navigation to a router link. href alone renders a plain <a>.

import { Link } from "@tanstack/react-router"

import {
  NavigationMenuItem,
  NavigationMenuLink,
  navigationMenuStyles,
} from "@/components/ui/navigation-menu"

export function DocsLink() {
  return (
    <NavigationMenuItem>
      <NavigationMenuLink render={<Link to="/docs" />} xstyle={navigationMenuStyles.trigger}>
        Documentation
      </NavigationMenuLink>
    </NavigationMenuItem>
  )
}

navigationMenuStyles.trigger gives a top-level link the trigger's height and padding so it lines up with its neighbours. Pass active to mark the current page. The link then takes the open trigger's fill and aria-current="page".

Large menus

The popup grows to fit the panel it shows. Cap it with popupProps when a panel can be taller than the viewport, and cap the panel to match.

const styles = stylex.create({
  capped: { maxHeight: "var(--available-height)" },
  scrolls: { maxHeight: "var(--available-height)", overflowY: "auto" },
})

<NavigationMenu popupProps={{ xstyle: styles.capped }}>
  <NavigationMenuList>
    <NavigationMenuItem>
      <NavigationMenuTrigger>Products</NavigationMenuTrigger>
      <NavigationMenuContent xstyle={styles.scrolls}>{/* … */}</NavigationMenuContent>
    </NavigationMenuItem>
  </NavigationMenuList>
</NavigationMenu>

A native scrollbar stays visible while the panel slides. If that is a problem, put a Scroll Area inside the content instead.

API reference

Pass render to replace a part's element or compose it with another component.

Every part wraps the Base UI NavigationMenu part of the same name and accepts its props. See the Base UI reference for the full list. Each part also takes xstyle and className. NavigationMenuTrigger, NavigationMenuContent, NavigationMenuLink and the popup reached through popupProps take style too. It is real inline CSS, merged over whatever their Base UI state resolves to, not a StyleX override.

Renders a <nav> and, after its children, the portal, positioner, popup and viewport. The positioning props are forwarded to the positioner.

PropTypeDefault
valueValue | null—
defaultValueValue | nullnull
onValueChange(value: Value | null, details) => void—
delaynumber50
closeDelaynumber50
orientation"horizontal" | "vertical""horizontal"
side"top" | "bottom" | "left" | "right""bottom", "right" when vertical
sideOffsetnumber8
align"start" | "center" | "end""start"
alignOffsetnumber0
popupPropsNavigationMenuPrimitive.Popup.Props & { xstyle, className, style }—
PropTypeDefault
activebooleanfalse
closeOnClickbooleantrue
PropTypeDefault
keepMountedbooleanfalse
KeyDescription
triggerThe trigger's box and the shared focus ring, for a link that sits beside them
linkThe link's box and the same ring, for a control in a panel that is not a link

Each key pairs the part's own box with states.focusRing from theme/states.ts, so an element that uses one shows the same focus ring as the part it came from. The popup's fill and hairline ring are states.popupSurface and the positioner's layer is states.positioner. Neither is in the map, because neither is a box you would put on an element of your own.

Data attributes

AttributeOnEffect
data-slot="navigation-menu"the nav
data-orientationthe nav, listMirrors orientation
data-slot="navigation-menu-list"the ul
data-slot="navigation-menu-item"each li
data-slot="navigation-menu-trigger"a trigger
data-popup-open, data-presseda triggerBase UI writes them
data-slot="navigation-menu-trigger-icon"the chevronRotates while its item is open
data-slot="navigation-menu-content"a panel
data-activation-directiona panelWhich side the previous trigger was on; sets the slide
data-slot="navigation-menu-link"a link
data-activea linkMirrors active
data-slot="navigation-menu-positioner"the positionerSlides between triggers
data-side, data-align, data-instantthe positionerBase UI writes them
data-slot="navigation-menu-popup"the popupThe surface: fill, ring, radius
data-slot="navigation-menu-viewport"the viewportClips the panel while it slides
data-starting-style, data-ending-stylepopup and panelBase UI writes them while either animates