Dropdown

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

Installation

ReducedMotion

Pass reducedMotionwhen you want the installed component to settle into its quieter motion path immediately. Leaving the prop unset still respects the user's system-level reduced motion preference.

Props

Dropdown

9 props

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

Defaultfalse

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"

Defaultselect

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.

Notes

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

4 props

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

Defaulttrue

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.

Notes

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

2 props

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.

Notes

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

DropdownContent

4 props

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"

Defaultstart

Horizontal alignment relative to the trigger wrapper.

sideOffsetnumber

Default8

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.

Notes

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

5 props

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.

Notes

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

4 props

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.

Notes

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

2 props

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.

Notes

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

DropdownSeparator

1 prop

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.

Notes

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

ReducedMotion

1 prop

Shared motion override for the motion-enabled exports documented on this page.

reducedMotionboolean

When true, the component uses its calmer motion path immediately. Leaving it unset still respects the user's system-level reduced motion preference.

Notes

This prop can force reduced motion on, but it does not opt out of OS-level accessibility preferences when the system is already requesting less motion.