# Menu (/cloud/headless/menu) {/* Generated by scripts/sync-base-ui-reference.mjs. Edit the script, not this file. */} ## In Nyte [#in-nyte] ```ts title="Import" import { Menu } from "@nyte-ai/ui/menu"; ``` `@nyte-ai/ui/menu` re-exports the Base UI namespace unchanged. There is no Nyte styling on this subpath; the consumer owns every class, StyleX style, and layout decision. Base UI owns the interaction model, keyboard handling, focus management, and ARIA below. Consumed by: * `desktop/src/renderer/src/components/menu.tsx` The rest of this page is Base UI's documentation for `@base-ui/react/menu`, reproduced verbatim under the MIT license, © Material-UI SAS. Component paths in examples refer to the Base UI package; in Nyte, import from the subpath above. ## Anatomy [#anatomy] Import the component and assemble its parts: ```jsx title="Anatomy" import { Menu } from '@base-ui/react/menu'; ; ``` ## Examples [#examples] ### Open on hover [#open-on-hover] To create a menu that opens on hover, add the `openOnHover` prop to ``. You can additionally configure how quickly the menu opens on hover using the `delay` prop. ### Checkbox items [#checkbox-items] Use the `` part to create a menu item that can toggle a setting on or off. ### Radio items [#radio-items] Use the `` and `` parts to create menu items that work like radio buttons. ### Close on click [#close-on-click] Use the `closeOnClick` prop to change whether the menu closes when an item is clicked. ```jsx title="Control whether the menu closes on click" // Close the menu when a checkbox item is clicked // Keep the menu open when an item is clicked ``` ### Group labels [#group-labels] Use the `` part to add a label to a `` or ``. ### Nested menu [#nested-menu] To create a submenu, nest another menu inside the parent menu with ``. Use the `` part for the menu item that opens the nested menu. ```jsx title="Adding a submenu" {/* @highlight-start */} {/* Submenu */} {/* @highlight */} {/* prettier-ignore */} {/* Submenu items */} {/* @highlight-end */} ``` ### Navigate to another page [#navigate-to-another-page] Use the `` part to create a link. ```jsx title="A menu item that opens a link" Go to Projects ``` ### Open a dialog [#open-a-dialog] In order to open a dialog using a menu, control the dialog state and open it imperatively using the `onClick` handler on the menu item. ```tsx title="Connecting a dialog to a menu" import * as React from 'react'; import { Dialog } from '@base-ui/react/dialog'; import { Menu } from '@base-ui/react/menu'; function ExampleMenu() { const [dialogOpen, setDialogOpen] = React.useState(false); return ( Open menu {/* @highlight-start */} {/* Open the dialog when the menu item is clicked */} setDialogOpen(true)}>Open dialog {/* @highlight-end */} {/* @highlight-start */} {/* Control the dialog state */} {/* @highlight-end */} {/* prettier-ignore */} {/* Rest of the dialog */} ); } ``` ### Detached triggers [#detached-triggers] A menu can be opened by a trigger that lives either inside or outside the ``. Keep the trigger inside `` for simple, tightly coupled layouts like the hero demo at the top of this page. When the trigger and menu content need to live in different parts of the tree (for example, in a card list that controls a menu rendered near the document root), create a `handle` with `Menu.createHandle()` and pass it to both the trigger and the root. Note that only top-level menus can have detached triggers. Submenus must have their triggers defined within the `SubmenuRoot` part. The imperative methods on the handle, such as `open()` and `close()`, require a `` using the same handle to be mounted. Calls made while no root is attached to the handle — before one mounts, or after it unmounts — are ignored. Each time a root mounts, it starts from fresh state: a call made while no root was attached is not replayed, and no open state carries over from a previous mount. ```jsx title="Detached triggers" const demoMenu = Menu.createHandle(); // @highlight // @highlight-text "handle={demoMenu}" Actions // @highlight // @highlight-text "handle={demoMenu}" Edit Share ``` ### Multiple triggers [#multiple-triggers] One menu can be opened by several triggers. You can either render multiple `` components inside the same ``, or attach several detached triggers to the same `handle`. ```jsx title="Multiple triggers within the Root part" Row actions Quick actions {/* Rest of the menu */} ``` ```jsx title="Multiple detached triggers" const projectMenu = Menu.createHandle(); Row actions Quick actions {/* Rest of the menu */} ``` Menus can render different content depending on which trigger opened them. Pass a `payload` prop to each `` and read it via a function child on ``. Provide a type argument to `createHandle()` to strongly type the payload. ```jsx title="Detached triggers with payload" const menus = { file: ['New', 'Open', 'Save'], edit: ['Undo', 'Redo', 'Cut', 'Copy', 'Paste'], } // @highlight const demoMenu = Menu.createHandle<{ items: string[] }>(); // @highlight // @highlight-text "payload" File // @highlight // @highlight-text "payload" Edit {({ payload }) => ( // @highlight-text "payload" {(payload?.items ?? []).map((item) => ( // @highlight-text "payload" {item} ))} )} ``` ### Controlled mode with multiple triggers [#controlled-mode-with-multiple-triggers] Control a menu's open state externally with the `open` and `onOpenChange` props on ``. When more than one trigger can open the menu, track the active trigger with the `triggerId` prop on `` and matching `id` props on each ``. The `onOpenChange` callback receives `eventDetails`, which includes the DOM element that initiated the change, so you can update your `triggerId` state when the user activates a different trigger. ### Arrow [#arrow] Use the `` part inside the popup to visually connect the menu to its trigger. ### Animating the Menu [#animating-the-menu] When one menu is opened by multiple detached triggers, you can animate the menu as it moves between triggers. This includes animating position, size, and content. #### Position and Size [#position-and-size] To animate the menu's position, apply CSS transitions to the `left`, `right`, `top`, and `bottom` properties of the **Positioner** part. To animate its size, transition the `width` and `height` of the **Popup** part. #### Content [#content] The menu also supports content transitions. This is useful when different triggers display different content within the same menu. To enable content animations, wrap the menu content in the `` part. This part renders a `div` with `data-activation-direction`, containing up to two space-separated tokens — a horizontal (`left` or `right`) and a vertical (`up` or `down`) value — so you can make direction-aware animations. Inside ``, content is wrapped in `div`s with transition data attributes: * `data-current`: The currently visible content when no transitions are present or the incoming content. * `data-previous`: The outgoing content during a transition. ## API reference [#api-reference] ### Root [#root] Groups all parts of the menu. Doesn't render its own HTML element. **Root Props:** | Prop | Type | Default | Description | | :------------------- | :---------------------------------------------------------------------- | :----------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | defaultOpen | `boolean` | `false` | Whether the menu is initially open. To render a controlled menu, use the `open` prop instead. | | open | `boolean` | - | Whether the menu is currently open. | | onOpenChange | `((open: boolean, eventDetails: Menu.Root.ChangeEventDetails) => void)` | - | Event handler called when the menu is opened or closed. | | highlightItemOnHover | `boolean` | `true` | Whether moving the pointer over items should highlight them. Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state. | | actionsRef | `React.RefObject` | - | A ref to imperative actions. `unmount`: Manually unmounts the menu. Call this after any externally controlled closing animation finishes.`close`: When specified, the menu can be closed imperatively. | | closeParentOnEsc | `boolean` | `false` | When in a submenu, determines whether pressing the Escape key closes the entire menu, or only the current child menu. | | defaultTriggerId | `string \| null` | - | ID of the trigger that the menu is associated with. This is useful in conjunction with the `defaultOpen` prop to create an initially open menu. | | handle | `Menu.Handle` | - | A handle to associate the menu with a trigger. If specified, allows external triggers to control the menu's open state. | | loopFocus | `boolean` | `true` | Whether to loop keyboard focus back to the first item when the end of the list is reached while using the arrow keys. | | modal | `boolean` | `true` | Determines if the menu enters a modal state when open. `true`: user interaction is limited to the menu: document page scroll is locked and pointer interactions on outside elements are disabled.`false`: user interaction with the rest of the document is allowed. On touch devices, a `true` modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior. Nested menus ignore this prop, and menus opened by hover are never modal. | | onOpenChangeComplete | `((open: boolean) => void)` | - | Event handler called after any animations complete when the menu is opened or closed. | | triggerId | `string \| null` | - | ID of the trigger that the menu is associated with. This is useful in conjunction with the `open` prop to create a controlled menu. There's no need to specify this prop when the menu is uncontrolled (that is, when the `open` prop is not set). | | disabled | `boolean` | `false` | Whether the component should ignore user interaction. | | orientation | `Menu.Root.Orientation` | `'vertical'` | The visual orientation of the menu. Controls whether roving focus uses up/down or left/right arrow keys. | | children | `React.ReactNode \| PayloadChildRenderFunction` | - | The content of the menu. This can be a regular React node or a render function that receives the `payload` of the active trigger. | ### Root.Props [#rootprops] Re-export of [Root](#root) props. ### Root.State [#rootstate] ```typescript type MenuRootState = {}; ``` ### Root.Actions [#rootactions] ```typescript type MenuRootActions = { unmount: () => void; close: () => void }; ``` ### Root.ChangeEventReason [#rootchangeeventreason] ```typescript type MenuRootChangeEventReason = | 'trigger-hover' | 'trigger-focus' | 'trigger-press' | 'outside-press' | 'focus-out' | 'list-navigation' | 'escape-key' | 'item-press' | 'close-press' | 'sibling-open' | 'cancel-open' | 'imperative-action' | 'none'; ``` ### Root.ChangeEventDetails [#rootchangeeventdetails] ```typescript type MenuRootChangeEventDetails = ( | { reason: 'none'; event: Event } | { reason: 'trigger-hover'; event: MouseEvent } | { reason: 'trigger-focus'; event: FocusEvent } | { reason: 'trigger-press'; event: KeyboardEvent | MouseEvent | TouchEvent | PointerEvent } | { reason: 'outside-press'; event: MouseEvent | TouchEvent | PointerEvent } | { reason: 'focus-out'; event: FocusEvent | KeyboardEvent } | { reason: 'list-navigation'; event: KeyboardEvent } | { reason: 'escape-key'; event: KeyboardEvent } | { reason: 'item-press'; event: KeyboardEvent | MouseEvent | PointerEvent } | { reason: 'close-press'; event: KeyboardEvent | MouseEvent | PointerEvent } | { reason: 'sibling-open'; event: Event } | { reason: 'cancel-open'; event: MouseEvent } | { reason: 'imperative-action'; event: Event } ) & { /** Cancels Base UI from handling the event. */ cancel: () => void; /** Allows the event to propagate in cases where Base UI will stop the propagation. */ allowPropagation: () => void; /** Indicates whether the event has been canceled. */ isCanceled: boolean; /** Indicates whether the event is allowed to propagate. */ isPropagationAllowed: boolean; /** The element that triggered the event, if applicable. */ trigger: Element | undefined; preventUnmountOnClose: preventUnmountOnClose; }; ``` ### Root.Orientation [#rootorientation] ```typescript type MenuRootOrientation = 'horizontal' | 'vertical'; ``` ### Trigger [#trigger] A button that opens the menu. Renders a `