> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/en/components/dropdown.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/en/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/en/llms-full.txt.

# Dropdown

Group additional actions in a menu.


## Basic usage

[](#)
Provide menu actions through `items` and use a button as the trigger.


More actions

basic.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/dropdown/basic.tsx"
import { Button, Dropdown, Flex, Text } from '@ifhover/leaf-ui';
import { Archive, ChevronDown, Copy, Pencil } from 'lucide-react';
import { useState } from 'react';

export function DropdownBasic() {
  const [action, setAction] = useState('');
  return (
    <Flex direction="column" gap="md" align="start">
      <Dropdown
        items={[
          { key: 'edit', label: 'Edit', icon: <Pencil size={14} /> },
          { key: 'copy', label: 'Copy', icon: <Copy size={14} /> },
          { key: 'archive', label: 'Archive', icon: <Archive size={14} /> },
        ]}
        onSelect={setAction}
      >
        <Button variant="outline" endIcon={<ChevronDown size={16} />}>
          More actions
        </Button>
      </Dropdown>
      {action && <Text role="status">Selected: {action}</Text>}
    </Flex>
  );
}
```

Expand code


## Examples

### Trailing content

Use an item's `extra` for shortcuts, labels or other supplementary information. It shares the row's click target; do not nest buttons or links inside it.


More actions

extra.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/dropdown/extra.tsx"
import type { DropdownItem } from '@ifhover/leaf-ui';
import { Button, Dropdown, Flex, Tag, Text } from '@ifhover/leaf-ui';
import { ChevronDown, Copy, Download, Pencil } from 'lucide-react';
import { useState } from 'react';

const items: DropdownItem[] = [
  { key: 'edit', label: 'Edit', icon: <Pencil />, extra: <Text tone="muted">Ctrl E</Text> },
  { key: 'copy', label: 'Copy link', icon: <Copy />, extra: <Tag size="sm">New</Tag> },
  {
    key: 'export',
    label: 'Export',
    icon: <Download />,
    extra: <Text tone="muted">CSV</Text>,
    children: [
      { key: 'all', label: 'All data' },
      { key: 'selected', label: 'Current selection' },
    ],
  },
];

export function DropdownExtra() {
  const [action, setAction] = useState('');
  return (
    <Flex direction="column" gap="md" align="start">
      <Dropdown items={items} onSelect={setAction}>
        <Button variant="outline" endIcon={<ChevronDown size={16} />}>
          More actions
        </Button>
      </Dropdown>
      {action && <Text role="status">Selected: {action}</Text>}
    </Flex>
  );
}
```

Expand code

### Menu sizes

Set the menu size with Dropdown's `size`; submenus inherit it. The trigger Button has its own `size`.


SmallMore actions

DefaultMore actions

LargeMore actions

sizes.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/dropdown/sizes.tsx"
import { Button, Dropdown, Flex, Grid, Text } from '@ifhover/leaf-ui';
import { ChevronDown, Copy, Pencil } from 'lucide-react';

const sizes = [
  { size: 'sm', label: 'Small' },
  { size: 'md', label: 'Default' },
  { size: 'lg', label: 'Large' },
] as const;

export function DropdownSizes() {
  return (
    <Flex direction="column" gap="md">
      {sizes.map(({ size, label }) => (
        <Grid
          key={size}
          role="group"
          aria-label={label}
          columns={{ xs: 1, sm: 2 }}
          gap="8px"
          align="center"
        >
          <Text tone="muted">{label}</Text>
          <Dropdown
            size={size}
            items={[
              { key: 'edit', label: 'Edit', icon: <Pencil /> },
              { key: 'copy', label: 'Copy link', icon: <Copy />, extra: 'Ctrl C' },
            ]}
          >
            <Button variant="outline" endIcon={<ChevronDown size={16} />}>
              More actions
            </Button>
          </Dropdown>
        </Grid>
      ))}
    </Flex>
  );
}
```

Expand code

### Submenus and groups

Use `children` for submenus, and `type: 'group'` with `label` for a group heading. `onSelect` runs when an item is selected, not when a submenu opens.


Project actions

hierarchy.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/dropdown/hierarchy.tsx"
import { Button, Dropdown, Flex, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function DropdownHierarchy() {
  const [action, setAction] = useState('');
  return (
    <Flex direction="column" gap="md" align="start">
      <Dropdown
        onSelect={setAction}
        items={[
          {
            key: 'project',
            type: 'group',
            label: 'Project',
            children: [
              { key: 'open', label: 'Open' },
              {
                key: 'export',
                label: 'Export',
                children: [
                  { key: 'csv', label: 'CSV' },
                  { key: 'json', label: 'JSON' },
                ],
              },
            ],
          },
          { key: 'divider', type: 'divider' },
          { key: 'archive', label: 'Archive', disabled: true },
          { key: 'delete', label: 'Delete', danger: true },
        ]}
      >
        <Button variant="outline">Project actions</Button>
      </Dropdown>
      {action && <Text role="status">Selected: {action}</Text>}
    </Flex>
  );
}
```

Expand code

### Radio menu

Set `type: 'radio'` and use the same `group` identifier for mutually exclusive choices. This example manages the view through `checked` and `onCheckedChange`.


Change viewCurrent view: List

radio.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/dropdown/radio.tsx"
import { Button, Dropdown, Flex, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function DropdownRadio() {
  const [view, setView] = useState('list');
  return (
    <Flex direction="column" gap="md" align="start">
      <Dropdown
        items={[
          {
            key: 'list',
            label: 'List',
            type: 'radio',
            group: 'view',
            checked: view === 'list',
            onCheckedChange: () => setView('list'),
          },
          {
            key: 'grid',
            label: 'Grid',
            type: 'radio',
            group: 'view',
            checked: view === 'grid',
            onCheckedChange: () => setView('grid'),
          },
        ]}
      >
        <Button variant="outline">Change view</Button>
      </Dropdown>
      <Text role="status" tone="muted">
        Current view: {view === 'list' ? 'List' : 'Grid'}
      </Text>
    </Flex>
  );
}
```

Expand code

### Checkbox menu

Radio and checkbox items keep the menu open after selection by default. Override this with `closeOnSelect`.


Display optionsDetails are visible

checkbox.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/dropdown/checkbox.tsx"
import { Button, Dropdown, Flex, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function DropdownCheckbox() {
  const [details, setDetails] = useState(true);
  return (
    <Flex direction="column" gap="md" align="start">
      <Dropdown
        items={[
          {
            key: 'details',
            label: 'Show details',
            type: 'checkbox',
            checked: details,
            onCheckedChange: setDetails,
          },
        ]}
      >
        <Button variant="outline">Display options</Button>
      </Dropdown>
      <Text role="status" tone="muted">
        {details ? 'Details are visible' : 'Details are hidden'}
      </Text>
    </Flex>
  );
}
```

Expand code

### Hover trigger

[](#)
With `trigger="hover"`, pointer hover opens the menu. The focused button still supports opening with arrow keys.


Hover to open

hover.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/dropdown/hover.tsx"
import { Button, Dropdown, Flex, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function DropdownHover() {
  const [action, setAction] = useState('');
  return (
    <Flex direction="column" gap="md" align="start">
      <Dropdown
        trigger="hover"
        items={[
          { key: 'edit', label: 'Edit' },
          { key: 'copy', label: 'Copy' },
        ]}
        onSelect={setAction}
      >
        <Button variant="outline">Hover to open</Button>
      </Dropdown>
      {action && <Text role="status">Selected: {action}</Text>}
    </Flex>
  );
}
```

Expand code

### Context menu

With `trigger="contextMenu"`, the menu opens at the right-click position. Keyboard users can focus the button and press Down or Up to open it.


Right-click here

context-menu.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/dropdown/context-menu.tsx"
import { Button, Dropdown, Flex, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function DropdownContextMenu() {
  const [action, setAction] = useState('');
  return (
    <Flex direction="column" gap="md" align="start">
      <Dropdown
        trigger="contextMenu"
        items={[
          { key: 'edit', label: 'Edit' },
          { key: 'copy', label: 'Copy' },
        ]}
        onSelect={setAction}
      >
        <Button variant="outline">Right-click here</Button>
      </Dropdown>
      {action && <Text role="status">Selected: {action}</Text>}
    </Flex>
  );
}
```

Expand code


## API

### Dropdown API

Use a single button that forwards its ref and events as the trigger. Escape closes the menu and returns focus to it. See [PopupOptions](https://ifhover.github.io/leaf-ui/en/api/popup-options.md) for shared popup options.

| Property            | Type                                                                                                                                                                 | Default          | Description                                                                                                      |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------- |
| `items`             | `readonly `[`DropdownItem`](#dropdownitem)`[]`                                                                                                                       | Required         | Menu entries                                                                                                     |
| `children`          | `ReactElement< ButtonHTMLAttributes<HTMLButtonElement> & { ref?: Ref<HTMLButtonElement> } >`                                                                         | Required         | A single Leaf Button or native button                                                                            |
| `trigger`           | `'click' \| 'hover' \| 'contextMenu' \| readonly ('click' \| 'hover' \| 'contextMenu')[]`                                                                            | `'click'`        | Trigger mode; Dropdown supports click, hover and context menu.                                                   |
| `disabled`          | `boolean`                                                                                                                                                            | `false`          | Disable interaction.                                                                                             |
| `size`              | `'sm' \| 'md' \| 'lg'`                                                                                                                                               | `'md'`           | Presentation size.                                                                                               |
| `open`              | `boolean`                                                                                                                                                            | —                | Controlled open state.                                                                                           |
| `defaultOpen`       | `boolean`                                                                                                                                                            | `false`          | Initial open state for uncontrolled usage.                                                                       |
| `onOpenChange`      | `(open: boolean) => void`                                                                                                                                            | —                | Open-state changes                                                                                               |
| `onSelect`          | `(key: string) => void`                                                                                                                                              | —                | Called with the activated leaf item key, including radio and checkbox items; opening a submenu does not call it. |
| `placement`         | `'top-start' \| 'top-end' \| 'bottom-start' \| 'bottom-end'`                                                                                                         | `'bottom-start'` | Menu placement; popupPlacement takes precedence.                                                                 |
| `popupWidth`        | `number \| string`                                                                                                                                                   | `—`              | Popup width; grows with content from a 160px minimum when unset.                                                 |
| `popupMaxWidth`     | `number \| string`                                                                                                                                                   | `420`            | Maximum popup width, still bounded by the viewport.                                                              |
| `itemRender`        | `(item: `[`DropdownItem`](#dropdownitem)`) => ReactNode`                                                                                                             | —                | Customize the item label content, not the whole row.                                                             |
| `mouseEnterDelay`   | `number`                                                                                                                                                             | `100`            | Delay in milliseconds before opening on hover.                                                                   |
| `mouseLeaveDelay`   | `number`                                                                                                                                                             | `150`            | Delay in milliseconds before closing after pointer leave.                                                        |
| `popupPlacement`    | `'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'` | —                | Placement relative to the trigger.                                                                               |
| `popupClassName`    | `string`                                                                                                                                                             | —                | Custom class for the popup.                                                                                      |
| `popupStyle`        | `CSSProperties`                                                                                                                                                      | —                | Custom popup styles.                                                                                             |
| `popupRender`       | `(content: React.ReactNode) => React.ReactNode`                                                                                                                      | —                | Wrap or extend popup content; retain the supplied content to preserve interaction.                               |
| `getPopupContainer` | `() => Element \| DocumentFragment`                                                                                                                                  | —                | Return a popup container, including a ShadowRoot.                                                                |

### DropdownItem

Data for an action, group or submenu in a dropdown menu.

| Property          | Type                                                      | Default  | Description                                                                                            |
| ----------------- | --------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `key`             | `string`                                                  | Required | Unique key                                                                                             |
| `label`           | `ReactNode`                                               | —        | Item label or group heading.                                                                           |
| `icon`            | `ReactNode`                                               | —        | Icon before the item label.                                                                            |
| `extra`           | `ReactNode`                                               | —        | Trailing item content for shortcuts, status labels or other non-interactive information.               |
| `type`            | `'item' \| 'divider' \| 'group' \| 'checkbox' \| 'radio'` | `'item'` | Regular item, divider, group, checkbox or radio item.                                                  |
| `children`        | `readonly `[`DropdownItem`](#dropdownitem)`[]`            | —        | Menu entries.                                                                                          |
| `disabled`        | `boolean`                                                 | `false`  | Disable interaction.                                                                                   |
| `danger`          | `boolean`                                                 | `false`  | Destructive-action colors without disabling the item.                                                  |
| `checked`         | `boolean`                                                 | —        | Controlled checked state; stored internally when omitted.                                              |
| `group`           | `string`                                                  | —        | Mutual-exclusion group identifier for radio items.                                                     |
| `closeOnSelect`   | `boolean`                                                 | —        | Whether selection closes the menu; regular items close by default, radio and checkbox items stay open. |
| `onCheckedChange` | `(checked: boolean) => void`                              | —        | Called with the next checked state when the item is activated.                                         |
| `href`            | `string`                                                  | —        | Link destination.                                                                                      |
| `target`          | `string`                                                  | —        | Link target attribute, such as \_blank; opens in the current tab when omitted.                         |
| `onClick`         | `(event: MouseEvent<HTMLElement>) => void`                | —        | Runs when the item is selected                                                                         |
