# UI: Menu

> Menu, its items, separators, popover and trigger, and useDeliberatePress for destructive items.

Source: https://pithyx.org/docs/reference/sdk/ui/menu/
Markdown: https://pithyx.org/docs/reference/sdk/ui/menu.md

Menu, its items, separators, popover and trigger, and useDeliberatePress for destructive items. Import the token file once (`@pithyx/ui/tokens.css`) and wrap the app in `UiProvider`; see [@pithyx/ui](https://pithyx.org/docs/sdk/ui/).

Generated from the TSDoc comments of @pithyx/ui 1.0.0-rc.9 at build time; the text below the headings is the comment in the source.

## Interfaces

### MenuItemProps

The props of [MenuItem](#menuitem).

#### Extends

- `Omit`\<`AriaMenuItemProps`, `"className"` \| `"children"`\>

#### Properties

##### icon?

```ts
optional icon?: ReactNode;
```

An icon before the label.

##### children

```ts
children: ReactNode;
```

The label; a string is also the text for type-ahead.

##### tone?

```ts
optional tone?: "danger" | "default";
```

`danger` for a destructive entry; `default` when left out.

##### shortcut?

```ts
optional shortcut?: string;
```

Keyboard shortcut shown at the end of the item.

## Variables

### MenuTrigger

```ts
const MenuTrigger: (props) => Element | null = AriaMenuTrigger;
```

Opens a menu from its trigger: the first child is the trigger (a `Button` or `IconButton`), the second a
[MenuPopover](#menupopover) with the [Menu](#menu). It is React Aria's `MenuTrigger`; its props (`isOpen`, `onOpenChange`,
`trigger`) are documented there.

#### Parameters

| Parameter | Type               | Description                                           |
| --------- | ------------------ | ----------------------------------------------------- |
| `props`   | `MenuTriggerProps` | React Aria's menu trigger props and the two children. |

#### Returns

`Element` \| `null`

The trigger with its menu.

## Functions

### MenuPopover()

```ts
function MenuPopover(props): Element;
```

The popover a [Menu](#menu) opens in, next to its trigger inside a `MenuTrigger`.

#### Parameters

| Parameter | Type                                               | Description                                         |
| --------- | -------------------------------------------------- | --------------------------------------------------- |
| `props`   | `Omit`\<`PopoverProps`, `"className"`\> & `object` | React Aria's popover props (`placement`, `offset`). |

#### Returns

`Element`

The popover.

---

### Menu()

```ts
function Menu<T>(props): Element;
```

A menu of [MenuItem](#menuitem)s and [MenuSeparator](#menuseparator)s, with keyboard and touch handling.

#### Type Parameters

| Type Parameter         |
| ---------------------- |
| `T` _extends_ `object` |

#### Parameters

| Parameter | Type                                                   | Description                                                     |
| --------- | ------------------------------------------------------ | --------------------------------------------------------------- |
| `props`   | `Omit`\<`MenuProps`\<`T`\>, `"className"`\> & `object` | React Aria's menu props (`onAction`, `selectionMode`, `items`). |

#### Returns

`Element`

The menu.

#### Example

```tsx
<MenuTrigger>
  <IconButton label="More">
    <IconDots size={18} />
  </IconButton>
  <MenuPopover>
    <Menu onAction={(id) => run(String(id))}>
      <MenuItem id="rename" shortcut="F2">
        Rename
      </MenuItem>
      <MenuSeparator />
      <MenuItem id="delete" tone="danger">
        Delete
      </MenuItem>
    </Menu>
  </MenuPopover>
</MenuTrigger>
```

---

### MenuItem()

```ts
function MenuItem(props): Element;
```

One entry of a menu, with an optional icon and key hint. It shows a check mark in a menu with a `selectionMode` and
a chevron when it opens a submenu.

#### Parameters

| Parameter | Type                              | Description                                                                                              |
| --------- | --------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `props`   | [`MenuItemProps`](#menuitemprops) | React Aria's menu item props (`id`, `onAction`, `isDisabled`, `textValue`) plus icon, tone and shortcut. |

#### Returns

`Element`

The menu item.

---

### MenuSeparator()

```ts
function MenuSeparator(): Element;
```

A line between groups of menu entries.

#### Returns

`Element`

The separator.

---

### useDeliberatePress()

```ts
function useDeliberatePress(): object;
```

React Aria runs a menu item's action when a mouse press that began elsewhere, on the menu's trigger, is released
over the item (press, drag, release). A menu that opens under the pointer can then act on a plain click of its
trigger. Destructive items take their action only from a press that started on them: spread `pressProps` on the
item and ask `confirm()` in the menu's action handler.

#### Returns

The props for the item and the check for the action handler.

##### pressProps

```ts
pressProps: object;
```

Spread on the destructive item.

###### pressProps.onPressStart

```ts
onPressStart: () => void;
```

Arms the item when a press starts on it.

###### Returns

`void`

##### confirm

```ts
confirm: () => boolean;
```

Whether the action comes from a press that started on the item; disarms it.

###### Returns

`boolean`

#### Example

```tsx
const deliberate = useDeliberatePress();
<Menu onAction={(id) => id === 'delete' && deliberate.confirm() && remove()}>
  <MenuItem id="delete" tone="danger" {...deliberate.pressProps}>
    Delete
  </MenuItem>
</Menu>;
```