Dropdown Menu
A dropdown menu opens a list of actions from a button.A dropdown menu opens a list of actions when someone presses its trigger, and runs one when they choose it. To choose a value for a form field, use a Select. To offer the same actions on right-click, use a Context Menu.
Playground
Usage
import { Button, DropdownMenu } from '@kushagradhawan/kookie-ui';
import { HugeiconsIcon } from '@hugeicons/react';
import { MoreHorizontalIcon } from '@hugeicons/core-free-icons';
export function ProjectActions({ onRename, onDuplicate, onDelete }: { onRename: () => void; onDuplicate: () => void; onDelete: () => void }) {
return (
<DropdownMenu.Root>
<DropdownMenu.Trigger>
<Button iconOnly emphasis="quiet" aria-label="Project actions">
<HugeiconsIcon icon={MoreHorizontalIcon} strokeWidth={1.75} />
</Button>
</DropdownMenu.Trigger>
<DropdownMenu.Content>
<DropdownMenu.Item shortcut="⌘ R" onSelect={onRename}>Rename</DropdownMenu.Item>
<DropdownMenu.Item shortcut="⌘ D" onSelect={onDuplicate}>Duplicate</DropdownMenu.Item>
<DropdownMenu.Separator />
<DropdownMenu.Item color="red" onSelect={onDelete}>Delete</DropdownMenu.Item>
</DropdownMenu.Content>
</DropdownMenu.Root>
);
}Anatomy
<DropdownMenu.Root>
<DropdownMenu.Trigger />
<DropdownMenu.Content>
<DropdownMenu.Label />
<DropdownMenu.Item />
<DropdownMenu.Group />
<DropdownMenu.CheckboxItem />
<DropdownMenu.RadioGroup>
<DropdownMenu.RadioItem />
</DropdownMenu.RadioGroup>
<DropdownMenu.Sub>
<DropdownMenu.SubTrigger />
<DropdownMenu.SubContent />
</DropdownMenu.Sub>
<DropdownMenu.Separator />
</DropdownMenu.Content>
</DropdownMenu.Root>- Root: Holds the open state.
- Trigger: Wraps one element, usually a Button, that opens the menu.
- TriggerIcon: A chevron to put inside a trigger button with a text label.
- Content: The menu, rendered in a portal and placed below the trigger.
- Item: One action.
- CheckboxItem: An option that turns on or off.
- RadioGroup and RadioItem: A set of options where one is on.
- Label: A heading for the items after it. It can't be chosen.
- Group and Separator: A set of related items, and a line between sets.
- Sub, SubTrigger and SubContent: A nested menu and the item that opens it.
Best practices
Start each item with a verb. "Rename", "Duplicate" and "Move to folder" say what happens. Keep the labels short, because the menu is only as wide as its longest item.
Put destructive actions last. Separate them from the other items and set color="red". Confirm an action that can't be undone in an Alert Dialog.
Keep menus shallow. One level of submenu is easy to follow. A second level hides items behind more hover and more aim, so move them into a dialog or a page instead.
Make the actions reachable somewhere else. A menu behind an icon-only button is easy to miss. Show the main action as its own button, and keep the menu for the less frequent ones.
Don't disable items without a reason people can see. A disabled item stays visible but doesn't say why. If the action is never available in this context, leave it out.
Size
size on Content picks one of four item heights and the padding around them. Size 2 is the default. Match the size of the trigger, so a size 1 button in a dense toolbar opens a size 1 menu. A submenu takes the size of its parent unless you set its own. size accepts a responsive object.
Submenu behaviour
submenuBehavior on Content sets how a submenu opens.
| Value | Behaviour | Use it for |
|---|---|---|
cascade | Opens beside the parent menu. This is the default | Pointer use on wide screens |
drill-down | Replaces the menu content, with a back row at the top | Touch screens and narrow layouts |
A responsive object such as { initial: 'drill-down', md: 'cascade' } gives phones the drill-down and wider screens the cascade. In drill-down, label on Sub sets the text of the back row, and Escape goes back one level before it closes the menu.
Examples
Button with a label
A trigger button with a text label shows a chevron, so people can tell it opens a menu. Put TriggerIcon after the label. The button sizes the icon.
<DropdownMenu.Trigger>
<Button>
Export
<DropdownMenu.TriggerIcon />
</Button>
</DropdownMenu.Trigger>View options
Use CheckboxItem for options that turn on or off, and a RadioGroup for options where one is on. These items stay as menu items, so the menu closes after each choice unless you call event.preventDefault() in onSelect.
<DropdownMenu.Content>
<DropdownMenu.Label>Show</DropdownMenu.Label>
<DropdownMenu.CheckboxItem checked={showDone} onCheckedChange={setShowDone}>
Completed tasks
</DropdownMenu.CheckboxItem>
<DropdownMenu.Separator />
<DropdownMenu.Label>Sort by</DropdownMenu.Label>
<DropdownMenu.RadioGroup value={sort} onValueChange={setSort}>
<DropdownMenu.RadioItem value="due">Due date</DropdownMenu.RadioItem>
<DropdownMenu.RadioItem value="priority">Priority</DropdownMenu.RadioItem>
</DropdownMenu.RadioGroup>
</DropdownMenu.Content>Nested actions
Group a set of related targets, such as folders, under a Sub.
<DropdownMenu.Sub label="Move to">
<DropdownMenu.SubTrigger>Move to</DropdownMenu.SubTrigger>
<DropdownMenu.SubContent>
<DropdownMenu.Item>Drafts</DropdownMenu.Item>
<DropdownMenu.Item>Archive</DropdownMenu.Item>
</DropdownMenu.SubContent>
</DropdownMenu.Sub>Links in a menu
When an item goes to another page, render your router's link with asChild. The item stays an anchor, so it opens in a new tab and shows its address like any link.
<DropdownMenu.Item asChild>
<Link href="/settings">Settings</Link>
</DropdownMenu.Item>Shortcut hints
shortcut shows a key hint at the end of the item and sets aria-keyshortcuts. It doesn't bind the key, so register the shortcut in your app as well.
Props
Root
| Prop | Type | Default | Description |
|---|---|---|---|
open | boolean | Whether the menu is open, when you control it | |
defaultOpen | boolean | false | Whether the menu is open at first render |
onOpenChange | (open: boolean) => void | Called when the menu opens or closes | |
modal | boolean | true | Blocks the rest of the page while the menu is open |
dir | 'ltr' | 'rtl' | The reading direction |
Trigger
Trigger takes one child element and accepts disabled. The child receives the trigger's attributes and events.
Content
| Prop | Type | Default | Description |
|---|---|---|---|
size | '1' | '2' | '3' | '4', responsive | '2' | The item height step |
color | AccentColor | Theme accent | The colour of the highlight |
submenuBehavior | 'cascade' | 'drill-down', responsive | 'cascade' | How submenus open |
side | 'top' | 'right' | 'bottom' | 'left' | 'bottom' | Where the menu opens |
align | 'start' | 'center' | 'end' | 'start' | How the menu lines up with the trigger |
sideOffset | number | 4 | The gap to the trigger in pixels |
collisionPadding | number | 10 | The space kept from the edge of the screen |
loop | boolean | false | Wraps the arrow keys from the last item to the first |
virtualized | boolean | false | Leaves out the scroll area, for a Virtual Menu that scrolls itself |
container | HTMLElement | document.body | The element the portal renders into |
Item
| Prop | Type | Default | Description |
|---|---|---|---|
onSelect | (event: Event) => void | Called when the item is chosen. Call event.preventDefault() to keep the menu open | |
color | AccentColor | The colour of the item | |
shortcut | string | A key hint at the end of the item | |
disabled | boolean | false | Stops the item from being chosen |
textValue | string | The text for typeahead, when the children aren't plain text | |
asChild | boolean | false | Renders the child element, such as a link, with the item's look |
CheckboxItem
| Prop | Type | Default | Description |
|---|---|---|---|
checked | boolean | 'indeterminate' | Whether the option is on | |
onCheckedChange | (checked: boolean) => void | Called when the option turns on or off | |
color, shortcut, disabled, textValue, onSelect | As on Item |
RadioGroup and RadioItem
| Prop | Type | Default | Description |
|---|---|---|---|
value | string | On RadioGroup, the option that is on. On RadioItem, the value it sets. Required on RadioItem | |
onValueChange | (value: string) => void | On RadioGroup, called when another option turns on | |
color, disabled, textValue, onSelect | On RadioItem, as on Item |
Sub, SubTrigger and SubContent
| Prop | Type | Default | Description |
|---|---|---|---|
label | ReactNode | 'Back' | On Sub, the text of the back row in drill-down |
open, defaultOpen, onOpenChange | On Sub, the open state of the submenu. In drill-down, a controlled open decides which panel shows, and the trigger, the back row, Arrow Left and Escape only call onOpenChange | ||
disabled, textValue | On SubTrigger, as on Item | ||
size, color | Parent menu's | On SubContent, as on Content | |
virtualized, container, loop | On SubContent, as on Content. Cascade only |
Content, the items, Label, Group, Separator and SubContent also accept the attributes of the HTML div element. TriggerIcon accepts the attributes of the svg element.
Accessibility
| Key | Action |
|---|---|
| Enter, Space or Arrow Down | Opens the menu from the trigger and focuses the first item |
| Arrow Down or Arrow Up | Moves focus through the items |
| Home or End | Moves focus to the first or last item |
| Enter or Space | Chooses the focused item, or opens its submenu |
| Arrow Right | Opens the submenu of the focused item |
| Arrow Left | Closes the submenu, or goes back one level in drill-down |
| A letter key | Moves focus to the next item that starts with it |
| Escape | Closes the menu and returns focus to the trigger |
- Name: The trigger announces its own label. An icon-only trigger needs
aria-label, as on any icon-only button. - Announcements: The trigger sets
aria-haspopupandaria-expanded. Items have themenuitemrole, and checkbox and radio items announce whether they're on. A shortcut hint is hidden from screen readers, which readaria-keyshortcutsinstead. - Groups: A Group or RadioGroup that holds a Label is named by that Label, so a screen reader announces the section as focus enters it.
- Drill-down: Each panel is a group named after its submenu. A trigger that opens a panel announces no popup, because the panel replaces the level in the same menu. The back row of a submenu labelled "Move to" is named "Back from Move to".
- Focus: Focus stays inside the open menu and returns to the trigger when it closes. A drill-down menu always reopens at its first level.