#Dropdown
Group additional actions in a menu.
#Basic usage
Provide menu actions through items and use a button as the trigger.
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>
);
}
#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.
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>
);
}
#Menu sizes
Set the menu size with Dropdown's size; submenus inherit it. The trigger Button has its own size.
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>
);
}
#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.
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>
);
}
#Radio menu
Set type: 'radio' and use the same group identifier for mutually exclusive choices. This example manages the view through checked and onCheckedChange.
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>
);
}
#Checkbox menu
Radio and checkbox items keep the menu open after selection by default. Override this with closeOnSelect.
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>
);
}
#Hover trigger
With trigger="hover", pointer hover opens the menu. The focused button still supports opening with arrow keys.
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>
);
}
#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.
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>
);
}
#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 for shared popup options.
| Property | Type | Default | Description |
|---|---|---|---|
items | readonly 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) => 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[] | — | 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 |