> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Menu
> Present commands, checked options, radio choices, and nested menus.
export const StoryEmbed = ({storyId, title, height = 240}) => <>
Open in Storybook
;
Use `Menu` for actions opened from a trigger. Its items supply keyboard navigation and the visual layout of [ListItem](/ui/primitives/navigation/list-item).
## Anatomy
Keep the trigger and popup inside the same `Menu.Root`. Put action or selection items inside the popup.
```text theme={null}
Menu.Root
├── Menu.Trigger
└── Menu.Popup
├── Menu.Item
├── Menu.Separator
└── Menu.Item
```
| Part | Requirement | Purpose |
| ------------------------------- | --------------------------------- | -------------------------------------------------------------------------- |
| `Root` | Required | Owns open state and coordinates menu interaction. |
| `Trigger` | Required for a trigger-based menu | Opens the menu and provides its accessible name. |
| `Popup` | Required | Renders the positioned, portaled menu with keyboard navigation. |
| `Item` | One per action | Runs a command when selected. |
| `CheckboxItem` | Optional | Toggles an independent boolean option. |
| `RadioGroup`, `RadioItem` | Optional | Coordinate mutually exclusive options. Put radio items inside their group. |
| `Group`, `GroupLabel` | Optional | Group related items under a label. |
| `Separator` | Optional | Separates groups visually. |
| `SubmenuRoot`, `SubmenuTrigger` | Optional | Add a nested menu with its own popup. |
`Popup` includes the portal and positioner. Menu items include the row layout and selection indicators. Supply labels as children and use `startIcon`, `endIcon`, and `description` for supporting content.
## Uncontrolled state
Use `defaultOpen` to set the initial visibility. The menu owns subsequent changes from its trigger, item selection, and dismissal interactions.
```tsx theme={null}
import { IconCopy, IconTrash } from 'twenty-ui/icon';
import { Menu } from 'twenty-ui/primitives/surfaces';
type RecordMenuProps = { onDuplicate: () => void; onDelete: () => void };
export const RecordMenu = ({ onDuplicate, onDelete }: RecordMenuProps) => (
Record actions} onClick={onDuplicate}>
Duplicate
} color="danger" onClick={onDelete}>
Delete
);
```
`defaultOpen` defaults to `false`, so it can be omitted. Action items close the menu when selected by default. `disabled` prevents selection. `hotkeys` displays shortcut hints; register shortcut handlers in your application.
## Controlled state
Pass `open` and update it with `onOpenChange` to own the same menu's visibility in React state. The callback receives the next boolean and event details, including dismissal and item selection.
```tsx theme={null}
import { useState } from 'react';
import { IconCopy, IconTrash } from 'twenty-ui/icon';
import { Menu } from 'twenty-ui/primitives/surfaces';
type RecordMenuProps = { onDuplicate: () => void; onDelete: () => void };
export const RecordMenu = ({ onDuplicate, onDelete }: RecordMenuProps) => {
const [open, setOpen] = useState(false);
return (
Record actions} onClick={onDuplicate}>
Duplicate
} color="danger" onClick={onDelete}>
Delete
);
};
```
## Selection and submenus
Item selection is independent of popup visibility. Checkbox items use `defaultChecked` or `checked` with `onCheckedChange`. Radio groups use `defaultValue` or `value` with `onValueChange`.
For a submenu, place `SubmenuRoot` inside the parent popup, with its own trigger and popup. Each nested popup retains its own positioning and keyboard behavior.
```text theme={null}
Menu.Popup
└── Menu.SubmenuRoot
├── Menu.SubmenuTrigger
└── Menu.Popup
└── Menu.RadioGroup
├── Menu.RadioItem
└── Menu.RadioItem
```
### Uncontrolled item state
Each checkbox item and radio group owns its selection. Both the menu and submenu also manage their own visibility.
```tsx theme={null}
import { Menu } from 'twenty-ui/primitives/surfaces';
export const ViewMenu = () => (
View options
Show archived records
LayoutListBoard
);
```
### Controlled item state
The application owns the same selections in React state. Popup visibility remains uncontrolled because neither root receives `open`.
```tsx theme={null}
import { useState } from 'react';
import { Menu } from 'twenty-ui/primitives/surfaces';
export const ViewMenu = () => {
const [showArchived, setShowArchived] = useState(false);
const [view, setView] = useState('list');
return (
View options
Show archived records
LayoutListBoard
);
};
```
Checkbox and radio items keep the popup open by default so users can adjust options. Use `closeOnClick` to change that behavior. Nest a `SubmenuRoot`, `SubmenuTrigger`, and `Popup` inside a parent popup for submenus. Each `SubmenuRoot` has its own `defaultOpen`, `open`, and `onOpenChange` props, independent of the parent menu.
## Compose a trigger
Use `render` to make a Twenty UI `Button` the trigger. The menu supplies the button's activation handlers and accessibility attributes.
```tsx theme={null}
import { IconCopy, IconTrash } from 'twenty-ui/icon';
import { Button } from 'twenty-ui/primitives/input';
import { Menu } from 'twenty-ui/primitives/surfaces';
type RecordMenuProps = { onDuplicate: () => void; onDelete: () => void };
export const RecordMenu = ({ onDuplicate, onDelete }: RecordMenuProps) => (
}
/>
} onClick={onDuplicate}>
Duplicate
} color="danger" onClick={onDelete}>
Delete
);
```
Put `Button` in the trigger's `render` prop to preserve a single interactive control. For custom wrapper components, [forward the supplied props and ref](/ui/primitives/overview#custom-components).
## Keyboard and placement
Arrow keys move through the items, including disabled ones, which receive focus but cannot be selected; typeahead finds items by their text. Enter or Space selects an item. Escape closes the menu and returns focus to its trigger. Use clear text labels even when items have icons.
`Popup` owns its portal and accepts placement props and a `container` override. Placement defaults depend on whether it is a top-level menu or a submenu:
| Popup | `side` | `align` | `sideOffset` | `alignOffset` |
| -------------- | ------------ | ------- | ------------ | ------------- |
| Top-level menu | `bottom` | `start` | `8` | `0` |
| Submenu | `inline-end` | `start` | `0` | `-4` |
It uses the [theme's portal container](/ui/theming) by default.
## Props
The reference is generated from the public component types. Native attributes, including accessible names and event handlers, are also accepted on parts that render elements.
### Menu.Root
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.
The content of the menu.
This can be a regular React node or a render function that receives the `payload` of the active trigger.
When in a submenu, determines whether pressing the Escape key
closes the entire menu, or only the current child menu.
Whether the menu is initially open.
To render a controlled menu, use the `open` prop instead.
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.
Whether the component should ignore user interaction.
A handle to associate the menu with a trigger.
If specified, allows external triggers to control the menu's open state.
Whether moving the pointer over items should highlight them.
Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state.
Whether to loop keyboard focus back to the first item
when the end of the list is reached while using the arrow keys.
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.
Event handler called when the menu is opened or closed.
Event handler called after any animations complete when the menu is opened or closed.
Whether the menu is currently open.
The visual orientation of the menu.
Controls whether roving focus uses up/down or left/right arrow keys.
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).
### Menu.Trigger
CSS class applied to the element, or a function that
returns a class based on the component's state.
How long to wait before closing the menu that was opened on hover.
Specified in milliseconds.
Requires the `openOnHover` prop.
How long to wait before the menu may be opened on hover. Specified in milliseconds.
Requires the `openOnHover` prop.
Whether the component should ignore user interaction.
A handle to associate the trigger with a menu.
Whether the component renders a native `