Dropdown#
Navigation
@rockshin/tao-uiOpens 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
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
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
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
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
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
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
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
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
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
| 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 | - |
#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 | - |