# Dropdown Menu

A dropdown menu opens a list of actions from a button.

A dropdown menu opens a list of actions when someone presses its trigger, and runs one when they choose it. To choose a value for a form field, use a [Select](/docs/select). To offer the same actions on right-click, use a [Context Menu](/docs/context-menu).


## Usage

```tsx
import { Button, DropdownMenu } from '@kushagradhawan/kookie-ui';
import { HugeiconsIcon } from '@hugeicons/react';
import { MoreHorizontalIcon } from '@hugeicons/core-free-icons';

export function ProjectActions({ onRename, onDuplicate, onDelete }: { onRename: () => void; onDuplicate: () => void; onDelete: () => void }) {
  return (
    <DropdownMenu.Root>
      <DropdownMenu.Trigger>
        <Button iconOnly emphasis="quiet" aria-label="Project actions">
          <HugeiconsIcon icon={MoreHorizontalIcon} strokeWidth={1.75} />
        </Button>
      </DropdownMenu.Trigger>
      <DropdownMenu.Content>
        <DropdownMenu.Item shortcut="⌘ R" onSelect={onRename}>Rename</DropdownMenu.Item>
        <DropdownMenu.Item shortcut="⌘ D" onSelect={onDuplicate}>Duplicate</DropdownMenu.Item>
        <DropdownMenu.Separator />
        <DropdownMenu.Item color="red" onSelect={onDelete}>Delete</DropdownMenu.Item>
      </DropdownMenu.Content>
    </DropdownMenu.Root>
  );
}
```

## Anatomy

```tsx
<DropdownMenu.Root>
  <DropdownMenu.Trigger />
  <DropdownMenu.Content>
    <DropdownMenu.Label />
    <DropdownMenu.Item />
    <DropdownMenu.Group />
    <DropdownMenu.CheckboxItem />
    <DropdownMenu.RadioGroup>
      <DropdownMenu.RadioItem />
    </DropdownMenu.RadioGroup>
    <DropdownMenu.Sub>
      <DropdownMenu.SubTrigger />
      <DropdownMenu.SubContent />
    </DropdownMenu.Sub>
    <DropdownMenu.Separator />
  </DropdownMenu.Content>
</DropdownMenu.Root>
```

- **Root:** Holds the open state.
- **Trigger:** Wraps one element, usually a [Button](/docs/button), that opens the menu.
- **TriggerIcon:** A chevron to put inside a trigger button with a text label.
- **Content:** The menu, rendered in a portal and placed below the trigger.
- **Item:** One action.
- **CheckboxItem:** An option that turns on or off.
- **RadioGroup and RadioItem:** A set of options where one is on.
- **Label:** A heading for the items after it. It can't be chosen.
- **Group and Separator:** A set of related items, and a line between sets.
- **Sub, SubTrigger and SubContent:** A nested menu and the item that opens it.

## Best practices

**Start each item with a verb.** "Rename", "Duplicate" and "Move to folder" say what happens. Keep the labels short, because the menu is only as wide as its longest item.

**Put destructive actions last.** Separate them from the other items and set `color="red"`. Confirm an action that can't be undone in an [Alert Dialog](/docs/alert-dialog).

**Keep menus shallow.** One level of submenu is easy to follow. A second level hides items behind more hover and more aim, so move them into a dialog or a page instead.

**Make the actions reachable somewhere else.** A menu behind an icon-only button is easy to miss. Show the main action as its own button, and keep the menu for the less frequent ones.

**Don't disable items without a reason people can see.** A disabled item stays visible but doesn't say why. If the action is never available in this context, leave it out.

## Size

`size` on `Content` picks one of four item heights and the padding around them. Size 2 is the default. Match the size of the trigger, so a size 1 button in a dense toolbar opens a size 1 menu. A submenu takes the size of its parent unless you set its own. `size` accepts a responsive object.

## Submenu behaviour

`submenuBehavior` on `Content` sets how a submenu opens.

| Value | Behaviour | Use it for |
| --- | --- | --- |
| `cascade` | Opens beside the parent menu. This is the default | Pointer use on wide screens |
| `drill-down` | Replaces the menu content, with a back row at the top | Touch screens and narrow layouts |

A responsive object such as `{ initial: 'drill-down', md: 'cascade' }` gives phones the drill-down and wider screens the cascade. In drill-down, `label` on `Sub` sets the text of the back row, and Escape goes back one level before it closes the menu.

## Examples

### Button with a label

A trigger button with a text label shows a chevron, so people can tell it opens a menu. Put `TriggerIcon` after the label. The button sizes the icon.

```tsx
<DropdownMenu.Trigger>
  <Button>
    Export
    <DropdownMenu.TriggerIcon />
  </Button>
</DropdownMenu.Trigger>
```

### View options

Use `CheckboxItem` for options that turn on or off, and a `RadioGroup` for options where one is on. These items stay as menu items, so the menu closes after each choice unless you call `event.preventDefault()` in `onSelect`.

```tsx
<DropdownMenu.Content>
  <DropdownMenu.Label>Show</DropdownMenu.Label>
  <DropdownMenu.CheckboxItem checked={showDone} onCheckedChange={setShowDone}>
    Completed tasks
  </DropdownMenu.CheckboxItem>
  <DropdownMenu.Separator />
  <DropdownMenu.Label>Sort by</DropdownMenu.Label>
  <DropdownMenu.RadioGroup value={sort} onValueChange={setSort}>
    <DropdownMenu.RadioItem value="due">Due date</DropdownMenu.RadioItem>
    <DropdownMenu.RadioItem value="priority">Priority</DropdownMenu.RadioItem>
  </DropdownMenu.RadioGroup>
</DropdownMenu.Content>
```

### Nested actions

Group a set of related targets, such as folders, under a `Sub`.

```tsx
<DropdownMenu.Sub label="Move to">
  <DropdownMenu.SubTrigger>Move to</DropdownMenu.SubTrigger>
  <DropdownMenu.SubContent>
    <DropdownMenu.Item>Drafts</DropdownMenu.Item>
    <DropdownMenu.Item>Archive</DropdownMenu.Item>
  </DropdownMenu.SubContent>
</DropdownMenu.Sub>
```

### Links in a menu

When an item goes to another page, render your router's link with `asChild`. The item stays an anchor, so it opens in a new tab and shows its address like any link.

```tsx
<DropdownMenu.Item asChild>
  <Link href="/settings">Settings</Link>
</DropdownMenu.Item>
```

### Shortcut hints

`shortcut` shows a key hint at the end of the item and sets `aria-keyshortcuts`. It doesn't bind the key, so register the shortcut in your app as well.

## Props

### Root

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | | Whether the menu is open, when you control it |
| `defaultOpen` | `boolean` | `false` | Whether the menu is open at first render |
| `onOpenChange` | `(open: boolean) => void` | | Called when the menu opens or closes |
| `modal` | `boolean` | `true` | Blocks the rest of the page while the menu is open |
| `dir` | `'ltr' \| 'rtl'` | | The reading direction |

### Trigger

Trigger takes one child element and accepts `disabled`. The child receives the trigger's attributes and events.

### Content

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `'1' \| '2' \| '3' \| '4'`, responsive | `'2'` | The item height step |
| `color` | `AccentColor` | Theme accent | The colour of the highlight |
| `submenuBehavior` | `'cascade' \| 'drill-down'`, responsive | `'cascade'` | How submenus open |
| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'bottom'` | Where the menu opens |
| `align` | `'start' \| 'center' \| 'end'` | `'start'` | How the menu lines up with the trigger |
| `sideOffset` | `number` | `4` | The gap to the trigger in pixels |
| `collisionPadding` | `number` | `10` | The space kept from the edge of the screen |
| `loop` | `boolean` | `false` | Wraps the arrow keys from the last item to the first |
| `virtualized` | `boolean` | `false` | Leaves out the scroll area, for a [Virtual Menu](/docs/virtual-menu) that scrolls itself |
| `container` | `HTMLElement` | `document.body` | The element the portal renders into |

### Item

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onSelect` | `(event: Event) => void` | | Called when the item is chosen. Call `event.preventDefault()` to keep the menu open |
| `color` | `AccentColor` | | The colour of the item |
| `shortcut` | `string` | | A key hint at the end of the item |
| `disabled` | `boolean` | `false` | Stops the item from being chosen |
| `textValue` | `string` | | The text for typeahead, when the children aren't plain text |
| `asChild` | `boolean` | `false` | Renders the child element, such as a link, with the item's look |

### CheckboxItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` | `boolean \| 'indeterminate'` | | Whether the option is on |
| `onCheckedChange` | `(checked: boolean) => void` | | Called when the option turns on or off |
| `color`, `shortcut`, `disabled`, `textValue`, `onSelect` | | | As on Item |

### RadioGroup and RadioItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | | On RadioGroup, the option that is on. On RadioItem, the value it sets. Required on RadioItem |
| `onValueChange` | `(value: string) => void` | | On RadioGroup, called when another option turns on |
| `color`, `disabled`, `textValue`, `onSelect` | | | On RadioItem, as on Item |

### Sub, SubTrigger and SubContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `ReactNode` | `'Back'` | On Sub, the text of the back row in drill-down |
| `open`, `defaultOpen`, `onOpenChange` | | | On Sub, the open state of the submenu. In drill-down, a controlled `open` decides which panel shows, and the trigger, the back row, Arrow Left and Escape only call `onOpenChange` |
| `disabled`, `textValue` | | | On SubTrigger, as on Item |
| `size`, `color` | | Parent menu's | On SubContent, as on Content |
| `virtualized`, `container`, `loop` | | | On SubContent, as on Content. Cascade only |

Content, the items, Label, Group, Separator and SubContent also accept the attributes of the HTML `div` element. TriggerIcon accepts the attributes of the `svg` element.

## Accessibility

| Key | Action |
| --- | --- |
| Enter, Space or Arrow Down | Opens the menu from the trigger and focuses the first item |
| Arrow Down or Arrow Up | Moves focus through the items |
| Home or End | Moves focus to the first or last item |
| Enter or Space | Chooses the focused item, or opens its submenu |
| Arrow Right | Opens the submenu of the focused item |
| Arrow Left | Closes the submenu, or goes back one level in drill-down |
| A letter key | Moves focus to the next item that starts with it |
| Escape | Closes the menu and returns focus to the trigger |

- **Name:** The trigger announces its own label. An icon-only trigger needs `aria-label`, as on any icon-only button.
- **Announcements:** The trigger sets `aria-haspopup` and `aria-expanded`. Items have the `menuitem` role, and checkbox and radio items announce whether they're on. A shortcut hint is hidden from screen readers, which read `aria-keyshortcuts` instead.
- **Groups:** A Group or RadioGroup that holds a Label is named by that Label, so a screen reader announces the section as focus enters it.
- **Drill-down:** Each panel is a group named after its submenu. A trigger that opens a panel announces no popup, because the panel replaces the level in the same menu. The back row of a submenu labelled "Move to" is named "Back from Move to".
- **Focus:** Focus stays inside the open menu and returns to the trigger when it closes. A drill-down menu always reopens at its first level.
