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.
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.
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.
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
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.