ui/components/menu

1 import { Menu, MenuDivider, MenuItem } from "@/components/ui/menu";2 3 export default function MenuDefault() {4   return (5     <div className="w-64 border border-border">6       <Menu aria-label="File actions">7         <MenuItem id="new" hotkey={1}>8           New File9         </MenuItem>10         <MenuItem id="open" hotkey={2}>11           Open File12         </MenuItem>13         <MenuItem id="save" hotkey={3}>14           Save15         </MenuItem>16         <MenuDivider />17         <MenuItem id="delete" variant="danger">18           Delete19         </MenuItem>20       </Menu>21     </div>22   );23 }24

Installation

$pnpm exec dgadd add ui/menu

[Installs to]src/components/ui/menu[Item]ui/menu

dgadd is not public on npm yet. Until the first release, pack @diffgazer/add from the repository and install that tarball into this app, which is what puts dgadd on pnpm exec.

UI components require Tailwind CSS v4. Local copy mode imports src/styles/styles.css; package mode uses @diffgazer/ui CSS once packages are available.

Usage

tsx

1 import { Menu, MenuDivider, MenuItem } from "@/components/ui/menu";2 3 export default function MenuDefault() {4   return (5     <div className="w-64 border border-border">6       <Menu aria-label="File actions">7         <MenuItem id="new" hotkey={1}>8           New File9         </MenuItem>10         <MenuItem id="open" hotkey={2}>11           Open File12         </MenuItem>13         <MenuItem id="save" hotkey={3}>14           Save15         </MenuItem>16         <MenuDivider />17         <MenuItem id="delete" variant="danger">18           Delete19         </MenuItem>20       </Menu>21     </div>22   );23 }24

Examples

Detail Variant

Preview

tsx

1 import { Menu, MenuItem } from "@/components/ui/menu";2 3 export default function MenuDetail() {4   return (5     <div className="w-80 border border-border">6       <Menu variant="detail" aria-label="Project menu">7         <MenuItem id="overview" value="12 files">8           Overview9         </MenuItem>10         <MenuItem id="files" value="Modified">11           Source Files12         </MenuItem>13         <MenuItem id="tests" value="Passing" valueVariant="success">14           Test Suite15         </MenuItem>16         <MenuItem id="config" value="3 warnings" valueVariant="muted">17           Configuration18         </MenuItem>19       </Menu>20     </div>21   );22 }23

Grouped with Labels

Preview

tsx

1 import { Menu, MenuGroup, MenuItem } from "@/components/ui/menu";2 3 export default function MenuGrouped() {4   return (5     <div className="w-64 border border-border">6       <Menu aria-label="Editor actions">7         <MenuGroup label="FILE">8           <MenuItem id="new" hotkey={1}>9             New File10           </MenuItem>11           <MenuItem id="open" hotkey={2}>12             Open File13           </MenuItem>14           <MenuItem id="save" hotkey={3}>15             Save16           </MenuItem>17         </MenuGroup>18         <MenuGroup label="EDIT">19           <MenuItem id="undo" hotkey={4}>20             Undo21           </MenuItem>22           <MenuItem id="redo" hotkey={5}>23             Redo24           </MenuItem>25           <MenuItem id="find" hotkey={6}>26             Find27           </MenuItem>28         </MenuGroup>29         <MenuGroup label="VIEW">30           <MenuItem id="terminal" hotkey={7}>31             Terminal32           </MenuItem>33           <MenuItem id="sidebar" hotkey={8}>34             Sidebar35           </MenuItem>36           <MenuItem id="minimap" hotkey={9}>37             Minimap38           </MenuItem>39         </MenuGroup>40       </Menu>41     </div>42   );43 }44

Checkbox and Radio Items

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import {5   Menu,6   MenuDivider,7   MenuItemCheckbox,8   MenuItemRadio,9   MenuLabel,10 } from "@/components/ui/menu";11 12 export default function MenuCheckboxRadio() {13   const [showHidden, setShowHidden] = useState(true);14   const [lineNumbers, setLineNumbers] = useState(true);15   const [wordWrap, setWordWrap] = useState(false);16   const [minimap, setMinimap] = useState(true);17   const [sortBy, setSortBy] = useState("name");18 19   return (20     <div className="w-64 border border-border">21       <Menu aria-label="View options" selectedId={sortBy} onSelect={setSortBy}>22         <MenuLabel>VIEW OPTIONS</MenuLabel>23         <MenuItemCheckbox id="hidden" checked={showHidden} onChange={setShowHidden}>24           Show Hidden Files25         </MenuItemCheckbox>26         <MenuItemCheckbox id="line-numbers" checked={lineNumbers} onChange={setLineNumbers}>27           Line Numbers28         </MenuItemCheckbox>29         <MenuItemCheckbox id="word-wrap" checked={wordWrap} onChange={setWordWrap}>30           Word Wrap31         </MenuItemCheckbox>32         <MenuItemCheckbox id="minimap" checked={minimap} onChange={setMinimap}>33           Minimap34         </MenuItemCheckbox>35         <MenuDivider />36         <MenuLabel>SORT BY</MenuLabel>37         <MenuItemRadio id="name">Name</MenuItemRadio>38         <MenuItemRadio id="date">Date Modified</MenuItemRadio>39         <MenuItemRadio id="size">Size</MenuItemRadio>40         <MenuItemRadio id="type">Type</MenuItemRadio>41       </Menu>42     </div>43   );44 }45

Custom Icons

Preview

tsx

1 "use client";2 3 import { Menu, MenuDivider, MenuItem } from "@/components/ui/menu";4 5 export default function MenuIcons() {6   return (7     <div className="w-64 border border-border">8       <Menu aria-label="Actions">9         <MenuItem id="new" icon={<span>+</span>} hotkey="Ctrl+N">10           New File11         </MenuItem>12         <MenuItem id="open" icon={<span>^</span>} hotkey="Ctrl+O">13           Open Folder14         </MenuItem>15         <MenuItem id="search" icon={<span>/</span>} hotkey="Ctrl+P">16           Search Files17         </MenuItem>18         <MenuDivider />19         <MenuItem id="rename" icon={<span>~</span>} hotkey="F2">20           Rename21         </MenuItem>22         <MenuItem id="move" icon={<span>&gt;</span>}>23           Move to...24         </MenuItem>25         <MenuDivider />26         <MenuItem id="delete" icon={<span>x</span>} variant="danger" hotkey="Del">27           Delete File28         </MenuItem>29       </Menu>30     </div>31   );32 }33

Disabled Items

Preview

tsx

1 import { Menu, MenuDivider, MenuItem } from "@/components/ui/menu";2 3 /**4  * Disabled items stay in the navigation order and keep announcing themselves,5  * they just cannot be activated. The highlight still lands on them so keyboard6  * users learn the item exists.7  */8 export default function MenuDisabled() {9   return (10     <div className="w-64 border border-border">11       <Menu aria-label="File actions" defaultHighlighted="paste">12         <MenuItem id="copy" hotkey={1}>13           Copy14         </MenuItem>15         <MenuItem id="paste" hotkey={2} disabled>16           Paste17         </MenuItem>18         <MenuItem id="duplicate" hotkey={3} disabled>19           Duplicate20         </MenuItem>21         <MenuDivider />22         <MenuItem id="delete" variant="danger" disabled>23           Delete24         </MenuItem>25       </Menu>26     </div>27   );28 }29

Submenu

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import {5   Menu,6   MenuDivider,7   MenuItem,8   MenuSub,9   MenuSubContent,10   MenuSubTrigger,11 } from "@/components/ui/menu";12 13 export default function MenuSubmenu() {14   const [lastAction, setLastAction] = useState<string | null>(null);15 16   return (17     <div className="w-64 border border-border">18       <Menu aria-label="Application menu" onSelect={setLastAction}>19         <MenuItem id="new" hotkey={1}>20           New File21         </MenuItem>22         <MenuItem id="open" hotkey={2}>23           Open File24         </MenuItem>25         <MenuDivider />26         <MenuSub>27           <MenuSubTrigger id="edit">Edit</MenuSubTrigger>28           <MenuSubContent>29             <MenuItem id="undo">Undo</MenuItem>30             <MenuItem id="redo">Redo</MenuItem>31             <MenuDivider />32             <MenuItem id="cut">Cut</MenuItem>33             <MenuItem id="copy">Copy</MenuItem>34             <MenuItem id="paste">Paste</MenuItem>35           </MenuSubContent>36         </MenuSub>37         <MenuSub>38           <MenuSubTrigger id="view">View</MenuSubTrigger>39           <MenuSubContent>40             <MenuItem id="zoom-in">Zoom In</MenuItem>41             <MenuItem id="zoom-out">Zoom Out</MenuItem>42             <MenuItem id="reset-zoom">Reset Zoom</MenuItem>43           </MenuSubContent>44         </MenuSub>45         <MenuDivider />46         <MenuItem id="quit" variant="danger">47           Quit48         </MenuItem>49       </Menu>50       {lastAction && (51         <p className="px-3 py-2 text-xs text-muted-foreground border-t border-border">52           Last action: {lastAction}53         </p>54       )}55     </div>56   );57 }58

Submenu (drill-down stack)

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import {5   Menu,6   MenuDivider,7   MenuItem,8   MenuSub,9   MenuSubContent,10   MenuSubTrigger,11 } from "@/components/ui/menu";12 13 export default function MenuSubmenuStack() {14   const [lastAction, setLastAction] = useState<string | null>(null);15 16   return (17     <div className="w-64 border border-border">18       <Menu aria-label="Application menu" onSelect={setLastAction}>19         <MenuItem id="new" hotkey={1}>20           New File21         </MenuItem>22         <MenuItem id="open" hotkey={2}>23           Open File24         </MenuItem>25         <MenuDivider />26         <MenuSub mode="stack">27           <MenuSubTrigger id="edit">Edit</MenuSubTrigger>28           <MenuSubContent>29             <MenuItem id="undo">Undo</MenuItem>30             <MenuItem id="redo">Redo</MenuItem>31             <MenuDivider />32             <MenuItem id="cut">Cut</MenuItem>33             <MenuItem id="copy">Copy</MenuItem>34             <MenuItem id="paste">Paste</MenuItem>35           </MenuSubContent>36         </MenuSub>37         <MenuSub mode="stack">38           <MenuSubTrigger id="view">View</MenuSubTrigger>39           <MenuSubContent>40             <MenuItem id="zoom-in">Zoom In</MenuItem>41             <MenuItem id="zoom-out">Zoom Out</MenuItem>42             <MenuItem id="reset-zoom">Reset Zoom</MenuItem>43           </MenuSubContent>44         </MenuSub>45         <MenuDivider />46         <MenuItem id="quit" variant="danger">47           Quit48         </MenuItem>49       </Menu>50       {lastAction && (51         <p className="px-3 py-2 text-xs text-muted-foreground border-t border-border">52           Last action: {lastAction}53         </p>54       )}55     </div>56   );57 }58

Controlled Keyboard Navigation

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { Menu, MenuDivider, MenuItem } from "@/components/ui/menu";5 6 const hotkeys: Record<string, string> = {7   "1": "new",8   "2": "open",9   "3": "save",10   "4": "export",11 };12 13 export default function MenuKeyboard() {14   const [selectedId, setSelectedId] = useState<string | null>("new");15 16   return (17     <div className="w-64 border border-border">18       <Menu19         selectedId={selectedId}20         onSelect={setSelectedId}21         onKeyDown={(event) => {22           const id = hotkeys[event.key];23           if (!id) return;24           event.preventDefault();25           setSelectedId(id);26         }}27         aria-label="File actions"28       >29         <MenuItem id="new" hotkey={1}>30           New File31         </MenuItem>32         <MenuItem id="open" hotkey={2}>33           Open File34         </MenuItem>35         <MenuItem id="save" hotkey={3}>36           Save37         </MenuItem>38         <MenuItem id="export" hotkey={4}>39           Export40         </MenuItem>41         <MenuDivider />42         <MenuItem id="delete" variant="danger">43           Delete44         </MenuItem>45       </Menu>46       {/* One hint line: each hint stays whole, wrapping happens only at the separators. */}47       <p className="flex flex-wrap items-center gap-x-2 whitespace-nowrap px-3 py-2 text-xs text-muted-foreground border-t border-border">48         <span>tab in</span>49         <span aria-hidden="true">·</span>50         <span>↑↓ nav</span>51         <span aria-hidden="true">·</span>52         <span>1-4 jump</span>53         <span aria-hidden="true">·</span>54         <span>⏎ select</span>55       </p>56     </div>57   );58 }59

API Reference

Name	Type	Default	Description
selectedId	string \| null	—	Controlled selected item id. Pair with onSelect. Switches item role to "menuitemradio" with aria-checked.
defaultSelectedId	string \| null	null	Initial selected id for uncontrolled mode. Setting this to a non-null value enables selection semantics.
highlighted	string \| null	—	Controlled highlighted (focused) item id. Pair with onHighlightChange.
defaultHighlighted	string \| null	null	Initial highlighted id for uncontrolled mode.
onSelect	(id: string) => void	—	Fired when an item is activated by click, Enter, or Space.
onHighlightChange	(value: string \| null) => void	—	Fired when the highlighted item changes via arrow keys, typeahead, or mouse.
onClose	() => void	—	Fired when Escape or Tab is pressed.
variant	"default" \| "detail"	"default"	Visual layout. `detail` renders taller rows with a right-aligned value column, for menus where each item carries a status or summary value.
wrap	boolean	true	When true, arrow navigation wraps from last item to first and vice versa.
typeahead	boolean	true	Enable type-ahead character search to jump to matching items. Submenus inherit this setting. Disable when every printable key the menu advertises belongs to an external hotkey layer.
autoFocus	boolean	—	Auto-focus the menu container on mount so arrow keys work without an explicit click.
aria-label	string	—	Accessible name for the menu container (role="menu").
childrenrequired	ReactNode	—	MenuItem and MenuDivider children.

MenuItem

Name	Type	Default	Description
idrequired	string	—	Stable identifier matched against selectedId/highlighted and passed to onSelect.
disabled	boolean	false	Disables activation while keeping the item in the navigation order with aria-disabled.
variant	"default" \| "danger"	"default"	Danger applies destructive coloring for destructive actions.
hotkey	number \| string	—	Decorative hotkey label rendered as [n]. Does not bind a key listener.
value	ReactNode	—	Detail variant only. Right-aligned value (badge, count, or status text).
valueVariant	"default" \| "success" \| "success-badge" \| "muted"	"default"	Color treatment for the detail value. The success variants prefix a ✓ so the passing state does not rest on color alone.
icon	ReactNode	—	Leading icon rendered in the indicator slot. Replaces the default ▌/> indicator when provided.
childrenrequired	ReactNode	—	Item label.

MenuDivider

Name	Type	Default	Description
className	string	—	Class applied to the separator. Renders role="separator" with horizontal orientation.

MenuGroup

Name	Type	Default	Description
label	ReactNode	—	Optional label rendered via MenuLabel. When provided, the group is labelled via aria-labelledby.
childrenrequired	ReactNode	—	MenuItem, MenuItemCheckbox, MenuItemRadio, or MenuDivider children.

MenuLabel

Name	Type	Default	Description
childrenrequired	ReactNode	—	Label text for a MenuGroup.

MenuItemCheckbox

Name	Type	Default	Description
idrequired	string	—	Stable identifier for the checkbox item.
checked	boolean	—	Controlled checked state.
defaultChecked	boolean	false	Initial checked state for uncontrolled mode.
onChange	(checked: boolean) => void	—	Fired when the checked state toggles.
disabled	boolean	false	Disables the checkbox item.
childrenrequired	ReactNode	—	Checkbox item label.

MenuItemRadio

Name	Type	Default	Description
idrequired	string	—	Stable identifier for the radio item.
disabled	boolean	false	Disables the radio item.
childrenrequired	ReactNode	—	Radio item label.

MenuSub

Name	Type	Default	Description
open	boolean	—	Controlled open state for the submenu.
defaultOpen	boolean	false	Initial open state for uncontrolled mode.
onOpenChange	(open: boolean) => void	—	Fired when the submenu open state changes.
mode	"flyout" \| "stack" \| "auto"	"auto"	Presentation. "flyout" opens a side-anchored panel; "stack" drills down inside the parent panel with a back row. "auto" picks stack on touch or below 640px, where a side flyout has nowhere to go.
childrenrequired	ReactNode	—	MenuSubTrigger and MenuSubContent children.

MenuSubTrigger

Name	Type	Default	Description
idrequired	string	—	Stable identifier for the submenu trigger item.
disabled	boolean	false	Disables the submenu trigger.
childrenrequired	ReactNode	—	Trigger label.

MenuSubContent

Name	Type	Default	Description
childrenrequired	ReactNode	—	Menu items rendered inside the submenu floating panel.
sideOffset	number	0	Offset from the trigger edge in pixels.

Data attributes

Attribute	Applies to	Values	Description
data-highlighted	MenuItem / MenuItemCheckbox / MenuItemRadio / MenuSubTrigger	present when highlighted	Marks the active descendant for keyboard highlight styling, including disabled items that remain discoverable but cannot activate.
data-hovered	MenuItem / MenuItemCheckbox / MenuItemRadio / MenuSubTrigger / MenuStackBack	present when pointer-hovered	Cosmetic pointer hover styling hook. It never enters the accessibility tree and does not move the active descendant.
data-state	MenuItemCheckbox / MenuItemRadio	"checked" \| "unchecked"	Enumerated check state for styling hooks in copy mode.
data-selected	MenuItem / MenuItemRadio	present when selected	Marks the selected item in selection/radio menu modes.
data-value	MenuItem / MenuItemCheckbox / MenuItemRadio / MenuSubTrigger	item id	Stable item id used by keyboard navigation and typeahead.
data-diffgazer-navigation-item	Menu items	"true"	Marks descendants discoverable by @diffgazer/keys navigation utilities.

Accessibility

Keyboard Navigation

Keyboard navigation is built-in. The Controlled Keyboard Navigation example above demonstrates controlled mode with explicit state management. Arrow keys and their vim aliases j/k move the highlight, Enter activates selection.

Key	Action
ArrowUp / k	Moves highlight to the previous item. Disabled items remain navigable and announced but cannot be activated.
ArrowDown / j	Moves highlight to the next item. Disabled items remain navigable and announced but cannot be activated.
Home / End	Moves highlight to the first or last item, including disabled items that remain nonactivatable.
Enter / Space	Activates the highlighted item or toggles checkbox/radio items.
Printable character	Starts or extends a typeahead query and moves the highlight to the matching item. j/k still move the highlight on an empty query buffer and only extend a query already in progress.
Escape / Tab	Calls onClose on the root menu.
ArrowRight	Opens the highlighted nested submenu. On a leaf item it does nothing and stays within the current submenu.
ArrowLeft / Escape	Closes submenu content and returns focus to its trigger.

Notes

Composition Contract

Use Menu.Item and Menu.Divider as explicit children in the Menu JSX tree. Custom item UI belongs inside Menu.Item. Components that create items internally from an opaque wrapper are not part of the current public contract.

Row Columns

A default row is icon, label, accelerator. The label column starts immediately after the icon and the [n] accelerator is pushed to the row end, so rows with and without an accelerator keep their labels aligned. Detail rows keep the same shape with a right-aligned value instead of an accelerator.

Submenu presentation

Menu.Sub takes mode="flyout" | "stack" | "auto" (default "auto"). A flyout is a side-anchored panel. A stack is a drill-down: the submenu replaces the item list inside the SAME panel, at the same width and left edge, with a sticky back row that is both the breadcrumb and the pop control. "auto" resolves to stack at coarse pointer or below 640px, resolved before the submenu ever opens so touch never sees a flyout frame — a side flyout has nowhere to go on a narrow screen and ends up shifted back over the rows it came from, hiding them. The key model is identical in both: ArrowRight/Enter pushes, ArrowLeft/Escape pops, and Escape at the root level still closes the menu. While drilled in, the parent items are removed from the DOM tree that navigation reads, so arrow keys and typeahead never reach a row the user cannot see.

Built-in Keyboard Navigation

Menu includes keyboard navigation via useListbox (Arrow keys and their vim aliases j/k, Home/End, Enter/Space). For custom key bindings or cross-component navigation, use the highlighted, onHighlightChange, and onKeyDown props to add external handlers alongside the built-in behavior.

Source

Install via CLI: pnpm exec dgadd add ui/menu. Keyboard hooks are included as standalone copies. For the full experience, use --integration keys.

Highlighted source loads after this disclosure opens. Browse the source repository.

Menu

Installation

Usage

Examples

Detail Variant

Grouped with Labels

Checkbox and Radio Items

Custom Icons

Disabled Items

Submenu

Submenu (drill-down stack)

Controlled Keyboard Navigation

API Reference

Menu

MenuItem

MenuDivider

MenuGroup

MenuLabel

MenuItemCheckbox

MenuItemRadio

MenuSub

MenuSubTrigger

MenuSubContent

Data attributes

Accessibility

Keyboard Navigation

Notes

Composition Contract

Row Columns

Submenu presentation

Built-in Keyboard Navigation

Source

View component source (52 files)