Navigation Menu
The row of links at the top of a site; some items open a panel of more links.
Installation
npx @yolkui/cli add navigation-menuItems and their panel
An item is either a link or a trigger that opens a panel of more links. There is one panel for the whole menu: it sits under the open item and moves and resizes as the pointer goes along the row. Give the list inside each NavigationMenuContent a width; the panel takes it.
The current page
active on a link marks the page you are on: it keeps the gray fill and is read as the current page. An open item has the same fill; its chevron turned up tells them apart. The menu does not know your routes, so compare the address yourself.
const pathname = usePathname()
<NavigationMenuLink render={<Link href="/pricing" />} active={pathname === "/pricing"}>
Pricing
</NavigationMenuLink>Links with icons
A link in a panel stacks its children, which suits a title over a description. For one line with an icon, give it flex-row items-center gap-2.
Sizes
size takes Button's four sizes: xs, sm, default and lg, 28 to 40 high, so the row lines up with buttons beside it in a header.
With a router
render takes your router's link, so a page changes without a reload. A link in a panel closes the menu when it is clicked; closeOnClick={false} keeps it open.
Vertical
orientation="vertical" makes a column for a sidebar. The panel opens beside the item and the chevrons point that way.
Right to left
Under dir="rtl" the row starts at the right and the panel opens from the item's right edge. Wrap the app in Base UI's DirectionProvider as well, so the arrow keys turn around too.
A second level
Put a NavigationMenu inside a panel for a second level. Its items become rows of the panel, and a trigger among them opens its own panel beside it. Keep it to two levels; deeper menus are hard to steer with a pointer and to follow with a screen reader.
A second level in the same panel
For a large menu, the second level can stay in the panel instead of opening another one: rows at the start, and the links of the chosen row beside them. Put inline on the nested NavigationMenu, a NavigationMenuPanel after its list, and a defaultValue so one row is always chosen. On a phone the rows sit above their links.
Disabled
disabled on a trigger fades it and stops it opening, but it stays in the Tab order, so a Tooltip around it can say why.
Search engines
A panel's links are added to the page only when it opens, so they are not in the HTML the server sends. keepMounted on NavigationMenuContent keeps them there, hidden, for a crawler to follow. Use it on a public site's main menu.
<NavigationMenuContent keepMounted>…</NavigationMenuContent>In a header that stays in place
A panel is placed in the page, so under a fixed or sticky header it would scroll away from its item. positionMethod="fixed" keeps it with the header. A panel taller than the room under the row scrolls inside itself.
<NavigationMenu positionMethod="fixed">…</NavigationMenu>On a phone
A tap opens the panel and a tap outside closes it. The panel is never wider than the screen, and a row too long for its place wraps. A row of many items still does not suit a phone: below your breakpoint, hide the row and show a menu button that opens the same links in a Dialog, each link closing it. Narrow the window to see the button here.
API
NavigationMenu draws the panel itself, so the placement props go on it.
| Prop | Type | What it does |
|---|---|---|
size | xs · sm · default · lg | On NavigationMenu: the height of the items in the row. default (36). |
orientation | horizontal · vertical | On NavigationMenu: a row or a column. horizontal by default. |
align | start · center · end | On NavigationMenu: which edge of the open item the panel lines up with. start by default. |
side | bottom · top · inline-end · inline-start | On NavigationMenu: where the panel opens. bottom, or inline-end in a vertical menu. |
sideOffset | number | On NavigationMenu: the gap between the row and the panel. 6 by default. |
inline | boolean | On a NavigationMenu inside a panel: its second level stays in that panel. Needs a NavigationMenuPanel after the list and a defaultValue. |
positionMethod | absolute · fixed | On NavigationMenu: fixed for a menu in a header that does not scroll. absolute by default. |
keepMounted | boolean | On NavigationMenuContent: keep the panel's links in the HTML while it is closed, for search engines. |
value | any | On NavigationMenu: the open item, when you control it; defaultValue and onValueChange go with it. Give each NavigationMenuItem a value. |
delay | number | On NavigationMenu: milliseconds before a panel opens under the pointer. 50 by default; closeDelay is the same for closing. |
aria-label | string | On NavigationMenu: the landmark's name. "Main" by default. |
active | boolean | On NavigationMenuLink: this is the current page. |
closeOnClick | boolean | On NavigationMenuLink: close the menu when the link is clicked. On for a link in a panel. |
render | element | On NavigationMenuLink: your router's link. |
disabled | boolean | On NavigationMenuTrigger: it fades, stays in the Tab order and opens nothing. |
navigationMenuTriggerStyle | ({ size }) => string | The classes of an item in the row, for a link outside the menu that should match. |
Accessibility
The menu is a nav landmark named "Main" holding a list of links and buttons. It is site navigation, not an application menu, so it uses no menu roles and a screen reader reads it as ordinary links.
- Tab moves through the items. The arrow keys move along the row too, and Home and End jump to its ends.
- Enter, Space or the down arrow opens a panel; Tab then goes into its links, and Escape closes it and returns focus to the item.
- A trigger says whether its panel is expanded or collapsed. The pointer opens a panel on hover, but nothing depends on hover: a click or the keyboard does the same.
- The current page carries aria-current="page". It is shown by a fill, a shape, not by a text colour.
- With several nav landmarks on a page (this one, a breadcrumb, a footer), give each its own name with aria-label.
- An open panel is a landmark too, named by the item that opened it. So give the menu a name that none of its items has: a menu named "Product" with an item "Product" would be read as two landmarks with one name.
- Under reduced motion the panel appears and changes size at once.