Dropdown

Compact menu for actions, overflow controls, and quick commands.

Installation

Props

Dropdown

Root provider that coordinates open state, selected value state, and the shared behavior used by the trigger, content, and item primitives.

childrenReactNode

Required

Compose DropdownTrigger, DropdownContent, DropdownItem, and optional helpers like DropdownValue or DropdownSeparator inside the root.

valuestring

Controlled selected value for the select variant. Action mode usually leaves this unset.

defaultValuestring

Initial selected value for uncontrolled select usage.

onValueChange(value: string | undefined) => void

Called when a select item updates the current value.

openboolean

Controlled open state for the menu surface.

defaultOpenboolean

Default false

Initial open state for uncontrolled usage.

onOpenChange(open: boolean) => void

Called whenever the trigger, outside click handling, or Escape key changes the open state.

variant"select" | "action"

Default select

Use select when items should commit a persistent value with a checkmark, or action when items should behave like immediate commands.

classNamestring

Merged onto the outer relative wrapper around the trigger and content.

Radix DropdownMenu.Root and Trigger handle open state, focus restoration, outside interactions, and keyboard typeahead while the public Iconiq parts API stays the same.

The select and action variants keep the exact same trigger shell, chevron spring, row styling, and grouped layout as the core dropdown component.

This Radix version portals the menu content, then reuses the same visible motion timings and offsets from registry/dropdown.tsx.

DropdownTrigger

Interactive trigger button that opens and closes the menu. It works with plain children, DropdownValue, or custom trigger content like an avatar.

childrenReactNode

Trigger content. In select mode this usually includes DropdownValue, while action menus can pass custom content such as an avatar or label row.

showChevronboolean

Default true

Hides the default chevron when you want a cleaner custom trigger, such as an avatar-only action menu.

classNamestring

Merged onto the trigger button shell.

disabledboolean

Prevents opening and dims the trigger styling.

The trigger is always rendered as a button in this version, so custom trigger visuals should be passed as children and styled with className.

DropdownValue

Small helper for select mode that reads the current value from context and prints the matching item label or a placeholder.

placeholderstring

Default "Select an option"

Text shown when no matching selected value is currently registered.

classNamestring

Merged onto the rendered span inside the trigger.

DropdownValue is only useful in select mode. Action menus usually provide their own trigger content instead.

DropdownContent

Animated menu surface that positions itself under the trigger and renders the item list for either variant.

childrenReactNode

Required

Usually DropdownItem children, with optional DropdownSeparator nodes between groups.

align"start" | "center" | "end"

Default start

Horizontal alignment relative to the trigger wrapper.

sideOffsetnumber

Default 8

Vertical gap between the trigger and the dropdown surface.

classNamestring

Merged onto the dropdown surface, which is useful for setting a custom width or changing shadows in docs/examples.

The motion layer is intentionally identical to the core dropdown: the same fade/slide entrance, the same delayed inner content settle, and the same rounded panel shell.

When you pass className="w-full", this Radix install maps that width to the trigger-width CSS variable so existing examples keep the same layout.

Radix manages collision-aware placement and focus, while the Iconiq layer preserves the original content styling and scroll treatment.

DropdownItem

Single interactive row used by both variants. In select mode it can register a value, and in action mode it acts like a plain command item.

childrenReactNode

Required

Row content. You can place icons inline before the label for action menus or richer item layouts.

valuestring

Selection key for select mode. When it matches the root value, the item renders the checkmark state.

textValuestring

Optional explicit label used by DropdownValue and typeahead when your item children are not plain text.

onClick(event: MouseEvent<HTMLButtonElement>) => void

Runs before the item closes the menu. Action menus typically use this for immediate commands like profile or logout.

disabledboolean

Prevents interaction and dims the row.

Select items do not render a filled selected background in this version; only the trailing checkmark indicates the chosen value.

If you omit value in select mode, the item behaves like a plain closing action and will not update the current value.

DropdownGroup

Optional wrapper for chunking larger menus into sections, with or without a visible label.

childrenReactNode

Required

Usually one or more DropdownItem nodes. Add label when you want a visible heading, or omit it when you just want grouped spacing.

labelReactNode

Optional convenience heading rendered with DropdownLabel styling and linked to the group for assistive technologies.

labelClassNamestring

Merged onto the generated section heading when you want to tweak its spacing or tone.

classNamestring

Merged onto the group wrapper. The base version adds light vertical spacing between grouped rows.

Label is optional. Without it, the wrapper only provides spacing unless you also pass aria-label or aria-labelledby.

If you provide label, the wrapper upgrades to role=group and wires aria-labelledby automatically.

DropdownLabel

Standalone non-interactive heading helper for advanced content layouts or custom grouping patterns.

childrenReactNode

Required

Short section text such as Product, Billing, or Workspace settings.

classNamestring

Merged onto the rendered div when you want to adjust spacing, weight, or casing locally.

Use this directly when you want a heading style without the convenience wrapper supplied by DropdownGroup.

DropdownSeparator

Simple divider for grouping related items inside the content surface.

classNamestring

Merged onto the divider element when you want to adjust spacing or tone locally.

The base separator uses the shared border token and a small vertical margin between item groups.

Registry bundle

Install the exact registry entry shown on the right when you want the component file and its declared runtime dependencies together.

Dependencies: @radix-ui/react-dropdown-menu, motion, lucide-react.

This page documents the Radix UI install only. Base UI does not ship an equivalent dropdown menu primitive in this comparison set.

The generated registry file is /r/r-dropdown.json.