overlaysstable

Dropdown

Composable action menus with nested content, selection states, and rich items.

Documentation

Size

Color

Search ValueSearch Placeholder

Options

Usage

Import the component and configure it with the same props used in the playground.

Examples

Common patterns and practical usage examples.

Basic

Action menu with common items.

Groups and separators

Organizes related actions with labels and dividers.

Item adornments

Adds icons, badges, and shortcuts to clarify actions.

Searchable

Filter menu items.

Selectable items

Uses checkbox and radio menu items for temporary preferences.

Submenu

Nests secondary actions when the web menu has more choices.

Loading

Loading menu state.

Disabled

Disabled trigger state.

API

Props available for the React Dropdown.

104 props

Dropdown

Prop	Type	Default	Description
`open`	`boolean`	-	Controlled open state.
`defaultOpen`	`boolean`	-	Initial open state for uncontrolled usage.
`onOpenChange`	`((open: boolean) => void)`	-	Called when the open state changes.
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Controls the trigger and item size.
`color`	`'primary' \| 'neutral' \| 'success' \| 'warning' \| 'danger'`	`'primary'`	Semantic color palette for the dropdown trigger and active items.
`disabled`	`boolean`	`false`	Disables trigger interaction.
`loading`	`boolean`	`false`	Shows loading content instead of regular items.
`closeOnSelect`	`boolean`	`true`	Controls whether the dropdown closes after an item is selected.
`searchable`	`boolean`	`false`	Enables filtering through a search field.
`command`	`boolean`	`false`	Enables command-style keyboard and search behavior.
`searchValue`	`string`	-	Controlled search query.
`defaultSearchValue`	`string`	-	Initial search query for uncontrolled usage.
`searchPlaceholder`	`string`	-	Placeholder shown in the search field.
`onSearch`	`((value: string) => void)`	-	Called when the search query changes.
`children`Required	`ReactNode`	-	Trigger, content, and optional compound dropdown children.
`placement`	`'top' \| 'right' \| 'bottom' \| 'left' \| 'top-start' \| 'top-end' \| 'right-start' \| 'right-end' \| 'bottom-start' \| 'bottom-end' \| 'left-start' \| 'left-end'`	-	Floating content placement relative to the trigger.
`strategy`	`'absolute' \| 'fixed'`	-	CSS positioning strategy used by the floating content.
`offset`	`number`	`8`	Distance between the trigger and dropdown content.
`collisionPadding`	`number`	-	Padding used when avoiding viewport collisions.
`matchTriggerWidth`	`boolean`	-	Matches dropdown content width to the trigger width.
`minWidth`	`string \| number`	-	Minimum dropdown content width.
`maxWidth`	`string \| number`	-	Maximum dropdown content width.
`portal`	`boolean`	`true`	Renders dropdown content through a portal.
`avoidCollisions`	`boolean`	`true`	Allows the dropdown to flip or shift to stay visible.
`modal`	`boolean`	`false`	Uses modal interaction semantics while the dropdown is open.
`loop`	`boolean`	`true`	Allows keyboard navigation to wrap between first and last items.
`className`	`string`	-	Class name applied to the root element.
`loadingText`	`ReactNode`	-	Content shown while dropdown items are loading.
`empty`	`ReactNode`	-	Content shown when no items match the current query.

Dropdown.Trigger

Prop	Type	Default	Description
`disabled`	`boolean`	`false`	Disables trigger interaction.
`children`Required	`ReactNode`	-	Trigger content.
`asChild`	`boolean`	-	Composes trigger behavior onto a single child element.
`className`	`string`	-	Class name applied to the trigger element.

Dropdown.Content

Prop	Type	Default	Description
`command`	`boolean`	`false`	Enables command-style content behavior.
`children`	`ReactNode`	-	Dropdown item and slot content.
`className`	`string`	-	Class name applied to the content element.
`style`	`CSSProperties`	-	Inline style applied to the content element.

Dropdown.Search

Prop	Type	Default	Description
`placeholder`	`string`	-	Placeholder shown in the search field.
`aria-label`	`string`	-	Accessible name for the search input.
`className`	`string`	-	Class name applied to the search input.

Dropdown.Item

Prop	Type	Default	Description
`color`	`'default' \| 'primary' \| 'success' \| 'warning' \| 'danger'`	`'primary'`	Semantic color palette for the item.
`disabled`	`boolean`	`false`	Disables item interaction.
`closeOnSelect`	`boolean`	`true`	Overrides whether selecting this item closes the dropdown.
`children`Required	`ReactNode`	-	Item label or custom item content.
`asChild`	`boolean`	-	Composes item behavior onto a single child element.
`icon`	`ReactNode`	-	Icon rendered before the item label.
`description`	`ReactNode`	-	Supporting text rendered below the item label.
`badge`	`ReactNode`	-	Badge content rendered after the item label.
`shortcut`	`ReactNode`	-	Keyboard shortcut hint rendered after the item label.
`onSelect`	`((event: DropdownSelectEvent) => void)`	-	Called when this item is selected.
`href`	`string`	-	Link target rendered when the item acts as an anchor.
`target`	`import("react").HTMLAttributeAnchorTarget`	-	Anchor target used when href is provided.
`rel`	`string`	-	Anchor rel attribute used when href is provided.
`download`	`string \| boolean`	-	Anchor download attribute used when href is provided.
`className`	`string`	-	Class name applied to the item element.

Dropdown.CheckboxItem

Prop	Type	Default	Description
`disabled`	`boolean`	`false`	Disables item interaction.
`closeOnSelect`	`boolean`	`true`	Overrides whether selecting this item closes the dropdown.
`asChild`	`boolean`	-	Composes checkbox item behavior onto a single child element.
`checked`	`boolean`	-	Controlled checked state.
`defaultChecked`	`boolean`	-	Initial checked state for uncontrolled usage.
`onCheckedChange`	`((checked: boolean) => void)`	-	Called when the checked state changes.
`icon`	`ReactNode`	-	Indicator icon shown when the item is checked.
`shortcut`	`ReactNode`	-	Keyboard shortcut hint rendered after the item label.
`children`Required	`ReactNode`	-	Checkbox item label or custom content.
`className`	`string`	-	Class name applied to the checkbox item element.

Dropdown.RadioGroup

Prop	Type	Default	Description
`children`	`ReactNode`	-	Radio item children.
`value`	`string`	-	Controlled selected radio value.
`defaultValue`	`string`	-	Initial selected radio value for uncontrolled usage.
`onValueChange`	`((value: string) => void)`	-	Called when the selected radio value changes.

Dropdown.RadioItem

Prop	Type	Default	Description
`disabled`	`boolean`	`false`	Disables item interaction.
`closeOnSelect`	`boolean`	`true`	Overrides whether selecting this item closes the dropdown.
`children`Required	`ReactNode`	-	Radio item label or custom content.
`asChild`	`boolean`	-	Composes radio item behavior onto a single child element.
`value`Required	`string`	-	Value represented by this radio item.
`icon`	`ReactNode`	-	Indicator icon shown when the item is selected.
`shortcut`	`ReactNode`	-	Keyboard shortcut hint rendered after the item label.
`className`	`string`	-	Class name applied to the radio item element.

Dropdown.Group

Prop	Type	Default	Description
`children`	`ReactNode`	-	Grouped dropdown items.

Dropdown.Label

Prop	Type	Default	Description
`children`	`ReactNode`	-	Label content for a dropdown group.
`className`	`string`	-	Class name applied to the label element.

Dropdown.Separator

Prop	Type	Default	Description
`className`	`string`	-	Class name applied to the separator element.

Dropdown.Sub

Prop	Type	Default	Description
`children`	`ReactNode`	-	Submenu trigger and content.

Dropdown.SubTrigger

Prop	Type	Default	Description
`target`	`import("react").HTMLAttributeAnchorTarget`	-	Anchor target used when href is provided.
`color`	`'default' \| 'primary' \| 'success' \| 'warning' \| 'danger'`	`'primary'`	Semantic color palette for the item.
`disabled`	`boolean`	`false`	Disables item interaction.
`closeOnSelect`	`boolean`	`true`	Overrides whether selecting this item closes the dropdown.
`children`Required	`ReactNode`	-	Item label or custom item content.
`asChild`	`boolean`	-	Composes item behavior onto a single child element.
`icon`	`ReactNode`	-	Icon rendered before the item label.
`description`	`ReactNode`	-	Supporting text rendered below the item label.
`badge`	`ReactNode`	-	Badge content rendered after the item label.
`shortcut`	`ReactNode`	-	Keyboard shortcut hint rendered after the item label.
`href`	`string`	-	Link target rendered when the item acts as an anchor.
`rel`	`string`	-	Anchor rel attribute used when href is provided.
`download`	`string \| boolean`	-	Anchor download attribute used when href is provided.
`className`	`string`	-	Class name applied to the item element.

Dropdown.SubContent

Prop	Type	Default	Description
`children`	`ReactNode`	-	Submenu item and slot content.
`className`	`string`	-	Class name applied to the submenu content element.

Dropdown.ItemIcon

Prop	Type	Default	Description
`children`	`ReactNode`	-	Icon slot content.

Dropdown.ItemDescription

Prop	Type	Default	Description
`children`	`ReactNode`	-	Description slot content.

Dropdown.ItemBadge

Prop	Type	Default	Description
`children`	`ReactNode`	-	Badge slot content.

Dropdown.ItemShortcut

Prop	Type	Default	Description
`children`	`ReactNode`	-	Shortcut slot content.

Dropdown.Empty

Prop	Type	Default	Description
`children`	`ReactNode`	-	Empty state content.

Dropdown.Loading

Prop	Type	Default	Description
`children`	`ReactNode`	-	Loading state content.

Accessibility

Guidance for accessible usage and interaction.

Trigger naming

Use trigger content that clearly communicates the menu purpose.

childrenaria-label

Keyboard menu behavior

Preserve arrow-key navigation, Escape dismissal, and focus return to the trigger.

loopmodalopen

Item states

Use disabled and color state to communicate unavailable or destructive actions.

disabledcolor

Selection patterns

Use checkbox and radio items only when menu selections remain understandable from their labels.

checkedvalueonValueChange

Related components

Explore components that are commonly used alongside this one.

generalstable

Button

Accessible actions with multiple appearances, colors, sizes, and composition support.

View component

formsstable

Select

Composable single and multiple selection with search, groups, and virtualization.

View component

overlaysstable

Popover

Floating contextual content with collision handling and flexible positioning.

View component