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, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/en/components/dropdown.md.

Dropdown

Group additional actions in a menu.

Basic usage

Provide menu actions through items and use a button as the trigger.

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>
  );
}

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.

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>
  );
}

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

Small
Default
Large
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>
  );
}

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.

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>
  );
}

Radio menu

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

Current view: List
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>
  );
}

Checkbox menu

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

Details are visible
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>
  );
}

Hover trigger

With trigger="hover", pointer hover opens the menu. The focused button still supports opening with arrow keys.

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>
  );
}

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.

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>
  );
}

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.

PropertyTypeDefaultDescription
itemsreadonly DropdownItem[]RequiredMenu entries
childrenReactElement< ButtonHTMLAttributes<HTMLButtonElement> & { ref?: Ref<HTMLButtonElement> } >RequiredA single Leaf Button or native button
trigger'click' | 'hover' | 'contextMenu' | readonly ('click' | 'hover' | 'contextMenu')[]'click'Trigger mode; Dropdown supports click, hover and context menu.
disabledbooleanfalseDisable interaction.
size'sm' | 'md' | 'lg''md'Presentation size.
openboolean—Controlled open state.
defaultOpenbooleanfalseInitial 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.
popupWidthnumber | string—Popup width; grows with content from a 160px minimum when unset.
popupMaxWidthnumber | string420Maximum popup width, still bounded by the viewport.
itemRender(item: DropdownItem) => ReactNode—Customize the item label content, not the whole row.
mouseEnterDelaynumber100Delay in milliseconds before opening on hover.
mouseLeaveDelaynumber150Delay 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.
popupClassNamestring—Custom class for the popup.
popupStyleCSSProperties—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.

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

PropertyTypeDefaultDescription
keystringRequiredUnique key
labelReactNode—Item label or group heading.
iconReactNode—Icon before the item label.
extraReactNode—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.
childrenreadonly DropdownItem[]—Menu entries.
disabledbooleanfalseDisable interaction.
dangerbooleanfalseDestructive-action colors without disabling the item.
checkedboolean—Controlled checked state; stored internally when omitted.
groupstring—Mutual-exclusion group identifier for radio items.
closeOnSelectboolean—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.
hrefstring—Link destination.
targetstring—Link target attribute, such as _blank; opens in the current tab when omitted.
onClick(event: MouseEvent<HTMLElement>) => void—Runs when the item is selected