Skip to content
Browse documentation
whisk/ui

DropdownMenu

Offer contextual actions from a trigger.

Overview

DropdownMenu presents contextual commands from a trigger. It manages menu roles, focus, dismissal, and positioning; application code owns what every command changes.

Use when

A trigger exposes a compact list of contextual actions.

Use instead

Use a dialog for a blocking decision or form, and Link navigation for primary destinations.

Usage

import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuTrigger,
} from "@smoothie-framework/whisk-react";

<DropdownMenu>
  <DropdownMenuTrigger>More actions</DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuItem onSelect={onDuplicate}>Duplicate</DropdownMenuItem>
    <DropdownMenuItem destructive onSelect={onArchive}>Archive</DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>

Examples

Group related commands

Use a label and separator when a menu has distinct command groups. A shortcut is a visual reminder only; register the matching keyboard shortcut in the application separately.

import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuSeparator,
  DropdownMenuShortcut,
  DropdownMenuTrigger,
} from "@smoothie-framework/whisk-react";

<DropdownMenu>
  <DropdownMenuTrigger>Project actions</DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuGroup>
      <DropdownMenuLabel>Project</DropdownMenuLabel>
      <DropdownMenuItem onSelect={onDuplicate}>Duplicate</DropdownMenuItem>
      <DropdownMenuItem onSelect={onRename}>
        Rename
        <DropdownMenuShortcut>⌘R</DropdownMenuShortcut>
      </DropdownMenuItem>
    </DropdownMenuGroup>
    <DropdownMenuSeparator />
    <DropdownMenuItem destructive onSelect={onArchive}>
      Archive project
    </DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>

Keep menu settings open

Checkbox items represent independent settings. Keep the menu open while a person changes several settings, and hold each checked value in application state. preventDefault in onSelect also cancels the item update and dismissal.

import {
  DropdownMenu,
  DropdownMenuCheckboxItem,
  DropdownMenuContent,
  DropdownMenuTrigger,
} from "@smoothie-framework/whisk-react";

type ColumnMenuProps = {
  showOwner: boolean;
  onShowOwnerChange: (checked: boolean) => void;
};

function ColumnMenu({ showOwner, onShowOwnerChange }: ColumnMenuProps) {
  return (
    <DropdownMenu closeOnSelect={false}>
      <DropdownMenuTrigger>Columns</DropdownMenuTrigger>
      <DropdownMenuContent aria-label="Visible columns">
        <DropdownMenuCheckboxItem
          checked={showOwner}
          onCheckedChange={onShowOwnerChange}
        >
          Owner
        </DropdownMenuCheckboxItem>
      </DropdownMenuContent>
    </DropdownMenu>
  );
}

Choose one menu option

Use a radio group for one active value. Unlike CheckboxItem, every radio item belongs to a controlled DropdownMenuRadioGroup.

tsx
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuTrigger,
} from "@smoothie-framework/whisk-react";

type SortMenuProps = {
  sort: string;
  onSortChange: (value: string) => void;
};

function SortMenu({ sort, onSortChange }: SortMenuProps) {
  return (
    <DropdownMenu closeOnSelect={false}>
      <DropdownMenuTrigger>Sort</DropdownMenuTrigger>
      <DropdownMenuContent>
        <DropdownMenuRadioGroup
          aria-label="Sort projects"
          value={sort}
          onValueChange={onSortChange}
        >
          <DropdownMenuRadioItem value="recent">Most recent</DropdownMenuRadioItem>
          <DropdownMenuRadioItem value="name">Name</DropdownMenuRadioItem>
        </DropdownMenuRadioGroup>
      </DropdownMenuContent>
    </DropdownMenu>
  );
}

Put secondary actions in a submenu

Use one submenu for a compact, clearly related secondary branch. If people need to compare actions across several levels, use a dedicated page or dialog instead.

tsx
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuTrigger,
} from "@smoothie-framework/whisk-react";

<DropdownMenu>
  <DropdownMenuTrigger>More actions</DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuItem onSelect={onDuplicate}>Duplicate</DropdownMenuItem>
    <DropdownMenuSub>
      <DropdownMenuSubTrigger>Move to</DropdownMenuSubTrigger>
      <DropdownMenuSubContent>
        <DropdownMenuItem onSelect={onMoveToInbox}>Inbox</DropdownMenuItem>
        <DropdownMenuItem onSelect={onMoveToArchive}>Archive</DropdownMenuItem>
      </DropdownMenuSubContent>
    </DropdownMenuSub>
  </DropdownMenuContent>
</DropdownMenu>

Offer actions on right-click

ContextTrigger keeps ordinary clicks and text selection intact. It opens on right-click, the Menu key, or Shift+F10. Use it for actions on the object under the pointer, not as a replacement for visible primary actions.

tsx
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
} from "@smoothie-framework/whisk-react";

<DropdownMenu>
  <DropdownMenuContextTrigger asChild>
    <article>Right-click this project card.</article>
  </DropdownMenuContextTrigger>
  <DropdownMenuContent aria-label="Project actions">
    <DropdownMenuItem onSelect={onDuplicate}>Duplicate</DropdownMenuItem>
    <DropdownMenuItem destructive onSelect={onArchive}>Archive</DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>

Props

Component props

PropTypeDefaultDescription
open | defaultOpenbooleannoneControl the open state or initialize an uncontrolled menu. Do not provide both or change ownership after mount.
onOpenChange(open: boolean) => voidnoneRequired with open. Update application state when the menu requests opening or dismissal.
sizesm | md | lgmdSet the default density for the trigger and content.
closeOnSelectbooleantrueClose after a command by default. Set it on the root or one item when a selection should leave the menu open.
positioning{ placement?, align?, offset?, strategy? }noneSet root defaults. placement is top, bottom, left, or right; align is start, center, or end; offset is nonnegative; strategy is absolute or fixed.
DropdownMenuTriggerbutton props & { asChild? }noneRenders a native button by default. asChild merges trigger behavior into exactly one element child.
DropdownMenuContextTriggerdiv props & { asChild?, disabled? }noneOpen on right-click or the Menu key or Shift+F10. disabled only disables Whisk/UI invocation; it does not suppress the browser context menu.
DropdownMenuContentdiv props & positioning propsnoneOverride placement, align, offset, positioning, or size for one surface. Give an aria-label when the trigger label does not name the menu.
DropdownMenuItembutton props & { onSelect?, destructive?, disabled?, closeOnSelect? }noneRun a command. startElement, endElement, and shortcut are decorative. Use textValue when visible text cannot describe the item for typeahead.
DropdownMenuCheckboxItemDropdownMenuItem props & { checked?, onCheckedChange? }noneRepresent an independent menu setting. checked is application-owned; this is not a form input or an implicit store.
DropdownMenuRadioGroup | DropdownMenuRadioItem{ value, onValueChange } | { value }noneUse a controlled group for one value from an exclusive set. Give the group an accessible name with aria-label or aria-labelledby.
DropdownMenuSub{ open?, defaultOpen?, onOpenChange? }noneCreate a nested menu inside its parent content. Its trigger and content belong directly inside the submenu.
DropdownMenuSubTrigger | DropdownMenuSubContentmenu item props | content propsnoneUse the trigger for a secondary action branch and content for its items. Submenus position at the inline end by default and flip in RTL.
DropdownMenuGroup | Label | Separator | Shortcutnative div | div | hr | span propsnoneGroup related commands, label a group, separate sections, or display a visual-only keyboard hint.

Accessibility

DropdownMenu uses native buttons with menu roles and returns focus to its trigger when it closes. From a trigger, ArrowDown and ArrowUp open the menu at its first or last item. Within a menu, Arrow keys, Home, End, and typeahead move focus; Escape closes it; Tab returns to the trigger and continues out of the menu. A submenu opens with Enter, Space, or its inline-direction Arrow key and closes with the opposite Arrow key. Keep commands as menu items, not nested buttons, inputs, or links. Give each rich or icon-only item textValue for typeahead, and give every radio group an accessible name.

Content guidance

Start each item with a specific verb. Name destructive outcomes directly, and keep contextual menu labels shorter than the surrounding page copy.