Context menu

Pro

A menu that opens where a person right-clicks (or long-presses, or presses the Menu key) on an area, in Candor's theme (Base UI). Arrow keys move along the items, Right and Left open and close submenus, Escape closes the menu. A menu is never the only way to do something: the same actions belong somewhere a person can find without knowing to right-click. An item that can't be used stays in the menu, marked and explained.

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/context-menu

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 {
  ContextMenu,
  ContextMenuCheckboxItem,
  ContextMenuContent,
  ContextMenuItem,
  ContextMenuSeparator,
  ContextMenuShortcut,
  ContextMenuSub,
  ContextMenuSubContent,
  ContextMenuSubTrigger,
  ContextMenuTrigger,
} from "@/components/candor/ui/context-menu"

export default function Example() {
  const [pinned, setPinned] = React.useState(false)
  return (
    <ContextMenu>
      {/* Focusable so the Menu key and Shift+F10 reach it; right-click or long-press also opens it. */}
      <ContextMenuTrigger tabIndex={0} className="flex h-32 w-72 items-center justify-center rounded-md border border-dashed text-sm text-muted-foreground">
        Right-click this report
      </ContextMenuTrigger>
      <ContextMenuContent>
        <ContextMenuItem>
          Open <ContextMenuShortcut>⏎</ContextMenuShortcut>
        </ContextMenuItem>
        <ContextMenuCheckboxItem checked={pinned} onCheckedChange={setPinned}>
          Pin to top
        </ContextMenuCheckboxItem>
        <ContextMenuSub>
          <ContextMenuSubTrigger>Share</ContextMenuSubTrigger>
          <ContextMenuSubContent>
            <ContextMenuItem>Copy link</ContextMenuItem>
            <ContextMenuItem locked="Only owners can invite people.">Invite people</ContextMenuItem>
          </ContextMenuSubContent>
        </ContextMenuSub>
        <ContextMenuSeparator />
        <ContextMenuItem variant="destructive">Delete report</ContextMenuItem>
      </ContextMenuContent>
    </ContextMenu>
  )
}

<ContextMenu>

No props.

Also takes the props of ContextMenuPrimitive.Root.Props.

<ContextMenuCheckboxItem>

A ContextMenu 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">.

<ContextMenuContent>

The popup of a ContextMenu, 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.

<ContextMenuGroup>

A set of related items in a ContextMenu, 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">.

<ContextMenuItem>

One action in a ContextMenu; 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">.

<ContextMenuLabel>

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

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">.

<ContextMenuPortal>

Renders a ContextMenu'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<ContextMenuPrimitive.Portal.Props, "container">.

<ContextMenuRadioGroup>

A set of ContextMenuRadioItems 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">.

<ContextMenuRadioItem>

One choice in a ContextMenuRadioGroup, 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">.

<ContextMenuSeparator>

A line between two groups of items in a ContextMenu.

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">.

<ContextMenuShortcut>

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">.

<ContextMenuSub>

A nested menu inside a ContextMenu; its ContextMenuSubTrigger opens its ContextMenuSubContent.

No props.

Also takes the props of ContextMenuPrimitive.SubmenuRoot.Props.

<ContextMenuSubContent>

The popup of a nested menu in a ContextMenu.

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.

<ContextMenuSubTrigger>

The item in a ContextMenu 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">.

<ContextMenuTrigger>

The area that opens a ContextMenu on a right-click or a long press; give the same actions a visible control too.

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

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

Motion

Moment	Family	What it does
open	overlay, scale	The menu fades in over the overlay family's duration (200 ms in, 120 ms out by default) and scales up from 0.95 from the point where it was opened (for a submenu, from 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-context-menu-<moment>-* in your brand file; the families are in the design reference.