Actionsduskmoonimplemented17 demos

Dropdown

Dropdown attaches contextual action menus to a compact trigger.

Import@duskmoon-dev/components/dropdown
8API sections
24documented props
9behavior scenarios
Key API
menuoverlaydropdownRendertriggerplacementopen

Usage

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

StylesheetImport @duskmoon-dev/components/styles.css once in the app or docs shell.
StateStart with default props for static examples, then switch to controlled props when state must be shared.
ThemeThe preview inherits the active DuskMoon data-theme value from the docs layout.

Features

Wayfinding

Covers the route, section, step, or action-list patterns that help users move through an interface.

Current state

Shows selected, active, open, or current props where the component exposes them.

Primary API surface

Dropdown is most often configured through `menu`, `overlay`, `dropdownRender`, `trigger`.

Covered behavior

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.

Preview

Basic usage

authored

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>);
}
Preview

Connects a real trigger button to a native popover

test-backed

Dropdown 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>);
}
Preview

Closes after item selection

test-backed

Dropdown 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>);
}
Preview

Tracks native light dismissal

test-backed

Dropdown 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>);
}
Preview

Keeps controlled open state until the parent changes it

test-backed

Dropdown 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>);
}
Preview

Uses only the secondary button to invoke Dropdown.Button

test-backed

Dropdown 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>);
}
Preview

Disables native invocation when disabled

test-backed

Dropdown 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>);
}
Preview

Keeps the primary action separate from the menu trigger

test-backed

Dropdown 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>);
}
Preview

Forwards button styling and preserves a wrapped trigger and ref

test-backed

Dropdown 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>);
}
Preview

Disables both split controls while loading

test-backed

Dropdown 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>);
}
Preview

Split buttons

authored

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>
  );
}
Preview

Custom trigger icon

authored

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>
  );
}
Preview

Disabled split button

authored

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>
  );
}
Preview

Tooltip on trigger

authored

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>
  );
}
Preview

Button and danger

authored

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>
  );
}
Preview

Menu item states

authored

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>
  );
}
Preview

Theme aware

authored

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.

Types: packages/components/src/components/dropdown/Dropdown.types.tsScenarios: packages/components/src/components/dropdown/Dropdown.test.tsx
DropdownPropsinterface extends Omit<ComponentProps<"span">, "menu">
PropTypeRequiredDescription
menuDropdownMenuNomenu configures Dropdown.
overlayReactNodeNooverlay configures Dropdown.
dropdownRender(menus: ReactNode) => ReactNodeNodropdownRender configures Dropdown.
triggerDropdownTrigger[]Notrigger configures Dropdown.
placementDropdownPlacementNoplacement configures Dropdown.
openbooleanNoopen configures Dropdown.
defaultOpenbooleanNodefaultOpen configures Dropdown.
arrowbooleanNoarrow configures Dropdown.
disabledbooleanNodisabled configures Dropdown.
destroyPopupOnHidebooleanNodestroyPopupOnHide configures Dropdown.
onOpenChange(open: boolean) => voidNoonOpenChange configures Dropdown.
childrenReactNodeYeschildren configures Dropdown.
DropdownMenuIteminterface
PropTypeRequiredDescription
keystring | numberYeskey configures Dropdown.
labelReactNodeNolabel configures Dropdown.
iconReactNodeNoicon configures Dropdown.
disabledbooleanNodisabled configures Dropdown.
dangerbooleanNodanger configures Dropdown.
type"item" | "divider"Notype configures Dropdown.
classNamestringNoclassName configures Dropdown.
DropdownMenuInfointerface
PropTypeRequiredDescription
keystringYeskey configures Dropdown.
itemDropdownMenuItemYesitem configures Dropdown.
domEventMouseEvent<HTMLButtonElement>YesdomEvent configures Dropdown.
DropdownMenuinterface
PropTypeRequiredDescription
itemsDropdownMenuItem[]Noitems configures Dropdown.
onClick(info: DropdownMenuInfo) => voidNoonClick configures Dropdown.
DropdownPlacementtype
Type definition
| "top" | "bottom" | "left" | "right" | "topLeft" | "topRight" | "bottomLeft" | "bottomRight"
DropdownTriggertype
Type definition
"click" | "hover" | "contextMenu"
DropdownButtonPropstype
Type definition
Omit< DropdownProps, "children" | "onClick" | keyof ButtonProps > & Omit<ButtonProps, "children" | "onClick" | "ref"> & { buttonsRender?: (buttons: ReactNode[]) => ReactNode[]
DropdownComponenttype
Type definition
ForwardRefExoticComponent< DropdownProps & RefAttributes<HTMLSpanElement> > & { Button: ForwardRefExoticComponent< DropdownButtonProps & RefAttributes<HTMLSpanElement> >