Dropdown Menu

A list of actions and options that opens from a button.

import * as stylex from "@stylexjs/stylex"
import { Button } from "@/components/ui/button"
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuSeparator,
  DropdownMenuShortcut,
  DropdownMenuSub,
  DropdownMenuSubContent,
  DropdownMenuSubTrigger,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu"

const styles = stylex.create({
  menu: { minWidth: "10rem" },
})

export default function DropdownMenuDemo() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline" />}>Open</DropdownMenuTrigger>
      <DropdownMenuContent xstyle={styles.menu}>
        <DropdownMenuGroup>
          <DropdownMenuLabel>Workspace</DropdownMenuLabel>
          <DropdownMenuItem>
            Members
            <DropdownMenuShortcut>⇧⌘M</DropdownMenuShortcut>
          </DropdownMenuItem>
          <DropdownMenuItem>
            Usage
            <DropdownMenuShortcut>⌘U</DropdownMenuShortcut>
          </DropdownMenuItem>
          <DropdownMenuItem>
            Preferences
            <DropdownMenuShortcut>⌘,</DropdownMenuShortcut>
          </DropdownMenuItem>
        </DropdownMenuGroup>
        <DropdownMenuSeparator />
        <DropdownMenuGroup>
          <DropdownMenuItem>Projects</DropdownMenuItem>
          <DropdownMenuSub>
            <DropdownMenuSubTrigger>Invite people</DropdownMenuSubTrigger>
            <DropdownMenuSubContent>
              <DropdownMenuItem>By email</DropdownMenuItem>
              <DropdownMenuItem>By link</DropdownMenuItem>
              <DropdownMenuSeparator />
              <DropdownMenuItem>Manage access...</DropdownMenuItem>
            </DropdownMenuSubContent>
          </DropdownMenuSub>
          <DropdownMenuItem>
            New Project
            <DropdownMenuShortcut>⌘N</DropdownMenuShortcut>
          </DropdownMenuItem>
        </DropdownMenuGroup>
        <DropdownMenuSeparator />
        <DropdownMenuGroup>
          <DropdownMenuItem>Documentation</DropdownMenuItem>
          <DropdownMenuItem>Feedback</DropdownMenuItem>
          <DropdownMenuItem disabled>Changelog</DropdownMenuItem>
        </DropdownMenuGroup>
        <DropdownMenuSeparator />
        <DropdownMenuItem>
          Sign out
          <DropdownMenuShortcut>⇧⌘Q</DropdownMenuShortcut>
        </DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}

Installation

pnpm dlx shadcn@latest add @arene/dropdown-menu

Needs the arene setup first.

Usage

import { Button } from "@/components/ui/button"
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu"
<DropdownMenu>
  <DropdownMenuTrigger render={<Button variant="outline" />}>Open</DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuGroup>
      <DropdownMenuLabel>Workspace</DropdownMenuLabel>
      <DropdownMenuItem>Members</DropdownMenuItem>
      <DropdownMenuItem>Usage</DropdownMenuItem>
    </DropdownMenuGroup>
    <DropdownMenuSeparator />
    <DropdownMenuItem>Sign out</DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>

Pass the trigger element through render. Base UI merges aria-haspopup and aria-expanded into it and the Button keeps its styles.

Basic

Use DropdownMenuLabel to name a group and DropdownMenuSeparator to divide groups.

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

export default function DropdownMenuBasic() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline" />}>Open</DropdownMenuTrigger>
      <DropdownMenuContent>
        <DropdownMenuGroup>
          <DropdownMenuLabel>Workspace</DropdownMenuLabel>
          <DropdownMenuItem>Members</DropdownMenuItem>
          <DropdownMenuItem>Usage</DropdownMenuItem>
          <DropdownMenuItem>Preferences</DropdownMenuItem>
        </DropdownMenuGroup>
        <DropdownMenuSeparator />
        <DropdownMenuItem>Documentation</DropdownMenuItem>
        <DropdownMenuItem>Feedback</DropdownMenuItem>
        <DropdownMenuItem disabled>Changelog</DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}

Nest secondary actions in a DropdownMenuSub.

import { Button } from "@/components/ui/button"
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuSeparator,
  DropdownMenuSub,
  DropdownMenuSubContent,
  DropdownMenuSubTrigger,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu"

export default function DropdownMenuSubmenu() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline" />}>Open</DropdownMenuTrigger>
      <DropdownMenuContent>
        <DropdownMenuItem>Projects</DropdownMenuItem>
        <DropdownMenuSub>
          <DropdownMenuSubTrigger>Invite people</DropdownMenuSubTrigger>
          <DropdownMenuSubContent>
            <DropdownMenuItem>By email</DropdownMenuItem>
            <DropdownMenuItem>By link</DropdownMenuItem>
            <DropdownMenuSub>
              <DropdownMenuSubTrigger>Import</DropdownMenuSubTrigger>
              <DropdownMenuSubContent>
                <DropdownMenuItem>From CSV</DropdownMenuItem>
                <DropdownMenuItem>From directory</DropdownMenuItem>
                <DropdownMenuSeparator />
                <DropdownMenuItem>From API</DropdownMenuItem>
              </DropdownMenuSubContent>
            </DropdownMenuSub>
            <DropdownMenuSeparator />
            <DropdownMenuItem>Manage access...</DropdownMenuItem>
          </DropdownMenuSubContent>
        </DropdownMenuSub>
        <DropdownMenuItem>New Project</DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}

Shortcuts

Use DropdownMenuShortcut to show a key combination at the trailing edge of an item. It displays the key only. Wire the binding yourself.

import * as stylex from "@stylexjs/stylex"
import { Button } from "@/components/ui/button"
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuSeparator,
  DropdownMenuShortcut,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu"

const styles = stylex.create({
  menu: { minWidth: "10rem" },
})

export default function DropdownMenuShortcuts() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline" />}>Open</DropdownMenuTrigger>
      <DropdownMenuContent xstyle={styles.menu}>
        <DropdownMenuGroup>
          <DropdownMenuLabel>Workspace</DropdownMenuLabel>
          <DropdownMenuItem>
            Members
            <DropdownMenuShortcut>⇧⌘M</DropdownMenuShortcut>
          </DropdownMenuItem>
          <DropdownMenuItem>
            Usage
            <DropdownMenuShortcut>⌘U</DropdownMenuShortcut>
          </DropdownMenuItem>
          <DropdownMenuItem>
            Preferences
            <DropdownMenuShortcut>⌘,</DropdownMenuShortcut>
          </DropdownMenuItem>
        </DropdownMenuGroup>
        <DropdownMenuSeparator />
        <DropdownMenuItem>
          Sign out
          <DropdownMenuShortcut>⇧⌘Q</DropdownMenuShortcut>
        </DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}

Icons

Place an icon before the label. The item sizes it.

import { Button } from "@/components/ui/button"
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu"
import { ChartBarIcon } from "@phosphor-icons/react/dist/csr/ChartBar"
import { SignOutIcon } from "@phosphor-icons/react/dist/csr/SignOut"
import { GearIcon } from "@phosphor-icons/react/dist/csr/Gear"
import { UsersIcon } from "@phosphor-icons/react/dist/csr/Users"

export default function DropdownMenuIcons() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline" />}>Open</DropdownMenuTrigger>
      <DropdownMenuContent>
        <DropdownMenuItem>
          <UsersIcon aria-hidden="true" />
          Members
        </DropdownMenuItem>
        <DropdownMenuItem>
          <ChartBarIcon aria-hidden="true" />
          Usage
        </DropdownMenuItem>
        <DropdownMenuItem>
          <GearIcon aria-hidden="true" />
          Preferences
        </DropdownMenuItem>
        <DropdownMenuSeparator />
        <DropdownMenuItem variant="destructive">
          <SignOutIcon aria-hidden="true" />
          Sign out
        </DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}

Checkboxes

Use DropdownMenuCheckboxItem for items that toggle. Pass checked and onCheckedChange to control it, or defaultChecked to leave it uncontrolled.

import * as stylex from "@stylexjs/stylex"
import { Button } from "@/components/ui/button"
import {
  DropdownMenu,
  DropdownMenuCheckboxItem,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuLabel,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu"

const styles = stylex.create({
  menu: { minWidth: "10rem" },
})

export default function DropdownMenuCheckboxes() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline" />}>Open</DropdownMenuTrigger>
      <DropdownMenuContent xstyle={styles.menu}>
        <DropdownMenuGroup>
          <DropdownMenuLabel>View</DropdownMenuLabel>
          <DropdownMenuCheckboxItem defaultChecked>Ruler</DropdownMenuCheckboxItem>
          <DropdownMenuCheckboxItem disabled>Outline</DropdownMenuCheckboxItem>
          <DropdownMenuCheckboxItem>Word Count</DropdownMenuCheckboxItem>
        </DropdownMenuGroup>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}

Radio group

Use DropdownMenuRadioGroup to hold one value across its DropdownMenuRadioItems. Pass value and onValueChange, or defaultValue.

import { Button } from "@/components/ui/button"
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuLabel,
  DropdownMenuRadioGroup,
  DropdownMenuRadioItem,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu"

export default function DropdownMenuRadioGroupDemo() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline" />}>Open</DropdownMenuTrigger>
      <DropdownMenuContent>
        <DropdownMenuGroup>
          <DropdownMenuLabel>Sort by</DropdownMenuLabel>
          <DropdownMenuRadioGroup defaultValue="modified">
            <DropdownMenuRadioItem value="name">Name</DropdownMenuRadioItem>
            <DropdownMenuRadioItem value="modified">Last Modified</DropdownMenuRadioItem>
            <DropdownMenuRadioItem value="size">Size</DropdownMenuRadioItem>
          </DropdownMenuRadioGroup>
        </DropdownMenuGroup>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}

Destructive

Set variant="destructive" on an item to colour it and its icon.

import { Button } from "@/components/ui/button"
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu"
import { PencilSimpleIcon } from "@phosphor-icons/react/dist/csr/PencilSimple"
import { ShareNetworkIcon } from "@phosphor-icons/react/dist/csr/ShareNetwork"
import { TrashIcon } from "@phosphor-icons/react/dist/csr/Trash"

export default function DropdownMenuDestructive() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline" />}>Actions</DropdownMenuTrigger>
      <DropdownMenuContent>
        <DropdownMenuGroup>
          <DropdownMenuItem>
            <PencilSimpleIcon aria-hidden="true" />
            Edit
          </DropdownMenuItem>
          <DropdownMenuItem>
            <ShareNetworkIcon aria-hidden="true" />
            Share
          </DropdownMenuItem>
        </DropdownMenuGroup>
        <DropdownMenuSeparator />
        <DropdownMenuItem variant="destructive">
          <TrashIcon aria-hidden="true" />
          Delete
        </DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}

API reference

Pass render to replace a part's element or compose it with another component.

Every part wraps the Base UI Menu part of the same name and accepts its props. See the Base UI reference for the full list. Each styled part also takes xstyle and className. The items and DropdownMenuSubTrigger also take style, which is real inline CSS merged over the style their Base UI state resolves to.

PropTypeDefault
side"top" | "bottom" | "left" | "right" | "inline-start" | "inline-end""bottom"
sideOffsetnumber4
align"start" | "center" | "end""start"
alignOffsetnumber0

The popup is at least as wide as its trigger and never narrower than 8rem. Set a wider floor through xstyle.

The same props, with side="right", sideOffset={0} and alignOffset={-3} as defaults.

PropTypeDefault
variant"default" | "destructive""default"
insetboolean—
disabledboolean—

inset pads the leading edge by the width of an indicator column, so a plain item lines up with checkbox and radio items beside it. DropdownMenuLabel, DropdownMenuSubTrigger, DropdownMenuCheckboxItem and DropdownMenuRadioItem take inset too.

An item that navigates. It wraps Base UI's Menu.LinkItem and renders an <a>, styled like DropdownMenuItem. Use it for links instead of giving an item render={<a />}.

PropTypeDefault
hrefstring—
closeOnClickbooleanfalse
insetboolean—

The menu stays open on click, since a navigation usually unmounts it. Set closeOnClick on a link that opens a new tab or another app.

PropTypeDefault
checkedboolean—
defaultCheckedboolean—
onCheckedChange(checked: boolean) => void—
PropTypeDefault
valuestring—
defaultValuestring—
onValueChange(value: string) => void—

Data attributes

AttributeOnEffect
data-slot="dropdown-menu-content"the popupPopup surface
data-side, data-alignthe popupBase UI writes them. data-side picks the slide direction
data-starting-style, data-ending-stylethe popupBase UI writes them while the popup animates in or out
data-slot="dropdown-menu-item"an itemTargets items from a parent
data-slot="dropdown-menu-link-item"a linkTargets link items from a parent
data-variantan itemReflects the variant prop
data-insetan itemPresent when inset is set
data-highlighted, data-disabledan itemBase UI writes them