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.

submenuBehavior on Content sets how a submenu opens.

ValueBehaviourUse it for
cascadeOpens beside the parent menu. This is the defaultPointer use on wide screens
drill-downReplaces the menu content, with a back row at the topTouch 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>

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

PropTypeDefaultDescription
openbooleanWhether the menu is open, when you control it
defaultOpenbooleanfalseWhether the menu is open at first render
onOpenChange(open: boolean) => voidCalled when the menu opens or closes
modalbooleantrueBlocks 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

PropTypeDefaultDescription
size'1' | '2' | '3' | '4', responsive'2'The item height step
colorAccentColorTheme accentThe 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
sideOffsetnumber4The gap to the trigger in pixels
collisionPaddingnumber10The space kept from the edge of the screen
loopbooleanfalseWraps the arrow keys from the last item to the first
virtualizedbooleanfalseLeaves out the scroll area, for a Virtual Menu that scrolls itself
containerHTMLElementdocument.bodyThe element the portal renders into

Item

PropTypeDefaultDescription
onSelect(event: Event) => voidCalled when the item is chosen. Call event.preventDefault() to keep the menu open
colorAccentColorThe colour of the item
shortcutstringA key hint at the end of the item
disabledbooleanfalseStops the item from being chosen
textValuestringThe text for typeahead, when the children aren't plain text
asChildbooleanfalseRenders the child element, such as a link, with the item's look

CheckboxItem

PropTypeDefaultDescription
checkedboolean | 'indeterminate'Whether the option is on
onCheckedChange(checked: boolean) => voidCalled when the option turns on or off
color, shortcut, disabled, textValue, onSelectAs on Item

RadioGroup and RadioItem

PropTypeDefaultDescription
valuestringOn RadioGroup, the option that is on. On RadioItem, the value it sets. Required on RadioItem
onValueChange(value: string) => voidOn RadioGroup, called when another option turns on
color, disabled, textValue, onSelectOn RadioItem, as on Item

Sub, SubTrigger and SubContent

PropTypeDefaultDescription
labelReactNode'Back'On Sub, the text of the back row in drill-down
open, defaultOpen, onOpenChangeOn 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, textValueOn SubTrigger, as on Item
size, colorParent menu'sOn SubContent, as on Content
virtualized, container, loopOn 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

KeyAction
Enter, Space or Arrow DownOpens the menu from the trigger and focuses the first item
Arrow Down or Arrow UpMoves focus through the items
Home or EndMoves focus to the first or last item
Enter or SpaceChooses the focused item, or opens its submenu
Arrow RightOpens the submenu of the focused item
Arrow LeftCloses the submenu, or goes back one level in drill-down
A letter keyMoves focus to the next item that starts with it
EscapeCloses 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-haspopup and aria-expanded. Items have the menuitem role, and checkbox and radio items announce whether they're on. A shortcut hint is hidden from screen readers, which read aria-keyshortcuts instead.
  • 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.