Dropdown Menu

Non-modal action menu on the shared anchored-overlay runtime, with items, checkbox items, and radio groups.

Identity

Category: Overlays & feedback
Status: stable public Registry/export-map component family
Targets: iOS · Android · Web, subject to the compatibility contract
Prerequisites: @beemvp/beeui-ui installed (or this component’s source copied via the Registry CLI below) and, on Web, the BeeUI Tailwind/Uniwind theme CSS loaded — see Start for full platform setup.
Source: packages/ui/src/components/dropdown-menu.tsx

Import

import { DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuItem, DropdownMenuLabel, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuTrigger } from '@beemvp/beeui-ui';

There is no documented deep/private source import. For source ownership from a BeeUI checkout:

pnpm beeui add dropdown-menu

Registry (used throughout this page) is BeeUI’s source-ownership manifest — registry/registry.json — that the pnpm beeui/@beemvp/beeui-cli CLI reads to copy a component’s real source into your app and rewrite its internal imports; it is not an npm package index. This component’s own Registry entry: registry/registry.json.

Composition and public API

Family exports: DropdownMenu DropdownMenuCheckboxItem DropdownMenuContent DropdownMenuItem DropdownMenuLabel DropdownMenuRadioGroup DropdownMenuRadioItem DropdownMenuSeparator DropdownMenuTrigger
- Also routed here, outside the Registry family:
  - dropdown-menu
- Package export subpath: @beemvp/beeui-ui/dropdown-menu

Exported types: DropdownMenuAlign, DropdownMenuCheckboxItemProps, DropdownMenuCollisionPadding, DropdownMenuContentProps, DropdownMenuDirection, DropdownMenuItemProps, DropdownMenuLabelProps, DropdownMenuPlacement, DropdownMenuProps, DropdownMenuRadioGroupProps, DropdownMenuRadioItemProps, DropdownMenuSeparatorProps, DropdownMenuTriggerProps

The generated API inventory is mechanically joined to packages/ui/src/index.ts, Registry metadata, and the component reference contract. Each type’s field table below is parsed directly from that source, not a second hand-maintained copy; for the fuller behavior narrative see the canonical component behavior catalog.

State and behavior contract

Controlled/uncontrolled (open/onOpenChange/defaultOpen) non-modal menu; DropdownMenuItem’s onSelect closes the menu by default after the handler runs, DropdownMenuCheckboxItem stays open by default, and DropdownMenuRadioGroup fails safe by disabling every item that shares a duplicate value. DropdownMenuItem accepts an optional description — a muted secondary line rendered below the primary content, mirroring ListItem’s own description — but only for single-line, plain-text/number children; a custom element children ignores it.

Props

`DropdownMenuCheckboxItemProps`

Prop	Type	Default	Description
`checked` (required)	`boolean`	—	Whether this checkbox item is checked; renders a checkmark. Always controlled by the caller.
`closeOnSelect`	`boolean`	`false`	Closes the menu after this item is toggled. Defaults to false, unlike `DropdownMenuItem`, since checking multiple items in one open menu is a common flow.
`onCheckedChange`	`(checked: boolean) => void`	—	Called with the next checked state when this item is activated. Required for enabled items in dev mode (logs a warning otherwise).

Also carries every prop of Omit<DropdownMenuItemBaseProps, 'closeOnSelect' | 'onSelect'> — that upstream contract is not reproduced here.

`DropdownMenuContentProps`

Prop	Type	Default	Description
`align`	`DropdownMenuAlign`	`'start'`	Where the overlay sits along the anchor’s cross axis — `'start'`, `'center'` or `'end'`. The anchored-overlay kernel may flip it when the preferred placement would collide with the viewport.
`alignOffset`	`number`	`0`	Pixels to shift the overlay along the alignment axis, after `align` is resolved.
`avoidKeyboard`	`boolean`	`false`	Whether the overlay repositions to stay clear of the on-screen keyboard.
`avoidSafeArea`	`boolean`	`true`	Whether the overlay keeps clear of the platform safe-area insets — notches, home indicators and status bars.
`closeOnOutsidePress`	`boolean`	`true`	Whether a press outside the overlay dismisses it.
`collisionPadding`	`DropdownMenuCollisionPadding`	`8`	Minimum distance to keep from the viewport edges when the kernel repositions or flips the overlay. A number applies to every edge; an object sets edges individually.
`direction`	`DropdownMenuDirection`	—	Logical direction used to resolve `align`/`placement` for RTL layouts. Defaults to the app’s resolved layout direction.
`flip`	`boolean`	`true`	Flips `placement` to the opposite side of the trigger when there is not enough room. Defaults to true.
`outsidePressProps`	`Omit<PressableProps, 'children' \| 'onPress' \| 'style'>`	—	Forwarded to the outside-press dismiss layer, excluding `children`/`onPress`/`style`, which this component owns.
`outsidePressTestID`	`string`	—	`testID` applied to the outside-press dismiss layer, for targeting it in tests.
`placement`	`DropdownMenuPlacement`	`'bottom'`	Which side of the trigger the menu opens on. Defaults to `'bottom'`.
`shift`	`boolean`	`true`	Shifts the menu along the trigger’s edge to stay within the viewport instead of overflowing. Defaults to true.
`sideOffset`	`number`	`8`	Pixels of gap between the anchor and the overlay, along the placement side.

Also carries every prop of Omit<ViewProps, 'role'> — that upstream contract is not reproduced here.

`DropdownMenuItemProps`

DropdownMenuItemProps is exactly DropdownMenuItemBaseProps.

Prop	Type	Default	Description
`children`	`React.ReactNode`	—	Content rendered inside this element. The family’s composition section states which children it expects.
`className`	`string`	—	Extra utility classes, merged after the component’s own via `cn(...)`, so they win on conflict. An escape hatch for source-owned and application work, not a cross-engine portability guarantee.
`closeOnSelect`	`boolean`	`true`	Closes the menu after this item is activated (pressed or selected via keyboard). Defaults to true.
`description`	`React.ReactNode`	—	Muted secondary line rendered below the primary content (e.g. an address under a store name), mirroring `ListItem`’s `description`. Ignored for custom element `children` (single-line items only).
`descriptionClassName`	`string`	—	Applied to the `description` `Text` when it is a plain string or number; ignored for custom element `description`.
`onPress`	`PressableProps['onPress']`	—	Called on press, before `onSelect` and `closeOnSelect` run.
`onSelect`	`() => void`	—	Called when this item is activated (pressed or selected via keyboard), before `closeOnSelect` runs.
`textClassName`	`string`	—	Applied to string/number children, which are wrapped in a `Text`; ignored for custom element children.

Also carries every prop of Omit<PressableProps, 'accessibilityRole' | 'children' | 'onPress' | 'role'> — that upstream contract is not reproduced here.

`DropdownMenuLabelProps`

This type adds no fields of its own. These are the props the implementation reads from the base type below; everything else is passed straight through.

Prop	Default
`className`	—

Also carries every prop of Omit<TextProps, 'role' | 'variant'> — documented on the Text page, not reproduced here.

`DropdownMenuProps`

one of the following mutually exclusive variants:

Variant DropdownMenuControlledProps:

Prop	Type	Default	Description
`children`	`React.ReactNode`	—	Content rendered inside this element. The family’s composition section states which children it expects.
`defaultOpen`	`never`	`false`	Not accepted in the controlled variant, where `open` already owns the state. Pass `defaultOpen` on its own, without `open`, to use the uncontrolled variant.
`onOpenChange` (required)	`(open: boolean) => void`	—	Applies a requested open state, and is required here because the controlled variant never updates its own visibility. If this does not change `open`, nothing does.
`open` (required)	`boolean`	—	Current open state, owned by the caller; supplying a defined value alongside `onOpenChange` is what selects the controlled variant. Passing `open` without an `onOpenChange` function warns in development and falls back to uncontrolled behavior.

Variant DropdownMenuUncontrolledProps:

Prop	Type	Default	Description
`children`	`React.ReactNode`	—	Content rendered inside this element. The family’s composition section states which children it expects.
`defaultOpen`	`boolean`	`false`	Open state to start from, read once when the component mounts, so later changes to it are ignored. Defaults to false; drive visibility with `open` + `onOpenChange` instead when it needs to change.
`onOpenChange`	`(open: boolean) => void`	—	Notified after the open state changes, and optional here because the uncontrolled variant updates its own state either way.
`open`	`undefined`	—	Must be left undefined in the uncontrolled variant, because a defined `open` together with `onOpenChange` selects the controlled variant instead.

`DropdownMenuRadioGroupProps`

Prop	Type	Default	Description
`onValueChange`	`(value: string) => void`	—	Called with the selected `DropdownMenuRadioItem`’s `value` when the selection changes. Required whenever `value` is set (logs a dev warning otherwise).
`value`	`string`	—	The `value` of the currently selected `DropdownMenuRadioItem` among this group’s children.

Also carries every prop of Omit<ViewProps, 'role'> — that upstream contract is not reproduced here.

`DropdownMenuRadioItemProps`

Prop	Type	Default	Description
`closeOnSelect`	`boolean`	`false`	Closes the menu after this item is selected. Defaults to false, matching `DropdownMenuCheckboxItem`’s convention.
`value` (required)	`string`	—	Identifies this item within its parent `DropdownMenuRadioGroup`. A value duplicated by another item in the same group is disabled with a dev-mode warning.

Also carries every prop of Omit<DropdownMenuItemBaseProps, 'closeOnSelect' | 'onSelect'> — that upstream contract is not reproduced here.

`DropdownMenuSeparatorProps`

This type adds no fields of its own. These are the props the implementation reads from the base type below; everything else is passed straight through.

Prop	Default
`className`	—

Also carries every prop of Omit<ViewProps, 'role'> — that upstream contract is not reproduced here.

`DropdownMenuTriggerProps`

DropdownMenuTriggerProps is exactly ButtonProps.

Prop	Type	Default	Description
`children`	`React.ReactNode`	—	Content rendered inside this element. The family’s composition section states which children it expects.
`className`	`string`	—	Extra utility classes, merged after the component’s own via `cn(...)`, so they win on conflict. An escape hatch for source-owned and application work, not a cross-engine portability guarantee.
`labelClassName`	`string`	—	Extra utility classes for the label text specifically, merged after the component’s own.
`loading`	`boolean`	`false`	Shows a spinner in place of the label, sets `aria-busy`, and disables presses. Defaults to false.
`size`	`'sm' \| 'md' \| 'lg' \| 'icon'`	`'md'`	Chooses this element’s `size` from `buttonVariants`’s presets, declared in `packages/ui/src/components/button.tsx` — the classes each value applies are there.
`variant`	`'primary' \| 'secondary' \| 'outline' \| 'ghost' \| 'destructive'`	`'primary'`	Chooses this element’s `variant` from `buttonVariants`’s presets, declared in `packages/ui/src/components/button.tsx` — the classes each value applies are there.

Also carries every prop of Omit<PressableProps, 'accessibilityRole' | 'role' | 'children'> — that upstream contract is not reproduced here.

This is the pressable itself — the same variant/size/press API as Button — so icon/label children go directly inside it. Do not nest a second pressable (an icon button, or an avatar wrapped for press) inside a *Trigger: on Web that renders one interactive element inside another, which React flags as invalid DOM nesting. For an icon-only or avatar trigger, set variant="ghost" (and size/className as needed) on the trigger itself instead of wrapping a second pressable.

Related exported types:

DropdownMenuAlign — alias of AnchoredOverlayAlign.
DropdownMenuCollisionPadding — alias of AnchoredOverlayCollisionPadding.
DropdownMenuDirection — alias of AnchoredOverlayDirection.
DropdownMenuPlacement — alias of AnchoredOverlayPlacement.

The executable fixtures below are the source-grounded usage examples; consumers should not infer state ownership from DOM structure or another UI library.

Provider and dependencies

BeeUIProvider is required above this family because it participates in shared overlay/toast runtime infrastructure.
Peer/native dependencies visible to this Registry item: react, react-native
Registry dependency closure: button, core-overlay, overlay-runtime, text, theme, use-direction
Safe-area ownership remains explicit: shell surfaces touching system edges opt into SafeArea; components do not silently invent app-shell insets.
Web consumers load the BeeUI semantic theme CSS as documented in Web onboarding.

Platform behavior

This family ships no platform-specific file, but its source branches on Platform, so some behavior differs by target.

The same public family is exposed across the supported target matrix; meaningful platform differences remain governed by the compatibility contract.

Evidence classes are not equal and this page does not blur them: Web behavior is exercised in a real browser, while iOS and Android carry package/export and native-compile evidence, which is not device-runtime proof. The compatibility contract records which class each claim rests on.

Accessibility

Roles this family assigns: menu, menuitem, radiogroup — set in dropdown-menu.tsx by the components themselves, not by the caller.
Accessibility states and properties it sets: accessibilityElementsHidden, accessible, checked, controls, disabled, expanded, haspopup, hidden — read from dropdown-menu.tsx.

Keyboard/focus behavior, announcements, Dynamic Type/Web zoom, RTL and reduced-motion expectations are not derived here — see Accessibility overview, Keyboard & focus, RTL/localization and Large text & zoom. BeeUI does not claim universal accessibility certification from automated tests.

Styling and theming

Style axes: tone (8 values, inherited from TextProps), size (4 values), variant (5 values).
Class-name surfaces: className, descriptionClassName, labelClassName, textClassName.

Colors, spacing and typography come from semantic tokens rather than from values written here — see Theming and Density. A className is an escape hatch for source-owned and application work, not a cross-engine portability guarantee.

Executable examples

Primary executable fixture: apps/showcase/__tests__/dropdown-menu-item-description-slot.test.tsx
Additional fixture: apps/showcase/__tests__/dropdown-menu-trigger-haspopup-hover.test.tsx
Additional fixture: apps/showcase/__tests__/issue-141-rtl-overlay-acceptance.test.tsx
Additional fixture: apps/showcase/__tests__/issue-149-reduced-motion-acceptance.test.tsx

Addressable examples

Each link below opens the Showcase at that exact example, not at the top of the gallery:

basic — smallest meaningful complete usage
composition — the composition example

The Showcase links demonstrate Web behavior; use the native-preview guide for real simulator/emulator/device paths.

Live Web preview

This frame loads the real BeeUI Web Showcase on demand; it is not a second docs-only implementation. It proves browser behavior only. Use native preview for iOS/Android simulator, emulator or device paths.

Composition anatomy

Family root / primary export: DropdownMenu
- Public composition parts / helpers:
  - DropdownMenuCheckboxItem
  - DropdownMenuContent
  - DropdownMenuItem
  - DropdownMenuLabel
  - DropdownMenuRadioGroup
  - DropdownMenuRadioItem
  - DropdownMenuSeparator
  - DropdownMenuTrigger
- Exported type surface:
  - DropdownMenuAlign
  - DropdownMenuCheckboxItemProps
  - DropdownMenuCollisionPadding
  - DropdownMenuContentProps
  - DropdownMenuDirection
  - DropdownMenuItemProps
  - DropdownMenuLabelProps
  - DropdownMenuPlacement
  - DropdownMenuProps
  - DropdownMenuRadioGroupProps
  - DropdownMenuRadioItemProps
  - DropdownMenuSeparatorProps
  - DropdownMenuTriggerProps

The tree above is ordinary document structure so it remains readable with keyboard and assistive technology; it is derived from the real public export family rather than a canvas-only diagram.

Verified example source

These are the parts of the typechecked runtime Showcase fixture behind this live preview — apps/showcase/component-gallery/component-gallery.tsx, 1103 lines — where Dropdown Menu is actually used: 70 lines in 5 places. Each block is copied verbatim from the line range named above it, so it is the same executable source, not a retelling of it. The rest of that file exercises other families and is not reproduced here.

Imports the examples below need (a filtered subset of the fixture’s own top-level imports):

import { BeeThemeScope, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuItem, DropdownMenuLabel, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuTrigger, Text } from '@beemvp/beeui-ui';
import * as React from 'react';
import { useUniwind } from 'uniwind';

Fixture state this block reads (same file, lines 174, 176-178, 190):

const OverlayConsumerContext = React.createContext('overlay-context-default');
function OverlayContextValue({ testID }: { testID: string }) {
  return <Text testID={testID}>{`context: ${React.useContext(OverlayConsumerContext)}`}</Text>;
}
  const [menuOpen, setMenuOpen] = React.useState(false);

lines 219–227:

          <DropdownMenu onOpenChange={setMenuOpen} open={menuOpen}>
            <DropdownMenuTrigger testID="overlay-context-casec-menu-trigger" variant="outline">
              CASE C menu
            </DropdownMenuTrigger>
            <DropdownMenuContent>
              <DropdownMenuLabel>CASE C menu</DropdownMenuLabel>
              <OverlayContextValue testID="overlay-context-casec-menu-value" />
            </DropdownMenuContent>
          </DropdownMenu>

Fixture state this block reads (same file, lines 174, 176-178):

const OverlayConsumerContext = React.createContext('overlay-context-default');
function OverlayContextValue({ testID }: { testID: string }) {
  return <Text testID={testID}>{`context: ${React.useContext(OverlayConsumerContext)}`}</Text>;
}

lines 249–257:

        <DropdownMenu>
          <DropdownMenuTrigger testID="overlay-context-menu-trigger" variant="outline">
            Menu context
          </DropdownMenuTrigger>
          <DropdownMenuContent>
            <DropdownMenuLabel>Menu consumer context</DropdownMenuLabel>
            <OverlayContextValue testID="overlay-context-menu-value" />
          </DropdownMenuContent>
        </DropdownMenu>

Fixture state this block reads (same file, lines 174, 176-178, 235):

const OverlayConsumerContext = React.createContext('overlay-context-default');
function OverlayContextValue({ testID }: { testID: string }) {
  return <Text testID={testID}>{`context: ${React.useContext(OverlayConsumerContext)}`}</Text>;
}
  const [dialogMenuAction, setDialogMenuAction] = React.useState('none');

lines 290–304:

            <DropdownMenu>
              <DropdownMenuTrigger testID="overlay-context-dialog-menu-trigger" variant="outline">
                Menu in dialog
              </DropdownMenuTrigger>
              <DropdownMenuContent>
                <DropdownMenuLabel>Menu in dialog</DropdownMenuLabel>
                <OverlayContextValue testID="overlay-context-dialog-menu-value" />
                <DropdownMenuItem
                  onSelect={() => setDialogMenuAction('selected')}
                  testID="overlay-context-dialog-menu-item"
                >
                  Select in dialog
                </DropdownMenuItem>
              </DropdownMenuContent>
            </DropdownMenu>

Fixture state this block reads (same file, line 321-324):

function ThemeScopeValue({ testID }: { testID: string }) {
  const { theme } = useUniwind();
  return <Text testID={testID}>{`theme: ${theme}`}</Text>;
}

lines 343–351:

          <DropdownMenu>
            <DropdownMenuTrigger testID="theme-scope-menu-trigger" variant="outline">
              Menu in scope
            </DropdownMenuTrigger>
            <DropdownMenuContent>
              <DropdownMenuLabel>Menu in a BeeThemeScope</DropdownMenuLabel>
              <ThemeScopeValue testID="theme-scope-menu-value" />
            </DropdownMenuContent>
          </DropdownMenu>

Fixture state this block reads (same file, lines 469, 470, 471):

  const [menuToolbar, setMenuToolbar] = React.useState(true);
  const [menuDensity, setMenuDensity] = React.useState('comfortable');
  const [menuAction, setMenuAction] = React.useState('No action yet');

lines 792–819:

                  <DropdownMenu>
                    <DropdownMenuTrigger variant="outline">Workspace menu</DropdownMenuTrigger>
                    <DropdownMenuContent>
                      <DropdownMenuLabel>Workspace</DropdownMenuLabel>
                      <DropdownMenuItem onSelect={() => setMenuAction('Edit project')}>
                        Edit project
                      </DropdownMenuItem>
                      <DropdownMenuItem disabled>Archive unavailable</DropdownMenuItem>
                      <DropdownMenuSeparator />
                      <DropdownMenuCheckboxItem
                        checked={menuToolbar}
                        onCheckedChange={setMenuToolbar}
                      >
                        Show toolbar
                      </DropdownMenuCheckboxItem>
                      <DropdownMenuSeparator />
                      <DropdownMenuLabel>Density</DropdownMenuLabel>
                      <DropdownMenuRadioGroup
                        onValueChange={setMenuDensity}
                        value={menuDensity}
                      >
                        <DropdownMenuRadioItem value="compact">Compact</DropdownMenuRadioItem>
                        <DropdownMenuRadioItem value="comfortable">
                          Comfortable
                        </DropdownMenuRadioItem>
                      </DropdownMenuRadioGroup>
                    </DropdownMenuContent>
                  </DropdownMenu>

Open the fixture itself for the full surrounding component. For a smaller app-specific example, start from the imports and fixture-state blocks above and keep only the state your screen owns.

Limitations

Passing open without onOpenChange leaves the value read-only: the component renders what you passed and can never change it. It warns in development builds rather than failing silently in production.
Passing value without onValueChange leaves the value read-only: the component renders what you passed and can never change it. It warns in development builds rather than failing silently in production.