--- name: menu-usage description: > Use after component-usage-ux when an app needs @techsio/ui-kit Menu for action, radio, checkbox, separator, or submenu items using the Zag.js menu wrapper, Button trigger, icons, and supported open/highlight/select props. metadata: component_version: "1.5.0" type: "core" library: "@techsio/ui-kit" library_version: "0.3.2" requires: "component-usage-ux app-token-overrides ux-guidelines" resources: "references/ux.md ../../references/component-contracts.md ../../references/consumer_app_usage_rules.md" sources: "https://zagjs.com/components/react/menu" contributor_sources: "libs/ui/src/molecules/menu.tsx libs/ui/src/tokens/components/molecules/_menu.css libs/ui/stories/molecules/menu.stories.tsx libs/ui/src/molecules/menu.figma.ts" audience: "consumer" --- > Portable scope: Use the installed package's exported types and bundled sibling skills. Repository source paths are optional contributor evidence, not consumer prerequisites; use the consuming app's own checks. Resolve ../../references/ paths from this skill's folder, not the app working directory. # @techsio/ui-kit Menu Usage Use Menu for contextual command lists. Use Select for choosing a value in a form, Tabs for switching panels, and Popover for custom content. ## UX/UI guidelines House rules come from the `ux-guidelines` skill (writing, formatting, states, where actions and feedback live). This section applies them to `Menu`. **Use it when** - A list of commands for one object or context: row `More actions`, account menu, overflow of page actions. **Use something else when** | Need | Use instead | | --- | --- | | Choosing a value in a form | Select | | Switching views | Tabs | | Custom content (forms, pickers) | Popover | | Searching many commands | Command | **Do** - Order items by frequency; group with separators; destructive items last, with a label that names the consequence (menu items have no danger tone). - Label items as verbs (`Duplicate`, `Archive`, `Delete…`); `…` when the item opens a dialog asking for more input. - Show shortcuts with Hotkeys when they exist. - Disable an unavailable item only if the reason is obvious; otherwise hide it. **Don't** - Put navigation and commands in one flat list without grouping. - Nest menus more than one level. **Copy and states** - Trigger for overflow: ActionIcon with `aria-label="More actions"`. **Behaviour (from the UX spec)** - Opening the menu or highlighting an item runs nothing; only activation does. Closing without choosing changes nothing. - The app confirms the result on the object or with a toast, never inside the menu. - Use `link` items for navigation and `action` items for commands, in separate groups. **Figma → code** | Figma | Code | | --- | --- | | `size=sm\|md\|lg` | `size` (`xs` is legacy, DataTable only) | | menu-trigger / submenu / check glyphs | `triggerIcon`, `submenu` items, `checkbox`/`radio` items | Full UX page (anatomy, states, behaviour, edge cases): [references/ux.md](references/ux.md). The same page renders in Storybook as *Molecules/Menu → UX guidelines*. ## Setup ```tsx import { Menu, type MenuItem } from "@techsio/ui-kit/molecules/menu" const items: MenuItem[] = [ { type: "action", value: "edit", label: "Edit", icon: "token-icon-edit" }, { type: "separator", id: "main" }, { type: "action", value: "delete", label: "Delete" }, ] runAction(value)} /> ``` Supported item types: ```text action: value, label, icon, disabled link: value, label, href, target, rel, icon, disabled radio: value, label, name, checked checkbox: value, label, checked separator: id submenu: value, label, icon, disabled, items ``` ## Core Patterns ### Model menu items as data Use `MenuItem[]`; do not render custom `
  • ` elements in apps. ### Use menu for commands Menu actions should trigger commands. For destructive commands, pair with Dialog confirmation when needed. ### Use customTrigger carefully Prefer the default Button trigger. If custom trigger is needed, pass a valid React element so Zag trigger props can be cloned onto it. ## Common Mistakes ### HIGH Custom dropdown command list Wrong: ```tsx {open && } ``` Correct: ```tsx ``` Source: libs/ui/src/molecules/menu.tsx ### HIGH Invented item type Wrong: ```tsx { type: "danger", value: "delete", label: "Delete" } ``` Correct: ```tsx { type: "action", value: "delete", label: "Delete" } ``` Source: libs/ui/src/molecules/menu.tsx ### HIGH Inline item styling Wrong: ```tsx ``` Correct: ```tsx ``` Source: libs/ui/src/tokens/components/molecules/_menu.css ## Validation Commands ```sh rg -n "role=\"menu\"|]*className=.*(absolute|shadow)|type: \"(danger|link|item)\"" apps rg -n "]*className=.*(bg-|text-|rounded-|p-|shadow-)" apps rg -n "customTrigger=|type: \"submenu\"|onCheckedChange" apps ``` ## Popup and trigger contracts Canonical sizes are sm/md/lg (default md). Legacy xs is retained only for compatibility. The trigger and popup rows follow the root size. Popup Content and Positioner use the shared opaque popup surface and managed elevation. `contextMenu` uses right-click/long press or Shift+F10/ContextMenu on the focusable trigger, not left-click. A custom trigger must be a named interactive element; its event handlers are composed with Zag behavior, including preventDefault. Boolean customTrigger values fall back to the named built-in trigger rather than producing an empty button. className is applied to the trigger. Disabled submenus remain unavailable commands and do not mount a child machine. RTL direction propagates to nested menus and mirrors their directional glyphs. Checkbox/radio items are controlled: update the items array in onCheckedChange. For radio commands, clear the previous checked item in the same name group. Nested popups may overlap their parent when necessary on narrow viewports; their positioning is capped to the available viewport so flipped submenus do not clip commands off-screen. Navigation items use `{ type: "link", value, label, href, target?, rel?, disabled? }`. They render native anchors so keyboard navigation and the optional `navigate` callback work; `navigate` receives the item value. Checkboxes and radio items also accept `disabled`. Submenus inherit direction, focus looping, typeahead, and navigation from the root. Escape or selection restores context-menu focus to its invoker; clicking or focusing outside does not steal focus back. Menus size to their content (bounded by the available viewport width) instead of inheriting the trigger width, so icon-only triggers open readable menus. Construct native MouseEvents explicitly so the dismissal path is unambiguous to readers and static analysis; no behaviour change.