Dropdown
Dropdown attaches contextual action menus to a compact trigger.
@duskmoon-dev/components/dropdownUsage
When to use
- Use it when users need to move between sections, pages, steps, or contextual actions.
- Expose current and disabled state so navigation remains clear to keyboard and screen-reader users.
Implementation notes
Features
Covers the route, section, step, or action-list patterns that help users move through an interface.
Shows selected, active, open, or current props where the component exposes them.
Dropdown is most often configured through `menu`, `overlay`, `dropdownRender`, `trigger`.
Connects a real trigger button to a native popover
Feature Demos
Feature demos are authored for the component page, then supplemented with behavior scenarios from the component test coverage.
Basic usage
Import the component stylesheet and Dropdown from its package subpath, then render it with the core props.
Source
import "@duskmoon-dev/components/styles.css";
import { Dropdown } from "@duskmoon-dev/components/dropdown";
export function Example() {
return (<Dropdown
menu={{
items: [
{ key: "edit", label: "Edit" },
{ key: "divider", type: "divider" },
{ key: "delete", label: "Delete", danger: true }
]
}}
>
<button type="button">Actions</button>
</Dropdown>);
}Connects a real trigger button to a native popover
test-backedDropdown scenario from the component test coverage: connects a real trigger button to a native popover.
Source
import "@duskmoon-dev/components/styles.css";
import { Dropdown } from "@duskmoon-dev/components/dropdown";
export function DropdownConnectsARealTriggerDemo() {
return (<Dropdown
menu={{
items: [
{ key: "edit", label: "Edit" },
{ key: "divider", type: "divider" },
{ key: "delete", label: "Delete", danger: true }
]
}}
>
<button type="button">Actions</button>
</Dropdown>);
}Closes after item selection
test-backedDropdown scenario from the component test coverage: closes after item selection.
Source
import "@duskmoon-dev/components/styles.css";
import { Dropdown } from "@duskmoon-dev/components/dropdown";
export function DropdownClosesAfterItemSelectionDemo() {
return (<Dropdown
menu={{
items: [
{ key: "edit", label: "Edit" },
{ key: "divider", type: "divider" },
{ key: "delete", label: "Delete", danger: true }
]
}}
>
<button type="button">Actions</button>
</Dropdown>);
}Tracks native light dismissal
test-backedDropdown scenario from the component test coverage: tracks native light dismissal.
Source
import "@duskmoon-dev/components/styles.css";
import { Dropdown } from "@duskmoon-dev/components/dropdown";
export function DropdownTracksNativeLightDismissalDemo() {
return (<Dropdown
menu={{
items: [
{ key: "edit", label: "Edit" },
{ key: "divider", type: "divider" },
{ key: "delete", label: "Delete", danger: true }
]
}}
>
<button type="button">Actions</button>
</Dropdown>);
}Keeps controlled open state until the parent changes it
test-backedDropdown scenario from the component test coverage: keeps controlled open state until the parent changes it.
Source
import "@duskmoon-dev/components/styles.css";
import { Dropdown } from "@duskmoon-dev/components/dropdown";
export function DropdownKeepsControlledOpenStateDemo() {
return (<Dropdown
menu={{
items: [
{ key: "edit", label: "Edit" },
{ key: "divider", type: "divider" },
{ key: "delete", label: "Delete", danger: true }
]
}}
>
<button type="button">Actions</button>
</Dropdown>);
}Uses only the secondary button to invoke Dropdown.Button
test-backedDropdown scenario from the component test coverage: uses only the secondary button to invoke dropdown.button.
Source
import "@duskmoon-dev/components/styles.css";
import { Dropdown } from "@duskmoon-dev/components/dropdown";
export function DropdownUsesOnlyTheSecondaryDemo() {
return (<Dropdown
menu={{
items: [
{ key: "edit", label: "Edit" },
{ key: "divider", type: "divider" },
{ key: "delete", label: "Delete", danger: true }
]
}}
>
<button type="button">Actions</button>
</Dropdown>);
}Disables native invocation when disabled
test-backedDropdown scenario from the component test coverage: disables native invocation when disabled.
Source
import "@duskmoon-dev/components/styles.css";
import { Dropdown } from "@duskmoon-dev/components/dropdown";
export function DropdownDisablesNativeInvocationWhenDemo() {
return (<Dropdown
menu={{
items: [
{ key: "edit", label: "Edit" },
{ key: "divider", type: "divider" },
{ key: "delete", label: "Delete", danger: true }
]
}}
>
<button type="button">Actions</button>
</Dropdown>);
}Keeps the primary action separate from the menu trigger
test-backedDropdown scenario from the component test coverage: keeps the primary action separate from the menu trigger.
Source
import "@duskmoon-dev/components/styles.css";
import { Dropdown } from "@duskmoon-dev/components/dropdown";
export function DropdownKeepsThePrimaryActionDemo() {
return (<Dropdown
menu={{
items: [
{ key: "edit", label: "Edit" },
{ key: "divider", type: "divider" },
{ key: "delete", label: "Delete", danger: true }
]
}}
>
<button type="button">Actions</button>
</Dropdown>);
}Forwards button styling and preserves a wrapped trigger and ref
test-backedDropdown scenario from the component test coverage: forwards button styling and preserves a wrapped trigger and ref.
Source
import "@duskmoon-dev/components/styles.css";
import { Dropdown } from "@duskmoon-dev/components/dropdown";
export function DropdownForwardsButtonStylingAndDemo() {
return (<Dropdown
menu={{
items: [
{ key: "edit", label: "Edit" },
{ key: "divider", type: "divider" },
{ key: "delete", label: "Delete", danger: true }
]
}}
>
<button type="button">Actions</button>
</Dropdown>);
}Disables both split controls while loading
test-backedDropdown scenario from the component test coverage: disables both split controls while loading.
Source
import "@duskmoon-dev/components/styles.css";
import { Dropdown } from "@duskmoon-dev/components/dropdown";
export function DropdownDisablesBothSplitControlsDemo() {
return (<Dropdown
menu={{
items: [
{ key: "edit", label: "Edit" },
{ key: "divider", type: "divider" },
{ key: "delete", label: "Delete", danger: true }
]
}}
>
<button type="button">Actions</button>
</Dropdown>);
}Split buttons
Use the split button for a primary action alongside a menu of related workspace actions.
Source
import "@duskmoon-dev/components/styles.css";
import React from "react";
import { Dropdown } from "@duskmoon-dev/components/dropdown";
import { Button, Tooltip } from "@duskmoon-dev/components";
function UserIcon() {
return <svg aria-hidden="true" width="16" height="16" fill="none" stroke="currentColor" strokeWidth="1.75" viewBox="0 0 24 24"><circle cx="12" cy="8" r="3.25" /><path strokeLinecap="round" d="M5.5 20a6.5 6.5 0 0 1 13 0" /></svg>;
}
const actionMenu = {
items: [
{ key: "overview", label: "Overview", icon: <UserIcon /> },
{ key: "members", label: "Members", icon: <UserIcon /> },
{ key: "delete", label: "Delete workspace", danger: true, icon: <UserIcon /> },
{ key: "invite", label: "Invite member", disabled: true, icon: <UserIcon /> },
]
};
export function DropdownSplitButtonsDemo() {
return (
<Dropdown.Button appearance="outline" color="base" menu={actionMenu}>
Actions
</Dropdown.Button>
);
}Custom trigger icon
Replace the split button trigger content with a custom icon while preserving its click behavior.
Source
import "@duskmoon-dev/components/styles.css";
import React from "react";
import { Dropdown } from "@duskmoon-dev/components/dropdown";
import { Button, Tooltip } from "@duskmoon-dev/components";
function UserIcon() {
return <svg aria-hidden="true" width="16" height="16" fill="none" stroke="currentColor" strokeWidth="1.75" viewBox="0 0 24 24"><circle cx="12" cy="8" r="3.25" /><path strokeLinecap="round" d="M5.5 20a6.5 6.5 0 0 1 13 0" /></svg>;
}
const actionMenu = {
items: [
{ key: "overview", label: "Overview", icon: <UserIcon /> },
{ key: "members", label: "Members", icon: <UserIcon /> },
{ key: "delete", label: "Delete workspace", danger: true, icon: <UserIcon /> },
{ key: "invite", label: "Invite member", disabled: true, icon: <UserIcon /> },
]
};
export function DropdownCustomTriggerIconDemo() {
return (
<Dropdown.Button
appearance="outline"
color="base"
buttonsRender={(buttons) => [
buttons[0],
React.cloneElement(buttons[1] as React.ReactElement<{ children?: React.ReactNode }>, { children: <UserIcon /> }),
]}
menu={actionMenu}
>
Actions
</Dropdown.Button>
);
}Disabled split button
Disable both parts of the split button when the action menu is unavailable.
Source
import "@duskmoon-dev/components/styles.css";
import React from "react";
import { Dropdown } from "@duskmoon-dev/components/dropdown";
import { Button, Tooltip } from "@duskmoon-dev/components";
function UserIcon() {
return <svg aria-hidden="true" width="16" height="16" fill="none" stroke="currentColor" strokeWidth="1.75" viewBox="0 0 24 24"><circle cx="12" cy="8" r="3.25" /><path strokeLinecap="round" d="M5.5 20a6.5 6.5 0 0 1 13 0" /></svg>;
}
const actionMenu = {
items: [
{ key: "overview", label: "Overview", icon: <UserIcon /> },
{ key: "members", label: "Members", icon: <UserIcon /> },
{ key: "delete", label: "Delete workspace", danger: true, icon: <UserIcon /> },
{ key: "invite", label: "Invite member", disabled: true, icon: <UserIcon /> },
]
};
export function DisabledDropdownSplitButtonDemo() {
return (
<Dropdown.Button appearance="outline" color="base" disabled menu={actionMenu}>
Actions
</Dropdown.Button>
);
}Tooltip on trigger
Wrap only the menu trigger with a Tooltip to explain where it leads.
Source
import "@duskmoon-dev/components/styles.css";
import React from "react";
import { Dropdown } from "@duskmoon-dev/components/dropdown";
import { Button, Tooltip } from "@duskmoon-dev/components";
function UserIcon() {
return <svg aria-hidden="true" width="16" height="16" fill="none" stroke="currentColor" strokeWidth="1.75" viewBox="0 0 24 24"><circle cx="12" cy="8" r="3.25" /><path strokeLinecap="round" d="M5.5 20a6.5 6.5 0 0 1 13 0" /></svg>;
}
const actionMenu = {
items: [
{ key: "overview", label: "Overview", icon: <UserIcon /> },
{ key: "members", label: "Members", icon: <UserIcon /> },
{ key: "delete", label: "Delete workspace", danger: true, icon: <UserIcon /> },
{ key: "invite", label: "Invite member", disabled: true, icon: <UserIcon /> },
]
};
export function DropdownTooltipTriggerDemo() {
return (
<Dropdown.Button
appearance="outline"
color="base"
buttonsRender={(buttons) => [
buttons[0],
<Tooltip key="trigger" id="dropdown-trigger-help" title="Open workspace actions">
{buttons[1]}
</Tooltip>,
]}
menu={actionMenu}
>
Actions
</Dropdown.Button>
);
}Button and danger
Use a regular Button as a dropdown trigger, and reserve the error color for destructive split actions.
Source
import "@duskmoon-dev/components/styles.css";
import React from "react";
import { Dropdown } from "@duskmoon-dev/components/dropdown";
import { Button, Tooltip } from "@duskmoon-dev/components";
function UserIcon() {
return <svg aria-hidden="true" width="16" height="16" fill="none" stroke="currentColor" strokeWidth="1.75" viewBox="0 0 24 24"><circle cx="12" cy="8" r="3.25" /><path strokeLinecap="round" d="M5.5 20a6.5 6.5 0 0 1 13 0" /></svg>;
}
const actionMenu = {
items: [
{ key: "overview", label: "Overview", icon: <UserIcon /> },
{ key: "members", label: "Members", icon: <UserIcon /> },
{ key: "delete", label: "Delete workspace", danger: true, icon: <UserIcon /> },
{ key: "invite", label: "Invite member", disabled: true, icon: <UserIcon /> },
]
};
function ChevronDownIcon() {
return <svg aria-hidden="true" width="16" height="16" fill="none" stroke="currentColor" strokeWidth="1.75" viewBox="0 0 24 24"><path strokeLinecap="round" strokeLinejoin="round" d="m6 9 6 6 6-6" /></svg>;
}
export function DropdownButtonAndDangerDemo() {
return (
<div className="dropdown-button-danger-preview" style={{ display: "flex", flexWrap: "wrap", gap: 16, alignItems: "flex-start" }}>
<Dropdown trigger={["click"]} menu={actionMenu}>
<Button appearance="outline" color="base" rightIcon={<ChevronDownIcon />}>
Actions
</Button>
</Dropdown>
<Dropdown.Button appearance="outline" color="error" menu={actionMenu}>
Delete
</Dropdown.Button>
</div>
);
}Menu item states
Combine regular, destructive, and unavailable menu items in one open menu preview.
Source
import "@duskmoon-dev/components/styles.css";
import React from "react";
import { Dropdown } from "@duskmoon-dev/components/dropdown";
import { Button, Tooltip } from "@duskmoon-dev/components";
function UserIcon() {
return <svg aria-hidden="true" width="16" height="16" fill="none" stroke="currentColor" strokeWidth="1.75" viewBox="0 0 24 24"><circle cx="12" cy="8" r="3.25" /><path strokeLinecap="round" d="M5.5 20a6.5 6.5 0 0 1 13 0" /></svg>;
}
const actionMenu = {
items: [
{ key: "overview", label: "Overview", icon: <UserIcon /> },
{ key: "members", label: "Members", icon: <UserIcon /> },
{ key: "delete", label: "Delete workspace", danger: true, icon: <UserIcon /> },
{ key: "invite", label: "Invite member", disabled: true, icon: <UserIcon /> },
]
};
export function DropdownMenuItemStatesDemo() {
return (
<Dropdown.Button
appearance="outline"
color="base"
defaultOpen
menu={actionMenu}
>
Actions
</Dropdown.Button>
);
}Theme aware
Docs previews inherit the DuskMoon data-theme value. Use the header switch to compare light and dark rendering.
Source
<div data-theme="sunshine">
<Dropdown
menu={{
items: [
{ key: "edit", label: "Edit" },
{ key: "divider", type: "divider" },
{ key: "delete", label: "Delete", danger: true }
]
}}
>
<button type="button">Actions</button>
</Dropdown>
</div>
<div data-theme="moonlight">
<Dropdown
menu={{
items: [
{ key: "edit", label: "Edit" },
{ key: "divider", type: "divider" },
{ key: "delete", label: "Delete", danger: true }
]
}}
>
<button type="button">Actions</button>
</Dropdown>
</div>API
The API reference below lists every parsed exported type or interface for Dropdown. Start with `menu`, `overlay`, `dropdownRender`, `trigger` for common usage.
packages/components/src/components/dropdown/Dropdown.types.tsScenarios: packages/components/src/components/dropdown/Dropdown.test.tsx| Prop | Type | Required | Description |
|---|---|---|---|
menu | DropdownMenu | No | menu configures Dropdown. |
overlay | ReactNode | No | overlay configures Dropdown. |
dropdownRender | (menus: ReactNode) => ReactNode | No | dropdownRender configures Dropdown. |
trigger | DropdownTrigger[] | No | trigger configures Dropdown. |
placement | DropdownPlacement | No | placement configures Dropdown. |
open | boolean | No | open configures Dropdown. |
defaultOpen | boolean | No | defaultOpen configures Dropdown. |
arrow | boolean | No | arrow configures Dropdown. |
disabled | boolean | No | disabled configures Dropdown. |
destroyPopupOnHide | boolean | No | destroyPopupOnHide configures Dropdown. |
onOpenChange | (open: boolean) => void | No | onOpenChange configures Dropdown. |
children | ReactNode | Yes | children configures Dropdown. |
| Prop | Type | Required | Description |
|---|---|---|---|
key | string | number | Yes | key configures Dropdown. |
label | ReactNode | No | label configures Dropdown. |
icon | ReactNode | No | icon configures Dropdown. |
disabled | boolean | No | disabled configures Dropdown. |
danger | boolean | No | danger configures Dropdown. |
type | "item" | "divider" | No | type configures Dropdown. |
className | string | No | className configures Dropdown. |
| Prop | Type | Required | Description |
|---|---|---|---|
key | string | Yes | key configures Dropdown. |
item | DropdownMenuItem | Yes | item configures Dropdown. |
domEvent | MouseEvent<HTMLButtonElement> | Yes | domEvent configures Dropdown. |
| Prop | Type | Required | Description |
|---|---|---|---|
items | DropdownMenuItem[] | No | items configures Dropdown. |
onClick | (info: DropdownMenuInfo) => void | No | onClick configures Dropdown. |
Type definition
| "top" | "bottom" | "left" | "right" | "topLeft" | "topRight" | "bottomLeft" | "bottomRight"Type definition
"click" | "hover" | "contextMenu"Type definition
Omit< DropdownProps, "children" | "onClick" | keyof ButtonProps > & Omit<ButtonProps, "children" | "onClick" | "ref"> & { buttonsRender?: (buttons: ReactNode[]) => ReactNode[]Type definition
ForwardRefExoticComponent< DropdownProps & RefAttributes<HTMLSpanElement> > & { Button: ForwardRefExoticComponent< DropdownButtonProps & RefAttributes<HTMLSpanElement> >