Dropdown Menu

Installation

The component is exported from @by/experience-system. Add the package with your package manager:

pnpm add @by/experience-system

In this monorepo, depend on the workspace package (for example via workspace:* or your catalog) so imports resolve to packages/experience-system.

Composition

Use the following composition to build a DropdownMenu:

DropdownMenu
├── DropdownMenuTrigger
└── DropdownMenuContent
    ├── DropdownMenuLabel (optional)
    ├── DropdownMenuItem / CheckboxItem / RadioGroup / …
    ├── DropdownMenuSeparator (optional)
    └── DropdownMenuSub (optional)
        ├── DropdownMenuSubTrigger
        └── DropdownMenuSubContent

DropdownMenuTrigger is usually a Button (with asChild). Commands and groups live in DropdownMenuContent. Use DropdownMenuSub for nested menus. Behavior follows Radix UI Dropdown Menu.

Usage

import {
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuItem,
  Button,
} from '@by/experience-system';

DropdownMenu and its parts are client components ('use client'). Use them inside a Client Component or a dynamic import when using the Next.js App Router.

<DropdownMenu>
  <DropdownMenuTrigger asChild>
    <Button variant="outline">Open menu</Button>
  </DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuItem>Profile</DropdownMenuItem>
    <DropdownMenuItem>Settings</DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>

When to use

• When secondary actions should stay one click away but not compete with primary UI on the page.
• When grouping related commands (edit, share, delete) or settings toggles (checkboxes, radio groups) in a compact surface.

When not to use

• When the only action is primary navigation—prefer visible links or tabs.
• When the list grows so long that scanning becomes difficult—consider a dialog, drawer, or dedicated settings page.

Examples

The live preview at the top of this page uses dropdown-menu-usage (outline button trigger + two items).

Complex content

Items with leading icons, inset alignment for icon-less rows, shortcuts, a nested submenu (including an error-styled row via color="error"), checkbox items, and a radio group with an inset label.

API Reference

Subsection titles name @by/experience-system exports and the Radix part they wrap. Pieces map to Radix UI Dropdown Menu primitives. Styling, density-aware spacing, and icons are provided by @by/experience-system and @by/icons. The menu follows the Menu WAI-ARIA design pattern and uses roving tabindex to move focus among items.

DropdownMenu

Root. DropdownMenu contains all the parts of a dropdown menu. Exported as DropdownMenu; forwards DropdownMenu.Root props from radix-ui. dir defaults from ThemeProvider and can be overridden via props.

DropdownMenuTrigger

DropdownMenuTrigger — the control that toggles the menu. Use asChild to merge props into a Button or other focusable element.

DropdownMenuPortal

DropdownMenuPortal — portals children into the document. In this experience system, container defaults to the element from useContainerElement() (ThemeProvider) instead of document.body.

DropdownMenuContent

DropdownMenuContent — the surface that opens from the trigger. This export wraps Portal with the Experience System container so you typically render DropdownMenuContent directly (without a separate DropdownMenuPortal for the main menu).

DropdownMenuItem

DropdownMenuItem — a selectable command in the menu.

DropdownMenuGroup

DropdownMenuGroup — groups multiple items for semantics and optional labeling.

DropdownMenuLabel

DropdownMenuLabel — a non-focusable label for a section. Optional inset aligns with inset items.

DropdownMenuCheckboxItem

DropdownMenuCheckboxItem — a toggle row backed by a checkbox. Uses a Check indicator internally.

DropdownMenuRadioGroup

DropdownMenuRadioGroup — groups DropdownMenuRadioItem components.

DropdownMenuRadioItem

DropdownMenuRadioItem — a single choice in a radio group. Indicator uses ShapeBulletCircleFill.

DropdownMenuSeparator

DropdownMenuSeparator — a visual divider between groups.

DropdownMenuShortcut

DropdownMenuShortcut — Experience System helper: a span for keyboard hints, aligned to the trailing edge when placed inside an item. Not a Radix primitive part.

DropdownMenuSub

DropdownMenuSub — contains all parts of a submenu.

DropdownMenuSubTrigger

DropdownMenuSubTrigger — opens a nested menu. Includes a trailing ArrowChevronRight icon.

DropdownMenuSubContent

DropdownMenuSubContent — the panel for a submenu. Render inside DropdownMenuSub.

@by/experience-system does not export DropdownMenuArrow; DropdownMenuSubTrigger includes a trailing chevron instead. For Radix’s optional arrow API, see the upstream docs.

Accessibility

Uses roving tabindex among items. Prefer DropdownMenuLabel (optionally inset) for section titles, and give icon-only triggers an accessible name (aria-label on the button).

Keyboard interactions

For the full primitive reference and upstream updates, see Radix UI — Dropdown Menu.

Implementation: packages/experience-system/src/components/DropdownMenu/DropdownMenu.tsx. Codegen-oriented rules for AI agents: packages/experience-system/src/components/DropdownMenu/DropdownMenu.instructions.md.