DropdownMenu

A menu of actions or options that opens from a button you click. Built on base-ui Menu — focus management, type-ahead, keyboard navigation, and ARIA wiring come for free.

Reach for DropdownMenu when a button reveals a list of actions (a row’s ”⋯” overflow, a “New” split button, a settings cog). It is the click-triggered sibling of ContextMenu — same items and parts, but opened by a button instead of a right-click — and of Menubar, which arranges several such menus into a persistent application bar.

Compose DropdownMenu (root), DropdownMenuTrigger (the button — pass your own via the render prop), and DropdownMenuContent (the popup), then fill the content with DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator, and friends.

Basic

The trigger uses base-ui’s render prop to borrow any element — here a Button. Inside DropdownMenuContent, lay out DropdownMenuItems, group them with a DropdownMenuLabel and DropdownMenuSeparator, hint at keybindings with DropdownMenuShortcut, and flag a dangerous action with variant="destructive". A leading lucide icon auto-sizes to size-4.

import {
  Button,
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuSeparator,
  DropdownMenuShortcut,
  DropdownMenuTrigger,
} from "@vesyl/ui-next";
import { Copy, Pencil, Printer, Trash2 } from "lucide-react";

export default function DropdownMenuBasic() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger
        render={(props) => (
          <Button {...props} variant="outline" size="sm">
            Order actions
          </Button>
        )}
      />
      <DropdownMenuContent>
        <DropdownMenuLabel>Order #1042</DropdownMenuLabel>
        <DropdownMenuSeparator />
        <DropdownMenuItem>
          <Printer />
          Print label
          <DropdownMenuShortcut>⌘P</DropdownMenuShortcut>
        </DropdownMenuItem>
        <DropdownMenuItem>
          <Copy />
          Duplicate order
          <DropdownMenuShortcut>⌘D</DropdownMenuShortcut>
        </DropdownMenuItem>
        <DropdownMenuItem>
          <Pencil />
          Edit details
        </DropdownMenuItem>
        <DropdownMenuSeparator />
        <DropdownMenuItem variant="destructive">
          <Trash2 />
          Cancel shipment
        </DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  );
}

Checkbox items

DropdownMenuCheckboxItem is a toggle that stays in the menu — ideal for show/hide column pickers and multi-select filters. Drive each with checked and onCheckedChange; the check indicator renders automatically.

import {
  Button,
  DropdownMenu,
  DropdownMenuCheckboxItem,
  DropdownMenuContent,
  DropdownMenuLabel,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
} from "@vesyl/ui-next";
import { SlidersHorizontal } from "lucide-react";
import { useState } from "react";

export default function DropdownMenuCheckbox() {
  const [columns, setColumns] = useState({
    tracking: true,
    carrier: true,
    weight: false,
    cost: false,
  });

  return (
    <DropdownMenu>
      <DropdownMenuTrigger
        render={(props) => (
          <Button {...props} variant="outline" size="sm">
            <SlidersHorizontal />
            Columns
          </Button>
        )}
      />
      <DropdownMenuContent>
        <DropdownMenuLabel>Visible columns</DropdownMenuLabel>
        <DropdownMenuSeparator />
        <DropdownMenuCheckboxItem
          checked={columns.tracking}
          onCheckedChange={(v) => setColumns((c) => ({ ...c, tracking: v }))}
        >
          Tracking number
        </DropdownMenuCheckboxItem>
        <DropdownMenuCheckboxItem
          checked={columns.carrier}
          onCheckedChange={(v) => setColumns((c) => ({ ...c, carrier: v }))}
        >
          Carrier
        </DropdownMenuCheckboxItem>
        <DropdownMenuCheckboxItem
          checked={columns.weight}
          onCheckedChange={(v) => setColumns((c) => ({ ...c, weight: v }))}
        >
          Weight
        </DropdownMenuCheckboxItem>
        <DropdownMenuCheckboxItem
          checked={columns.cost}
          onCheckedChange={(v) => setColumns((c) => ({ ...c, cost: v }))}
        >
          Label cost
        </DropdownMenuCheckboxItem>
      </DropdownMenuContent>
    </DropdownMenu>
  );
}

Radio group

Wrap DropdownMenuRadioItems in a DropdownMenuRadioGroup for a single-choice set, like a sort order. The group owns the selected value and fires onValueChange; each item declares its value.

import {
  Button,
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuLabel,
  DropdownMenuRadioGroup,
  DropdownMenuRadioItem,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
} from "@vesyl/ui-next";
import { ArrowUpDown } from "lucide-react";
import { useState } from "react";

export default function DropdownMenuRadio() {
  const [sort, setSort] = useState("created");

  return (
    <DropdownMenu>
      <DropdownMenuTrigger
        render={(props) => (
          <Button {...props} variant="outline" size="sm">
            <ArrowUpDown />
            Sort orders
          </Button>
        )}
      />
      <DropdownMenuContent>
        <DropdownMenuLabel>Sort by</DropdownMenuLabel>
        <DropdownMenuSeparator />
        <DropdownMenuRadioGroup value={sort} onValueChange={setSort}>
          <DropdownMenuRadioItem value="created">Date created</DropdownMenuRadioItem>
          <DropdownMenuRadioItem value="ship-by">Ship-by date</DropdownMenuRadioItem>
          <DropdownMenuRadioItem value="total">Order total</DropdownMenuRadioItem>
          <DropdownMenuRadioItem value="status">Fulfillment status</DropdownMenuRadioItem>
        </DropdownMenuRadioGroup>
      </DropdownMenuContent>
    </DropdownMenu>
  );
}

Submenus

Nest a DropdownMenuSub with a DropdownMenuSubTrigger (it gets a trailing chevron) and a DropdownMenuSubContent to fan out related actions — print formats, carrier choices — without crowding the top level.

import {
  Button,
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuSeparator,
  DropdownMenuSub,
  DropdownMenuSubContent,
  DropdownMenuSubTrigger,
  DropdownMenuTrigger,
} from "@vesyl/ui-next";
import { Package, Printer, Send, Tag } from "lucide-react";

export default function DropdownMenuSubmenus() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger
        render={(props) => (
          <Button {...props} variant="outline" size="sm">
            Fulfill order
          </Button>
        )}
      />
      <DropdownMenuContent>
        <DropdownMenuItem>
          <Package />
          Mark as packed
        </DropdownMenuItem>
        <DropdownMenuSub>
          <DropdownMenuSubTrigger>
            <Printer />
            Print label
          </DropdownMenuSubTrigger>
          <DropdownMenuSubContent>
            <DropdownMenuItem>4×6 thermal</DropdownMenuItem>
            <DropdownMenuItem>8.5×11 letter</DropdownMenuItem>
            <DropdownMenuSeparator />
            <DropdownMenuItem>Packing slip</DropdownMenuItem>
          </DropdownMenuSubContent>
        </DropdownMenuSub>
        <DropdownMenuSub>
          <DropdownMenuSubTrigger>
            <Tag />
            Buy postage
          </DropdownMenuSubTrigger>
          <DropdownMenuSubContent>
            <DropdownMenuItem>USPS Ground Advantage</DropdownMenuItem>
            <DropdownMenuItem>UPS Ground</DropdownMenuItem>
            <DropdownMenuItem>FedEx Home Delivery</DropdownMenuItem>
          </DropdownMenuSubContent>
        </DropdownMenuSub>
        <DropdownMenuSeparator />
        <DropdownMenuItem>
          <Send />
          Send tracking email
        </DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  );
}

Destructive & disabled items

variant="destructive" paints an item (and its icon) in the destructive color and tints its focus background. disabled dims an item and removes it from pointer and keyboard interaction. Pass align="end" to DropdownMenuContent to right-align the popup under an overflow trigger.

import {
  Button,
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
} from "@vesyl/ui-next";
import { Archive, MoreHorizontal, RotateCcw, Trash2 } from "lucide-react";

export default function DropdownMenuDestructive() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger
        render={(props) => (
          <Button {...props} variant="outline" size="icon" aria-label="Shipment actions">
            <MoreHorizontal />
          </Button>
        )}
      />
      <DropdownMenuContent align="end">
        <DropdownMenuItem>
          <RotateCcw />
          Refund label
        </DropdownMenuItem>
        <DropdownMenuItem>
          <Archive />
          Archive order
        </DropdownMenuItem>
        <DropdownMenuItem disabled>Reprint (already voided)</DropdownMenuItem>
        <DropdownMenuSeparator />
        <DropdownMenuItem variant="destructive">
          <Trash2 />
          Cancel shipment
        </DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  );
}

Reference

DropdownMenu

Root container. Extends base-ui Menu.Root props.

Prop	Type	Default	Description
`modal`	`boolean`	`false`	Trap focus and block outside interaction while open
`open`	`boolean`	—	Open state (controlled)
`defaultOpen`	`boolean`	—	Initial open state (uncontrolled)
`onOpenChange`	`(open) => void`	—	Fires when the menu opens or closes

DropdownMenuTrigger

The button that opens the menu. Extends base-ui Menu.Trigger props.

Prop	Type	Default	Description
`render`	`(props) => ReactElement` \| `ReactElement`	—	Render your own trigger element (e.g. a `Button`) with merged props

DropdownMenuContent

The popup surface. Extends base-ui Menu.Popup plus positioner props.

Prop	Type	Default	Description
`align`	`"start" \| "center" \| "end"`	`"start"`	Alignment relative to the trigger
`alignOffset`	`number`	`0`	Pixel offset along the alignment axis
`side`	`"top" \| "right" \| "bottom" \| "left"`	`"bottom"`	Which side of the trigger to open on
`sideOffset`	`number`	`4`	Gap between the trigger and the popup
`className`	`string`	—	Merged onto the popup

DropdownMenuItem

A clickable action. Extends base-ui Menu.Item props.

Prop	Type	Default	Description
`variant`	`"default" \| "destructive"`	`"default"`	Destructive paints the item and its icon red
`inset`	`boolean`	`false`	Pad the left edge to align with items that have icons
`disabled`	`boolean`	`false`	Dim the item and disable interaction
`onClick`	`(event) => void`	—	Fires when the item is activated

DropdownMenuCheckboxItem

A toggleable item. Extends base-ui Menu.CheckboxItem props.

Prop	Type	Default	Description
`checked`	`boolean`	—	Checked state (controlled)
`onCheckedChange`	`(checked) => void`	—	Fires when the checked state changes
`disabled`	`boolean`	`false`	Dim the item and disable interaction

DropdownMenuRadioGroup

Single-choice container. Extends base-ui Menu.RadioGroup props.

Prop	Type	Default	Description
`value`	`any`	—	Selected item value (controlled)
`defaultValue`	`any`	—	Initial value (uncontrolled)
`onValueChange`	`(value) => void`	—	Fires when the selection changes

DropdownMenuRadioItem

One radio choice. Extends base-ui Menu.RadioItem props.

Prop	Type	Default	Description
`value`	`any`	—	Identifies this choice in the group

Sub-parts

Part	Wraps	Notes
`DropdownMenuLabel`	`Menu.GroupLabel`	Non-interactive section heading; accepts `inset`
`DropdownMenuSeparator`	`Menu.Separator`	A hairline rule between groups
`DropdownMenuGroup`	`Menu.Group`	Groups items under a `DropdownMenuLabel`
`DropdownMenuShortcut`	`span`	Muted, right-aligned keybinding hint inside an item
`DropdownMenuSub`	`Menu.SubmenuRoot`	Wraps a submenu’s trigger and content
`DropdownMenuSubTrigger`	`Menu.SubmenuTrigger`	Opens the submenu; renders a trailing chevron
`DropdownMenuSubContent`	`DropdownMenuContent`	The nested popup; defaults to `side="right"`