Menubar

Pro

A desktop-style row of menus (File, Edit, View) in Candor's theme (Base UI). Arrow keys move between the menus and along each menu's items, Right and Left open and close submenus, Escape closes the open menu and returns focus to its trigger. An item that can't be used stays in the menu, marked and explained, instead of vanishing.

Markdown

Version 5.2.0· other versions

This page is for 5.2.0, the current release. An earlier release’s page is the Markdown that release published, so the docs match the version you have installed (candor-lock.json records it).

Not in the docs of 1.3.0, 1.4.0, 1.5.0, 1.5.1, 1.6.0, 1.7.0, 1.8.0, 1.8.1, 1.9.0, 1.9.1, 2.0.0, 2.1.0 and 2.2.0: the page came later, or had another name then.

Docs pages weren’t kept for 1.0.0, 1.0.1, 1.1.0, 1.1.1, 1.2.0 and 1.2.1: they are kept from 1.3.0 on, and before that only llms.txt was published.

Preview

Install

With the Candor CLI

First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/menubar

Brings in: layer, motion, tokens, utils · npm: @base-ui/react@^1.9.0, lucide-react@^1.67.0

Usage

TSX · The example above

"use client"

import * as React from "react"
import {
  Menubar,
  MenubarCheckboxItem,
  MenubarContent,
  MenubarItem,
  MenubarMenu,
  MenubarRadioGroup,
  MenubarRadioItem,
  MenubarSeparator,
  MenubarShortcut,
  MenubarSub,
  MenubarSubContent,
  MenubarSubTrigger,
  MenubarTrigger,
} from "@/components/candor/ui/menubar"

export default function Example() {
  const [grid, setGrid] = React.useState(true)
  const [density, setDensity] = React.useState("comfortable")
  return (
    <Menubar>
      <MenubarMenu>
        <MenubarTrigger>File</MenubarTrigger>
        <MenubarContent>
          <MenubarItem>
            New report <MenubarShortcut>⌘N</MenubarShortcut>
          </MenubarItem>
          <MenubarSub>
            <MenubarSubTrigger>Export</MenubarSubTrigger>
            <MenubarSubContent>
              <MenubarItem>CSV</MenubarItem>
              <MenubarItem>PDF</MenubarItem>
              <MenubarItem locked="Needs the data add-on.">Parquet</MenubarItem>
            </MenubarSubContent>
          </MenubarSub>
          <MenubarSeparator />
          <MenubarItem variant="destructive">Delete report</MenubarItem>
        </MenubarContent>
      </MenubarMenu>
      <MenubarMenu>
        <MenubarTrigger>View</MenubarTrigger>
        <MenubarContent>
          <MenubarCheckboxItem checked={grid} onCheckedChange={setGrid}>
            Show gridlines
          </MenubarCheckboxItem>
          <MenubarSeparator />
          <MenubarRadioGroup value={density} onValueChange={setDensity}>
            <MenubarRadioItem value="compact">Compact</MenubarRadioItem>
            <MenubarRadioItem value="comfortable">Comfortable</MenubarRadioItem>
          </MenubarRadioGroup>
        </MenubarContent>
      </MenubarMenu>
    </Menubar>
  )
}

<Menubar>

Prop	Type	Default	Description
className	`string \| undefined`	—	Extra classes for the outer element.

Also takes the props of Omit<MenubarPrimitive.Props, "className">.

<MenubarCheckboxItem>

A Menubar item that turns a setting on or off and shows a tick while it is on.

Prop	Type	Default	Description
className	`string \| undefined`	—	Classes for the part, merged with Candor's.
style	`React.CSSProperties \| undefined`	—	Inline styles for the part, merged over its motion chain.
onSelect	`OnSelect \| undefined`	—	Called when the person chooses the item; `event.preventDefault()` keeps the menu open.
closeOnClick	`boolean \| undefined`	true	Closes the menu once the person ticks the item, as Candor's menus did on Radix. Defaults to true.

Also takes the props of Omit<T, "className" | "style">.

<MenubarContent>

The popup of a Menubar, holding its items.

Prop	Type	Default	Description
className	`string \| undefined`	—	Classes for the part, merged with Candor's.
style	`React.CSSProperties \| undefined`	—	Inline styles for the part, merged over its motion chain.

<MenubarGroup>

A set of related items in a Menubar, read as one group by screen readers.

Prop	Type	Default	Description
className	`string \| undefined`	—	Classes for the part, merged with Candor's.
style	`React.CSSProperties \| undefined`	—	Inline styles for the part, merged over its motion chain.

Also takes the props of Omit<T, "className" | "style">.

<MenubarItem>

One action in a Menubar; it runs when chosen and closes the menu.

Prop	Type	Default	Description
className	`string \| undefined`	—	Classes for the part, merged with Candor's.
style	`React.CSSProperties \| undefined`	—	Inline styles for the part, merged over its motion chain.
inset	`boolean \| undefined`	—	Indents the item to line up with items that have an icon.
variant	`"default" \| "destructive" \| undefined`	"default"	destructive colours the item for actions that remove or can't be undone.
onSelect	`OnSelect \| undefined`	—	Called when the person chooses the item; `event.preventDefault()` keeps the menu open.
locked	`string \| null \| undefined`	—	Why the item can't be used right now. When set, it stays in the menu and in the arrow-key order, marked `aria-disabled`, choosing it does nothing and keeps the menu open, and the reason is printed beside it and read to screen readers. `null` or left out: unlocked.

Also takes the props of Omit<T, "className" | "style">.

<MenubarLabel>

A non-interactive heading over a group of items in a Menubar.

Prop	Type	Default	Description
inset	`boolean \| undefined`	—	Indents the label to line up with items that have an icon.

Also takes the props of React.ComponentProps<"div">.

<MenubarMenu>

One menu of a Menubar, with its MenubarTrigger and MenubarContent.

No props.

Also takes the props of MenuPrimitive.Root.Props.

<MenubarPortal>

Renders a Menubar's popup at the end of the page so nothing clips it; the parts do this themselves, so reach for it only to place a popup yourself.

No props.

Also takes the props of Omit<MenuPrimitive.Portal.Props, "container">.

<MenubarRadioGroup>

A set of MenubarRadioItems of which one is chosen.

Prop	Type	Default	Description
className	`string \| undefined`	—	Classes for the part, merged with Candor's.
style	`React.CSSProperties \| undefined`	—	Inline styles for the part, merged over its motion chain.

Also takes the props of Omit<T, "className" | "style">.

<MenubarRadioItem>

One choice in a MenubarRadioGroup, ticked while it is the chosen one.

Prop	Type	Default	Description
className	`string \| undefined`	—	Classes for the part, merged with Candor's.
style	`React.CSSProperties \| undefined`	—	Inline styles for the part, merged over its motion chain.
onSelect	`OnSelect \| undefined`	—	Called when the person chooses the item; `event.preventDefault()` keeps the menu open.
closeOnClick	`boolean \| undefined`	true	Closes the menu once the person ticks the item, as Candor's menus did on Radix. Defaults to true.

Also takes the props of Omit<T, "className" | "style">.

<MenubarSeparator>

A line between two groups of items in a Menubar.

Prop	Type	Default	Description
className	`string \| undefined`	—	Classes for the part, merged with Candor's.
style	`React.CSSProperties \| undefined`	—	Inline styles for the part, merged over its motion chain.

Also takes the props of Omit<T, "className" | "style">.

<MenubarShortcut>

The keys shown at the end of an item that run the same action from elsewhere.

No props.

Also takes the props of React.ComponentProps<"span">.

<MenubarSub>

A nested menu inside a Menubar; its MenubarSubTrigger opens its MenubarSubContent.

No props.

Also takes the props of MenuPrimitive.SubmenuRoot.Props.

<MenubarSubContent>

The popup of a nested menu in a Menubar.

Prop	Type	Default	Description
className	`string \| undefined`	—	Classes for the part, merged with Candor's.
style	`React.CSSProperties \| undefined`	—	Inline styles for the part, merged over its motion chain.

<MenubarSubTrigger>

The item in a Menubar that opens a nested menu, marked with an arrow.

Prop	Type	Default	Description
className	`string \| undefined`	—	Classes for the part, merged with Candor's.
style	`React.CSSProperties \| undefined`	—	Inline styles for the part, merged over its motion chain.
inset	`boolean \| undefined`	—	Indents the trigger to line up with items that have an icon.

Also takes the props of Omit<T, "className" | "style">.

<MenubarTrigger>

The name in a Menubar that opens one of its menus.

Prop	Type	Default	Description
className	`string \| undefined`	—	Extra classes for the outer element.

Also takes the props of Omit<MenuPrimitive.Trigger.Props, "className">.

Motion

Moment	Family	What it does
open	overlay, scale	A menu fades in over the overlay family's duration (200 ms in, 120 ms out by default) and scales up from 0.95 from where it is anchored (the menu's trigger, or for a submenu the item that opened it).
sub-open	overlay, scale	A submenu fades in and scales up a little from the item that opened it when the person opens it with the pointer or an arrow key, and fades out when it closes. Under reduced motion it is a short fade.

Set with --cd-motion-menubar-<moment>-* in your brand file; the families are in the design reference.