# Menu
> Present a compact list of actions with keyboard navigation.
Source: https://www.honestui.com/docs/components/menu
```tsx
import {
Pause as PauseIcon,
Play as PlayIcon,
SkipBack as SkipBackIcon,
SkipForward as SkipForwardIcon,
Trash as TrashIcon,
} from "honestui/icons"
import { Button } from "@/components/honest-ui/ui/button"
import {
Menu,
MenuCheckboxItem,
MenuGroup,
MenuGroupLabel,
MenuItem,
MenuPopup,
MenuRadioGroup,
MenuRadioItem,
MenuSeparator,
MenuShortcut,
MenuSub,
MenuSubPopup,
MenuSubTrigger,
MenuTrigger,
} from "@/components/honest-ui/ui/menu"
export function MenuDemo() {
return (
)
}
```
## Overview [#overview]
Use Menu for a compact list of actions or choices opened from a trigger: overflow actions behind an icon button, account menus, row actions, editor commands, and grouped command lists. Opening the menu is a deliberate act, so its contents can be dense — but the actions themselves should still be reachable elsewhere if they are frequent or essential.
Do not use a menu for primary navigation when links should stay visible and crawlable, and do not use one when people must compare options side by side; menus hide everything except the highlighted item. For text entry or filtering over long lists, use Autocomplete or Combobox instead.
## Anatomy [#anatomy]
A menu has a trigger, popup, items, optional groups with labels, separators, checkbox items, radio groups, shortcut hints, and nested submenus. `MenuPopup` renders its own portal and positioner, so alignment props like `align` and `sideOffset` sit directly on it. Each part is defined in `menu.tsx` and exported as a named PascalCase component; `dropdown-menu.tsx` re-exports the same parts under `DropdownMenu*` names.
## Behavior [#behavior]
**Opening.** Clicking, pressing Enter or Space, or pressing Arrow Down on the trigger opens the menu and moves focus to the first item. By default the menu is modal while open: page scroll locks and pointer interaction outside is disabled. Set `openOnHover` on the trigger to also open after a short hover delay.
**Navigating.** Arrow Up and Arrow Down move the highlight, wrapping around by default (`loopFocus`); Home and End jump to the first and last item. Typing letters jumps straight to matching item labels — the typeahead resets shortly after you stop typing. Pass `label` to an item whose visible text differs from what should match.
**Activating.** Enter and Space activate the highlighted item, and items close the menu after activating by default (`closeOnClick`). Checkbox and radio items keep their checked state visible through the leading indicator column. Set `closeOnClick={false}` on items that toggle something without dismissing their context.
**Closing.** Escape closes the menu and returns focus to the trigger. Outside clicks close it as well. Pass `finalFocus` on the popup to send focus elsewhere on close.
**Submenus.** Highlighting a submenu trigger and pressing Arrow Right opens it (Arrow Left mirrors in right-to-left layouts); Escape closes only the child menu, leaving the parent open.
**Scrolling.** `MenuPopup` limits itself to Base UI's available viewport height and scrolls vertically when its content is taller, with `overscroll-contain` so wheel and touch scrolling never chains to the page. To add a smaller product-specific limit, pass a `max-height` class that keeps `--available-height` as the upper bound, such as `max-h-[min(18rem,var(--available-height))]`.
## Accessibility [#accessibility]
The trigger announces itself with `aria-haspopup="menu"` and `aria-expanded`; the popup carries `role="menu"` and is labelled by the trigger. All navigation works with arrows, typeahead, Home/End, Enter, and Space, including items outside the initially visible scroll area — scrolling to reach them happens inside the popup, not the page.
Checkbox and radio items expose their checked state to assistive technology; use them only when the checked state genuinely matters inside the menu. Disabled items stay focusable but inert and are dimmed through tokens rather than removed, so people can find them and hear that they exist.
Colors come from theme tokens, so highlights, disabled states, and the destructive variant adapt to dark mode automatically. Item padding uses logical properties, so indentation and shortcut alignment mirror in right-to-left locales; the submenu chevron does not flip automatically, so verify direction under `dir="rtl"`. Long labels wrap within the item rather than widening the popup past the viewport, since horizontal overflow is hidden.
If a list becomes difficult to scan even with scrolling and typeahead, use Autocomplete or Combobox instead — search beats forcing people through a very long action menu.
## Installation [#installation]
Install the following dependencies:
```bash
npm install @base-ui/react
```
Import the following variables into your CSS file
```css
@theme inline {
--color-destructive-foreground: var(--destructive-foreground);
}
:root {
--destructive-foreground: oklch(0.505 0.213 27.518);
}
.dark {
--destructive-foreground: oklch(0.704 0.191 22.216);
}
```
Copy and paste the following code into your project.
### components/ui/menu.tsx
```tsx
"use client"
import * as React from "react"
import { Menu as MenuPrimitive } from "@base-ui/react/menu"
import { Check as CheckIcon, ChevronRight as ChevronRightIcon } from "honestui/icons"
import { cn } from "@/lib/utils"
const Menu = MenuPrimitive.Root
const MenuPortal = MenuPrimitive.Portal
function MenuTrigger({ className, ...props }: MenuPrimitive.Trigger.Props) {
return (
)
}
function MenuPopup({
className,
sideOffset = 4,
align = "center",
alignOffset = 0,
...props
}: MenuPrimitive.Popup.Props & {
align?: MenuPrimitive.Positioner.Props["align"]
sideOffset?: MenuPrimitive.Positioner.Props["sideOffset"]
alignOffset?: MenuPrimitive.Positioner.Props["alignOffset"]
}) {
return (
)
}
function MenuGroup(props: MenuPrimitive.Group.Props) {
return
}
function MenuItem({
className,
inset,
variant = "default",
...props
}: MenuPrimitive.Item.Props & {
inset?: boolean
variant?: "default" | "destructive"
}) {
return (
)
}
function MenuCheckboxItem({
className,
children,
checked,
...props
}: MenuPrimitive.CheckboxItem.Props) {
return (
{children}
)
}
function MenuRadioGroup(props: MenuPrimitive.RadioGroup.Props) {
return
}
function MenuRadioItem({
className,
children,
...props
}: MenuPrimitive.RadioItem.Props) {
return (
{children}
)
}
function MenuGroupLabel({
className,
inset,
...props
}: MenuPrimitive.GroupLabel.Props & {
inset?: boolean
}) {
return (
)
}
function MenuSeparator({ className, ...props }: MenuPrimitive.Separator.Props) {
return (
)
}
function MenuShortcut({ className, ...props }: React.ComponentProps<"span">) {
return (
)
}
function MenuSub(props: MenuPrimitive.SubmenuRoot.Props) {
return
}
function MenuSubTrigger({
className,
inset,
children,
...props
}: MenuPrimitive.SubmenuTrigger.Props & {
inset?: boolean
}) {
return (
{children}
)
}
function MenuSubPopup({
className,
sideOffset = 0,
alignOffset = -4,
align = "start",
...props
}: MenuPrimitive.Popup.Props & {
align?: MenuPrimitive.Positioner.Props["align"]
sideOffset?: MenuPrimitive.Positioner.Props["sideOffset"]
alignOffset?: MenuPrimitive.Positioner.Props["alignOffset"]
}) {
return (
)
}
export {
Menu,
Menu as DropdownMenu,
MenuPortal,
MenuPortal as DropdownMenuPortal,
MenuTrigger,
MenuTrigger as DropdownMenuTrigger,
MenuPopup,
MenuPopup as DropdownMenuContent,
MenuGroup,
MenuGroup as DropdownMenuGroup,
MenuItem,
MenuItem as DropdownMenuItem,
MenuCheckboxItem,
MenuCheckboxItem as DropdownMenuCheckboxItem,
MenuRadioGroup,
MenuRadioGroup as DropdownMenuRadioGroup,
MenuRadioItem,
MenuRadioItem as DropdownMenuRadioItem,
MenuGroupLabel,
MenuGroupLabel as DropdownMenuLabel,
MenuSeparator,
MenuSeparator as DropdownMenuSeparator,
MenuShortcut,
MenuShortcut as DropdownMenuShortcut,
MenuSub,
MenuSub as DropdownMenuSub,
MenuSubTrigger,
MenuSubTrigger as DropdownMenuSubTrigger,
MenuSubPopup,
MenuSubPopup as DropdownMenuSubContent,
}
```
Update the import paths to match your project setup.
## Usage [#usage]
```tsx
import {
Menu,
MenuCheckboxItem,
MenuGroup,
MenuGroupLabel,
MenuItem,
MenuPopup,
MenuRadioGroup,
MenuRadioItem,
MenuSeparator,
MenuSub,
MenuSubPopup,
MenuSubTrigger,
MenuTrigger,
} from "@/components/ui/menu";
```
```tsx
```
`MenuShortcut` renders a decorative hint span aligned to the end edge; it does not register a keyboard shortcut by itself.
## Don't do this [#dont-do-this]
### Navigating with onClick [#navigating-with-onclick]
```tsx
// Bad
```
```tsx
// Good
}>Docs
```
The bad version is a div pretending to be a link: it cannot be opened in a new tab with middle-click or Cmd click, shows no URL on hover, and assistive technology announces a command rather than a destination. Rendering through `Link` keeps real anchor semantics while inheriting the item's styling and keyboard behavior.
### Fake keyboard shortcuts [#fake-keyboard-shortcuts]
```tsx
// Bad
```
```tsx
// Good
useHotkey("mod+d", () => setTheme("dark"))
```
`MenuShortcut` is purely visual. Advertising a shortcut that does nothing breaks trust twice: once when it fails inside the app, and once when someone tries it from muscle memory outside the menu. Register the binding globally before printing it.
### Text fields inside the popup [#text-fields-inside-the-popup]
```tsx
// Bad
```
```tsx
// Good
{/* Filterable list */}
```
Menus intercept keystrokes for typeahead and arrow-key navigation, so a text input inside the popup fights the component for every keypress and the highlight jumps as people type. When a list needs filtering, use a component built around text entry.
## Examples [#examples]
### Open on Hover [#open-on-hover]
Hover opening suits toolbar-style triggers; keep click working by default elsewhere because hover menus misfire on touch screens.
```tsx
import { Button } from "@/components/honest-ui/ui/button"
import {
Menu,
MenuItem,
MenuPopup,
MenuTrigger,
} from "@/components/honest-ui/ui/menu"
export function MenuHoverDemo() {
return (
)
}
```
### With Checkbox [#with-checkbox]
Toggleable settings keep the menu open context while showing state.
```tsx
import { Button } from "@/components/honest-ui/ui/button"
import {
Menu,
MenuCheckboxItem,
MenuPopup,
MenuTrigger,
} from "@/components/honest-ui/ui/menu"
export function MenuCheckboxDemo() {
return (
)
}
```
### With Radio Group [#with-radio-group]
One selected value per group, indicated in the leading column.
```tsx
import { Button } from "@/components/honest-ui/ui/button"
import {
Menu,
MenuPopup,
MenuRadioGroup,
MenuRadioItem,
MenuTrigger,
} from "@/components/honest-ui/ui/menu"
export function MenuRadioGroupDemo() {
return (
)
}
```
### With Link [#with-link]
Items rendered as real links keep middle-click and new-tab behavior.
```tsx
import Link from "next/link"
import { Button } from "@/components/honest-ui/ui/button"
import {
Menu,
MenuItem,
MenuPopup,
MenuTrigger,
} from "@/components/honest-ui/ui/menu"
export function MenuLinkDemo() {
return (
)
}
```
### With Group Label [#with-group-label]
Labels give screen readers group names and sighted users scan lines.
```tsx
import { Button } from "@/components/honest-ui/ui/button"
import {
Menu,
MenuItem,
MenuPopup,
MenuSeparator,
MenuTrigger,
} from "@/components/honest-ui/ui/menu"
export function MenuGroupLabelsDemo() {
return (
)
}
```
### Icon-only trigger [#icon-only-trigger]
An icon-only trigger needs an explicit `aria-label` — the menu's accessible name comes from it.
```tsx
import { Ellipsis as MoreHorizontalIcon } from "honestui/icons"
import { Button } from "@/components/honest-ui/ui/button"
import { Menu, MenuItem, MenuPopup, MenuTrigger } from "@/components/honest-ui/ui/menu"
export function MenuProjectActions() {
return (
)
}
```
### Scrollable Menu [#scrollable-menu]
A product-specific cap keeps long lists manageable while `--available-height` remains the ceiling.
```tsx
import { Button } from "@/components/honest-ui/ui/button"
import {
Menu,
MenuGroup,
MenuGroupLabel,
MenuItem,
MenuPopup,
MenuTrigger,
} from "@/components/honest-ui/ui/menu"
const workspaces = [
"Acme Studio",
"Atlas Research",
"Beacon Labs",
"Cedar Health",
"Field Notes",
"Good Measure",
"Harbor Finance",
"Honest UI",
"Juniper Works",
"Northstar",
"Open Assembly",
"Signal House",
]
export function MenuScrollable() {
return (
)
}
```
### Nested Menu [#nested-menu]
Submenus preserve arrow-key navigation and close independently on Escape. Keep nesting shallow: each level costs precision and memory.
```tsx
import { Button } from "@/components/honest-ui/ui/button"
import {
Menu,
MenuItem,
MenuPopup,
MenuSub,
MenuSubPopup,
MenuSubTrigger,
MenuTrigger,
} from "@/components/honest-ui/ui/menu"
export function MenuNestedDemo() {
return (
)
}
```
### Open a Dialog [#open-a-dialog]
Actions that need more space or confirmation hand off to a Dialog on selection.
```tsx
"use client"
import * as React from "react"
import { Button } from "@/components/honest-ui/ui/button"
import {
Dialog,
DialogClose,
DialogDescription,
DialogFooter,
DialogHeader,
DialogPopup,
DialogTitle,
} from "@/components/honest-ui/ui/dialog"
import {
Menu,
MenuItem,
MenuPopup,
MenuTrigger,
} from "@/components/honest-ui/ui/menu"
export function DialogFromMenuDemo() {
const [dialogOpen, setDialogOpen] = React.useState(false)
return (
<>
)
}
```
## API reference [#api-reference]
All parts forward their matching Base UI Menu props from `@base-ui/react`. Honest UI adds:
| Part | Props | Default |
| ---------------------------------- | ------------------------------------ | -------------------- |
| `MenuPopup` / `MenuSubPopup` | `sideOffset`, `align`, `alignOffset` | `4`, `center`, `0` |
| `MenuItem` | `inset`, `variant` | `false`, `"default"` |
| `MenuGroupLabel`, `MenuSubTrigger` | `inset` | `false` |
The root accepts controlled `open` / `onOpenChange`, `loopFocus` (wraps arrow navigation, `true` by default), `modal` (scroll lock and outside-pointer blocking, `true` by default), and `orientation`. Items accept `disabled`, `closeOnClick` (`true` by default), and a `label` override for typeahead matching. The popup accepts `finalFocus` for post-close focus placement. `MenuSubPopup` tightens the offsets so submenus hug their trigger. Every `Menu*` export is also aliased as `DropdownMenu*` from the same file.
See the [Base UI Menu API](https://base-ui.com/react/components/menu#api-reference) for focus, submenu, checkbox, and radio behavior.