# Menu

A dropdown of actions opened from a trigger. Handles focus, arrow keys and typeahead, and closes when an item is clicked.

## Use for

- a list of actions behind an ellipsis button
- a row or card overflow menu
- a destructive action among others, with `color="negative"`

## Practices

- Do: Give every `Menu.Item` a `label` for typeahead. It is not rendered or announced, so the item also needs visible text in `Menu.Label`.
- Do: Put the item text in `Menu.Label`, not straight in `Menu.Item`, so it lines up and truncates.
- Do: Use the same `Menu.Media` size for every item in one menu, so the text starts on one line.
- Do: Pass an `aria-label` to a `Menu.Trigger` with no children. The default ellipsis has no name.
- Don't: Use it to pick a value. Use `Select` instead.

## API reference

### Menu.Root

Holds the open state and placement. Renders no element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` |  | Whether the menu is open, when controlled. |
| `defaultOpen` | `boolean` | `false` | Whether the menu starts open, when uncontrolled. |
| `onOpenChange` | `(open: boolean) => void` |  | Called with the new open state. |
| `placement` | `Placement` | `'bottom-start', or 'right-start' for a submenu` | Side and alignment against the trigger. |
| `sideOffset` | `SideOffset` | `4, or 0 for a submenu` | Gap from the trigger in px, or `{ x, y }` per axis. |
| `fallbackPlacements` | `Placement[]` | `the opposite side` | Where the menu goes, in order, when `placement` does not fit. |
| `openOnHover` | `boolean` | `false` | Also opens while the mouse rests on the trigger. |

### Menu.Trigger

Opens the menu. Renders a small neutral ghost `Button` with an ellipsis, or `children` as its label, or the `render` element.

Slot: `cl-menu-trigger`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `focusableWhenDisabled` | `boolean` | `false` | Keeps the default trigger in the tab order while disabled. A `render` trigger handles this itself. |

### Menu.Popup

The floating, scrollable surface. Portals and positions itself.

Slot: `cl-menu-popup`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `portalRoot` | `MenuPortalProps['root']` | `` `document.body` `` | The container the menu portals into. |

### Menu.Item

One action, as a `button`. What it shows is the `Menu.Media`, `Menu.Label` and `Menu.Indicator` inside it.

Slot: `cl-menu-item`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` |  | The text typeahead matches on. Not rendered and not the accessible name. |
| `color` | `'neutral' \| 'negative'` | `'neutral'` | `neutral` or `negative`. |
| `disabled` | `boolean` |  | Disables the item and ignores its `onClick`. |
| `closeOnClick` | `boolean` | `true` | Closes the menu after a click. |

### Menu.Media

A square leading column that centers an icon, image or avatar.

Slot: `cl-menu-item-media`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `MenuMediaSize` | `'sm'` | `sm` fits an icon or avatar, `xs` a bare glyph. Sets the row height. |

### Menu.Label

The item text. Fills the space between media and indicator and cuts to one line.

Slot: `cl-menu-item-label`

### Menu.Indicator

A small square trailing slot, such as for a spinner while the action runs.

Slot: `cl-menu-item-indicator`

### Menu.Separator

A full-width divider between groups of items.

Slot: `cl-menu-separator`

## Examples

### An overflow menu

```tsx
<Menu.Root>
  <Menu.Trigger aria-label='More actions' />
  <Menu.Popup>
    <Menu.Item label='Rename' onClick={onRename}>
      <Menu.Label>Rename</Menu.Label>
    </Menu.Item>
    <Menu.Separator />
    <Menu.Item label='Delete' color='negative' onClick={onDelete}>
      <Menu.Label>Delete</Menu.Label>
    </Menu.Item>
  </Menu.Popup>
</Menu.Root>
```

## Related

- [ActionMenu](/docs/components/action-menu.md)
- [Select](/docs/components/select.md)
- [Popover](/docs/components/popover.md)
