iconiq
—Open GitHub

Dropdown

Composable dropdown primitives with a selectable value flow for persistent choices and an action-menu flow for immediate commands.

Open in

Installation

npx shadcn@latest add @iconiq/dropdown

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

The menu stays local to the trigger wrapper and is absolutely positioned under it instead of being portaled to document.body.
Escape and outside clicks close the menu. This version does not ship a full roving-focus keyboard model like Radix dropdown-menu.

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 content stays mounted only while the menu is open, and its spring animation is handled internally.

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 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.

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.