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

# Dropdown

Navigation`@rockshin/tao-ui`

[Examples](#examples)[API](#api)

Opens a menu of actions or navigation choices from a trigger.

## When to use

Use Dropdown for compact action sets that do not need to stay visible.

**Recommended**

- Order frequent actions first.
- Use destructive styling only for destructive items.

**Avoid**

- Do not use Dropdown as a replacement for visible primary navigation.

## Examples


### Basic usage
```tsx preview
import { Button, Dropdown } from '@rockshin/tao-ui';

function DropdownExample() {
  return (
    <Dropdown
      menu={{
        items: [
          { key: 'edit', label: 'Edit' },
          { key: 'duplicate', label: 'Duplicate' },
          { type: 'divider' },
          { key: 'archive', label: 'Archive' },
        ],
      }}
    >
      <Button variant="secondary">Actions</Button>
    </Dropdown>
  );
}

export default DropdownExample;
```

### Groups and submenus
```tsx preview
import { Button, Dropdown } from '@rockshin/tao-ui';

function DropdownGroups() {
  return (
    <Dropdown
      menu={{
        items: [
          {
            type: 'group',
            label: 'Create',
            children: [
              { key: 'file', label: 'New file', extra: '⌘N' },
              { key: 'folder', label: 'New folder' },
            ],
          },
          { type: 'divider' },
          {
            key: 'share',
            label: 'Share',
            children: [
              { key: 'link', label: 'Copy link' },
              { key: 'invite', label: 'Invite people' },
            ],
          },
          { key: 'delete', label: 'Delete', danger: true },
        ],
      }}
    >
      <Button variant="secondary">Project actions</Button>
    </Dropdown>
  );
}

export default DropdownGroups;
```

### Trigger, arrow, and split button
```tsx preview
import { useState } from 'react';
import { Button, Dropdown, Stack } from '@rockshin/tao-ui';

const items = [
  { key: 'edit', label: 'Edit' },
  { key: 'duplicate', label: 'Duplicate' },
];

function DropdownTriggers() {
  const [feedback, setFeedback] = useState('');
  return (
    <>
      <Stack direction="horizontal" gap="md">
        <Dropdown trigger={['hover']} menu={{ items }}>
          <Button variant="secondary">Hover</Button>
        </Dropdown>
        <Dropdown trigger={['click']} arrow menu={{ items }}>
          <Button variant="secondary">Click with arrow</Button>
        </Dropdown>
        <Dropdown.Button menu={{ items }} onClick={() => setFeedback('save')}>
          Save
        </Dropdown.Button>
      </Stack>
      <output
        aria-live="polite"
        style={{
          display: 'block',
          marginTop: 12,
          whiteSpace: 'pre-wrap',
          overflowWrap: 'anywhere',
        }}
      >
        {feedback}
      </output>
    </>
  );
}

export default DropdownTriggers;
```

### Icons, shortcuts, and disabled items
Items support icons and extra content. Shortcut text is a hint and does not register a global keyboard shortcut.
```tsx preview
import { Button, Dropdown } from '@rockshin/tao-ui';

function FileIcon() {
  return (
    <svg
      aria-hidden="true"
      focusable="false"
      width="16"
      height="16"
      viewBox="0 0 24 24"
      fill="none"
      stroke="currentColor"
      strokeWidth="2"
      strokeLinecap="round"
      strokeLinejoin="round"
    >
      <path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z" />
      <path d="M14 2v6h6" />
    </svg>
  );
}

function CopyIcon() {
  return (
    <svg
      aria-hidden="true"
      focusable="false"
      width="16"
      height="16"
      viewBox="0 0 24 24"
      fill="none"
      stroke="currentColor"
      strokeWidth="2"
      strokeLinecap="round"
      strokeLinejoin="round"
    >
      <rect x="9" y="9" width="13" height="13" rx="2" />
      <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />
    </svg>
  );
}

function ClipboardIcon() {
  return (
    <svg
      aria-hidden="true"
      focusable="false"
      width="16"
      height="16"
      viewBox="0 0 24 24"
      fill="none"
      stroke="currentColor"
      strokeWidth="2"
      strokeLinecap="round"
      strokeLinejoin="round"
    >
      <rect x="8" y="2" width="8" height="4" rx="1" />
      <path d="M16 4h2a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h2" />
    </svg>
  );
}

export default function DropdownWithIconsAndShortcuts() {
  return (
    <Dropdown
      menu={{
        items: [
          { key: 'new', label: 'New file', icon: <FileIcon />, extra: '⌘N' },
          { key: 'copy', label: 'Copy', icon: <CopyIcon />, extra: '⌘C' },
          {
            key: 'paste',
            label: 'Paste',
            icon: <ClipboardIcon />,
            extra: '⌘V',
            disabled: true,
          },
        ],
      }}
    >
      <Button variant="secondary">Actions</Button>
    </Dropdown>
  );
}
```

### Groups and dividers
Group related tasks and separate different categories with dividers.
```tsx preview
import { Button, Dropdown } from '@rockshin/tao-ui';

export default function DropdownDividerAndGroup() {
  return (
    <Dropdown
      menu={{
        items: [
          {
            type: 'group',
            label: 'Account',
            children: [
              { key: 'profile', label: 'Profile' },
              { key: 'billing', label: 'Billing' },
            ],
          },
          { type: 'divider' },
          {
            type: 'group',
            label: 'Workspace',
            children: [
              { key: 'members', label: 'Members' },
              { key: 'settings', label: 'Settings' },
            ],
          },
          { type: 'divider' },
          { key: 'logout', label: 'Log out', danger: true },
        ],
      }}
    >
      <Button variant="secondary">Account</Button>
    </Dropdown>
  );
}
```

### Nested submenus
Nested `children` create submenus that remain navigable with arrow keys.
```tsx preview
import { Button, Dropdown, type MenuItem } from '@rockshin/tao-ui';

export default function DropdownSubmenu() {
  return (
    <Dropdown
      menu={{
        items: [
          { key: 'back', label: 'Back' },
          { key: 'forward', label: 'Forward', disabled: true },
          { type: 'divider' },
          {
            key: 'share',
            label: 'Share',
            children: [
              { key: 'mail', label: 'Email' },
              { key: 'message', label: 'Message' },
              {
                key: 'more',
                label: 'More',
                children: [
                  { key: 'twitter', label: 'Twitter' },
                  { key: 'facebook', label: 'Facebook' },
                ],
              },
            ],
          },
          { key: 'delete', label: 'Delete', danger: true, extra: '⌫' },
        ],
      }}
    >
      <Button variant="secondary">Right menu</Button>
    </Dropdown>
  );
}
```

### Controlled menu selection
Manage selected keys in application state for view modes or filtering choices.
```tsx preview
import { Button, Dropdown, Stack } from '@rockshin/tao-ui';

import { useState } from 'react';

export default function DropdownSelectable() {
  const [single, setSingle] = useState<string[]>(['md']);
  const [multi, setMulti] = useState<string[]>(['bold']);
  return (
    <Stack direction="horizontal" gap="lg">
      <Dropdown
        menu={{
          selectable: true,
          selectedKeys: single,
          onSelect: ({ selectedKeys }) => setSingle(selectedKeys),
          items: [
            { key: 'sm', label: 'Small' },
            { key: 'md', label: 'Medium' },
            { key: 'lg', label: 'Large' },
          ],
        }}
      >
        <Button variant="secondary">Size: {single[0]}</Button>
      </Dropdown>

      <Dropdown
        menu={{
          selectable: true,
          multiple: true,
          selectedKeys: multi,
          onSelect: ({ selectedKeys }) => setMulti(selectedKeys),
          items: [
            { key: 'bold', label: 'Bold' },
            { key: 'italic', label: 'Italic' },
            { key: 'underline', label: 'Underline' },
          ],
        }}
      >
        <Button variant="secondary">Format ({multi.length})</Button>
      </Dropdown>
    </Stack>
  );
}
```

### Menu placement
Configure `placement`; the popup still avoids viewport edges.
```tsx preview
import { Button, Dropdown, type MenuItem } from '@rockshin/tao-ui';

const basicItems: MenuItem[] = [
  { key: 'profile', label: 'Profile' },
  { key: 'billing', label: 'Billing' },
  { key: 'settings', label: 'Settings' },
];

export default function DropdownPlacement() {
  return (
    <div
      style={{
        display: 'grid',
        gridTemplateColumns: 'repeat(3, auto)',
        gap: 12,
        width: 'fit-content',
      }}
    >
      {(
        [
          'topLeft',
          'top',
          'topRight',
          'bottomLeft',
          'bottom',
          'bottomRight',
        ] as const
      ).map((p) => (
        <Dropdown key={p} placement={p} menu={{ items: basicItems }}>
          <Button variant="secondary">{p}</Button>
        </Dropdown>
      ))}
    </div>
  );
}
```

### Trigger behavior
Try click and hover triggers; retain a click entry point for touch devices.
```tsx preview
import { Button, Dropdown, type MenuItem, Stack } from '@rockshin/tao-ui';

const basicItems: MenuItem[] = [
  { key: 'profile', label: 'Profile' },
  { key: 'billing', label: 'Billing' },
  { key: 'settings', label: 'Settings' },
];

export default function DropdownTrigger() {
  return (
    <Stack direction="horizontal" gap="lg">
      <Dropdown trigger={['hover']} menu={{ items: basicItems }}>
        <Button variant="secondary">Hover me</Button>
      </Dropdown>
      <Dropdown trigger={['click']} arrow menu={{ items: basicItems }}>
        <Button variant="secondary">Click (with arrow)</Button>
      </Dropdown>
    </Stack>
  );
}
```

## API


### [#](#dropdown)Dropdown



| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| children | Trigger element (a single React element). | `ReactNode` **(Required)** | `-` |
| trigger | How the menu opens. Defaults to `['click']`. | `DropdownTrigger[] | undefined` | `-` |
| placement | Defaults to `'bottomLeft'`. Ignored for `contextMenu`. | `DropdownPlacement | undefined` | `-` |
| disabled | Whether to disable | `boolean | undefined` | `-` |
| arrow | Show a pointing arrow on the menu. Defaults to `false`. | `boolean | undefined` | `-` |
| className | Merged onto the floating content. | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |



### [#](#dropdownbutton)Dropdown.Button



| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| children | Main button content. | `ReactNode` | `-` |
| onClick | Main button click handler. | `(() => void) | undefined` | `-` |
| icon | Icon for the trigger button. Defaults to an ellipsis. | `ReactNode` | `-` |
| trigger | How the menu opens. Defaults to `['click']`. | `DropdownTrigger[] | undefined` | `-` |
| placement | Defaults to `'bottomLeft'`. Ignored for `contextMenu`. | `DropdownPlacement | undefined` | `-` |
| disabled | Whether to disable | `boolean | undefined` | `-` |
| arrow | Show a pointing arrow on the menu. Defaults to `false`. | `boolean | undefined` | `-` |
| className | Merged onto the floating content. | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |

