Dropdown Menu

Displays a menu of actions or links to the user, triggered by a button.

Open

<DropdownMenu>
  <DropdownMenuTrigger render={<Button variant="outline" />}>
Open
</DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuGroup>
      <DropdownMenuLabel>My Account</DropdownMenuLabel>
      <DropdownMenuItem>Profile</DropdownMenuItem>
      <DropdownMenuItem>Billing</DropdownMenuItem>
    </DropdownMenuGroup>
    <DropdownMenuSeparator />
    <DropdownMenuGroup>
      <DropdownMenuItem>Team</DropdownMenuItem>
      <DropdownMenuItem>Subscription</DropdownMenuItem>
    </DropdownMenuGroup>
  </DropdownMenuContent>
</DropdownMenu>

Installation

pnpm dlx cubix@latest add dropdown-menu

Usage

Import

import { Button } from "@/components/cubix/button"
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
} from "@/components/cubix/dropdown-menu"

Example

<DropdownMenu>
  <DropdownMenuTrigger render={<Button variant="outline" />}>
Open
</DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuGroup>
      <DropdownMenuLabel>My Account</DropdownMenuLabel>
      <DropdownMenuItem>Profile</DropdownMenuItem>
      <DropdownMenuItem>Billing</DropdownMenuItem>
    </DropdownMenuGroup>
    <DropdownMenuSeparator />
    <DropdownMenuGroup>
      <DropdownMenuItem>Team</DropdownMenuItem>
      <DropdownMenuItem>Subscription</DropdownMenuItem>
    </DropdownMenuGroup>
  </DropdownMenuContent>
</DropdownMenu>

Composition

Use the following composition to build a DropdownMenu:

Composition

DropdownMenu
├── DropdownMenuTrigger
└── DropdownMenuContent
    ├── DropdownMenuGroup
    │   ├── DropdownMenuLabel
    │   ├── DropdownMenuItem
    │   └── DropdownMenuItem
    ├── DropdownMenuSeparator
    ├── DropdownMenuGroup
    │   ├── DropdownMenuLabel
    │   ├── DropdownMenuCheckboxItem
    │   └── DropdownMenuCheckboxItem
    ├── DropdownMenuSeparator
    ├── DropdownMenuGroup
    │   ├── DropdownMenuLabel
    │   └── DropdownMenuRadioGroup
    │       ├── DropdownMenuRadioItem
    │       └── DropdownMenuRadioItem
    └── DropdownMenuSub
        ├── DropdownMenuSubTrigger
        └── DropdownMenuSubContent
            └── DropdownMenuGroup
                ├── DropdownMenuLabel
                ├── DropdownMenuItem
                └── DropdownMenuItem

Examples

Basic

A basic dropdown menu with labels and separators.

Open

<DropdownMenu>
  <DropdownMenuTrigger render={<Button variant="outline" />}>
Open
</DropdownMenuTrigger>
  <DropdownMenuContent className="w-56">
    <DropdownMenuGroup>
      <DropdownMenuLabel>My Account</DropdownMenuLabel>
      <DropdownMenuItem>Profile</DropdownMenuItem>
      <DropdownMenuItem>Billing</DropdownMenuItem>
      <DropdownMenuItem>Settings</DropdownMenuItem>
    </DropdownMenuGroup>
    <DropdownMenuSeparator />
    <DropdownMenuGroup>
      <DropdownMenuItem>GitHub</DropdownMenuItem>
      <DropdownMenuItem>Support</DropdownMenuItem>
      <DropdownMenuItem>API</DropdownMenuItem>
    </DropdownMenuGroup>
  </DropdownMenuContent>
</DropdownMenu>

Submenu

Use DropdownMenuSub to nest secondary actions.

Open

<DropdownMenuSub>
  <DropdownMenuSubTrigger>Invite users</DropdownMenuSubTrigger>
  <DropdownMenuSubContent>
    <DropdownMenuItem>Email</DropdownMenuItem>
    <DropdownMenuItem>Message</DropdownMenuItem>
    <DropdownMenuItem>More...</DropdownMenuItem>
  </DropdownMenuSubContent>
</DropdownMenuSub>

Shortcuts

Add DropdownMenuShortcut to show keyboard hints.

Open

<DropdownMenuItem>
  Profile
  <DropdownMenuShortcut>⇧⌘P</DropdownMenuShortcut>
</DropdownMenuItem>

Icons

Combine icons with labels for quick scanning.

Open

<DropdownMenuItem>
  <UserIcon />
  Profile
</DropdownMenuItem>

Checkboxes

Use DropdownMenuCheckboxItem for toggles.

Open

<DropdownMenuCheckboxItem
  checked={statusBar}
  onCheckedChange={setStatusBar}
>
  Status Bar
</DropdownMenuCheckboxItem>

Checkboxes Icons

Add icons to checkbox items.

Open

<DropdownMenuCheckboxItem
  checked={notifications.email}
  onCheckedChange={setEmail}
>
  <MailIcon />
  Email notifications
</DropdownMenuCheckboxItem>

Radio Group

Use DropdownMenuRadioGroup for exclusive choices.

Open

<DropdownMenuRadioGroup value={position} onValueChange={setPosition}>
  <DropdownMenuRadioItem value="top">Top</DropdownMenuRadioItem>
  <DropdownMenuRadioItem value="bottom">Bottom</DropdownMenuRadioItem>
  <DropdownMenuRadioItem value="right">Right</DropdownMenuRadioItem>
</DropdownMenuRadioGroup>

Radio Icons

Show radio options with icons.

Open

<DropdownMenuRadioItem value="card">
  <CreditCardIcon />
  Credit Card
</DropdownMenuRadioItem>

Destructive

Use variant="destructive" for irreversible actions.

Open

<DropdownMenuItem variant="destructive">
  <Trash2Icon />
  Delete
</DropdownMenuItem>

Avatar

An account switcher dropdown triggered by an avatar.

<DropdownMenuTrigger render={<Button variant="ghost" size="icon" className="rounded-full" />}>
CN
</DropdownMenuTrigger>

Complex

A richer example combining groups, icons, and submenus.

Open

<DropdownMenu>
  <DropdownMenuTrigger render={<Button variant="outline" />}>
Open
</DropdownMenuTrigger>
  <DropdownMenuContent className="w-56">
    <DropdownMenuLabel>My Account</DropdownMenuLabel>
    <DropdownMenuItem>Profile</DropdownMenuItem>
    <DropdownMenuCheckboxItem>Sidebar</DropdownMenuCheckboxItem>
    <DropdownMenuSub>
      <DropdownMenuSubTrigger>Invite Users</DropdownMenuSubTrigger>
      <DropdownMenuSubContent>
        <DropdownMenuItem>Email</DropdownMenuItem>
      </DropdownMenuSubContent>
    </DropdownMenuSub>
  </DropdownMenuContent>
</DropdownMenu>

RTL

Wrap the menu in a RTL container to mirror layout and chevrons.

<div dir="rtl">
  <DropdownMenu>
    <DropdownMenuTrigger render={<Button variant="outline" />}>
باز کردن
</DropdownMenuTrigger>
    <DropdownMenuContent className="w-56">
      <DropdownMenuItem>پروفایل</DropdownMenuItem>
      <DropdownMenuItem>تنظیمات</DropdownMenuItem>
    </DropdownMenuContent>
  </DropdownMenu>
</div>

API Reference

Note: The menu is not modal. Escape, Tab, and clicking outside close it, and focus returns to the trigger. Use arrow keys to move between items.

DropdownMenu

The container that wraps the trigger and content and manages open state.

Prop	Type	Default	Description
open	boolean	-	Controlled open state. Omit to use uncontrolled mode.
defaultOpen	boolean	false	Initial open state when uncontrolled.
onOpenChange	(open: boolean) => void	-	Called when the open state changes.
children	React.ReactNode	-	The trigger, content, and nested menu parts.

DropdownMenuTrigger

The element that opens the menu. Use render to merge onto a Button.

Prop	Type	Default	Description
render	React.ReactElement	-	Render the trigger as another element (e.g. a Button).
className	string	-	Additional Tailwind classes merged with the component styles (last one wins).

DropdownMenuContent

The menu panel rendered in a portal next to the trigger.

Prop	Type	Default	Description
side	"top" \| "right" \| "bottom" \| "left"	"bottom"	Preferred side of the trigger to render the menu on.
align	"start" \| "center" \| "end"	"start"	Alignment along the opposite axis of `side`.
sideOffset	number	4	Distance in pixels between the trigger and the menu.
alignOffset	number	0	Offset in pixels along the alignment axis.
className	string	-	Additional Tailwind classes merged with the component styles (last one wins).
...props	React.ComponentProps<'div'>	-	All native div attributes are forwarded to the menu panel.

DropdownMenuItem

An action inside the menu. Selecting it closes the menu.

Prop	Type	Default	Description
inset	boolean	-	Indent the item to align with items that have a leading icon.
variant	"default" \| "destructive"	"default"	Visual treatment. Use destructive for irreversible actions.
disabled	boolean	-	Prevents selection and removes the item from keyboard flow.
onSelect	(event: Event) => void	-	Called when the item is chosen. The menu closes afterwards.

DropdownMenuCheckboxItem

A checkable item. The menu stays open after toggling.

Prop	Type	Default	Description
checked	boolean	-	Controlled checked state.
defaultChecked	boolean	-	Initial checked state when uncontrolled.
onCheckedChange	(checked: boolean) => void	-	Called when the checked state changes. The menu stays open.
disabled	boolean	-	Prevents toggling the item.

DropdownMenuRadioGroup

A set of mutually exclusive items. The menu stays open after a change.

Prop	Type	Default	Description
value	string	-	Controlled selected value.
defaultValue	string	-	Initial selected value when uncontrolled.
onValueChange	(value: string) => void	-	Called when a radio item is selected. The menu stays open.

DropdownMenuRadioItem

One option inside a radio group. value is required.

Prop	Type	Default	Description
value	string	-	The unique value represented by this radio item.
disabled	boolean	-	Prevents selecting the item.