# Menu

Headless, unstyled dropdown menu of actions, with arrow-key navigation, typeahead and nested submenus. Wires `role="menu"`, `role="menuitem"` and the trigger’s `aria-expanded`, `aria-haspopup` and `aria-controls`.

## Use for

- an actions menu opened from a button
- a dropdown of commands, such as edit, duplicate and delete
- a nested submenu inside a menu
- a menu that opens on hover

## Practices

- Do: Pass `label` on every `Menu.Item`. Typeahead matches on it.
- Do: Nest a `Menu.Root` inside a `Menu.Popup` for a submenu. Its trigger becomes a `menuitem` that opens on hover.
- Do: Set `fallbackPlacements` for a menu opened inside another floating surface, so it does not flip onto that surface.
- Do: Animate with `data-starting-style` and `data-ending-style` on `Menu.Popup`. The popup unmounts once its exit transition ends.
- Don't: Pass `id` to `Menu.Positioner`. The primitive owns it to pair the trigger’s `aria-controls`.
- Don't: Use it for arbitrary content or a form. Use `Popover` instead.

## API reference

### Menu.Root

Holds the open state, placement and list navigation. Renders no element. Nested inside another menu, it becomes a submenu.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` |  | Whether the menu is open, when controlled. |
| `defaultOpen` | `boolean` | `false` | Whether the menu is open on mount, when uncontrolled. |
| `onOpenChange` | `(open: boolean) => void` |  | Called with the new open state. |
| `placement` | `Placement` | `'bottom-start', or 'right-start' for a submenu` | Where the menu sits against its trigger. |
| `sideOffset` | `SideOffset` | `4, or 0 for a submenu` | Gap to the trigger in px. `{ x, y }` sets one gap per axis. |
| `fallbackPlacements` | `Placement[]` |  | Placements to try, in order, when `placement` does not fit. |
| `openOnHover` | `boolean` | `false` | Opens when a mouse rests on the trigger. A press still opens it and keeps it open. |

### Menu.Trigger

A `button` that toggles the menu. Carries `data-open` or `data-closed`. Inside a parent menu it renders as `role="menuitem"`.

### Menu.Portal

Portals its children while the menu is mounted.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `root` | `HTMLElement \| null \| React.RefObject<HTMLElement \| null>` | ``the `Portal` container`` | The element to portal into. |

### Menu.Positioner

The floating `div`, placed against the trigger. Carries `data-side` and the `--cl-anchor-*`, `--cl-available-*` and `--cl-transform-origin` variables. Manages focus and handles `Home` and `End`.

### Menu.Popup

Wraps the items. Carries `data-open`, `data-closed`, `data-starting-style` and `data-ending-style`, and is inert while closing.

### Menu.Item

A `button` with `role="menuitem"`. Carries `data-active` while focused and `data-disabled`. Clicking it closes the whole menu tree.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` |  | The text typeahead matches on. |
| `disabled` | `boolean` |  | Sets `aria-disabled` and skips `onClick`. The item stays focusable. |
| `closeOnClick` | `boolean` | `true` | Whether a click closes the whole menu tree. |

### Menu.Separator

A `div` with `role="separator"` between items.

### Menu.Arrow

An optional `FloatingArrow` `svg` pointing at the trigger. Carries `data-side`.

## Examples

### Actions menu

```tsx
<Menu.Root>
  <Menu.Trigger>Actions</Menu.Trigger>
  <Menu.Positioner>
    <Menu.Popup>
      <Menu.Item label='Edit' onClick={onEdit}>
        Edit
      </Menu.Item>
      <Menu.Separator />
      <Menu.Item label='Delete' onClick={onDelete}>
        Delete
      </Menu.Item>
    </Menu.Popup>
  </Menu.Positioner>
</Menu.Root>
```

## Related

- [Popover](/docs/components/popover.md)
- [Select](/docs/components/select.md)
- [Portal](/docs/primitives/portal.md)
