Dropdown Preview

A dropdown lets people choose one or more options from a list. It can be used in forms to gather information where the options require custom styling or in UI to filter and sort information.

If you're designing a form, especially for mobile platforms, consider using a select for baked-in accessibility. If you need to let someone type in the visible field to submit a free form answer, or to filter the list, try a combobox.

Loading...
Open in CodeSandbox
Dropdown storybook
React guidance

Properties

appearance

Controls the colors and borders of the combobox trigger.

“outline” “underline” “filled-darker” “filled-lighter”
Default:
“‘outline’”

as

“button”
Default:
none

button

WithSlotShorthandValue<{ as?: "button"; } & Pick<DetailedHTMLProps<ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "key" | keyof ButtonHTMLAttributes<...>> & { ...; } & { ...; }>
Default:
none

defaultOpen

The default open state when open is uncontrolled

boolean
Default:
none

defaultSelectedOptions

For an uncontrolled component, sets the initial selection. If this is set, the defaultValue prop MUST also be set.

string[]
Default:
none

expandIcon

WithSlotShorthandValue<{ as?: "span"; } & Pick<DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "key" | keyof HTMLAttributes<...>> & { ...; } & { ...; }> | null
Default:
none

inlinePopup

Render the combobox’s popup inline in the DOM. This has accessibility benefits, particularly for touch screen readers.

boolean
Default:
none

listbox

WithSlotShorthandValue<WithSlotRenderFunction<Omit<ListboxSlots, "root"> & Omit<{ as?: "div"; } & Pick<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "key" | keyof HTMLAttributes<...>> & { ...; } & { ...; }, "ref"> & SelectionProps & RefAttributes<...>>> | null
Default:
none

multiselect

Sets the selection type to multiselect. Set this to true for multiselect, even if fully controlling selection state. This enables styles and accessibility properties to be set.

boolean
Default:
false

onOpenChange

Callback when the open/closed state of the dropdown changes

((e: ComboboxBaseOpenEvents, data: ComboboxBaseOpenChangeData) => void)
Default:
none

onOptionSelect

((event: SelectionEvents, data: OptionOnSelectData) => void)
Default:
none

open

Sets the open/closed state of the dropdown. Use together with onOpenChange to fully control the dropdown’s visibility

boolean
Default:
none

positioning

Configure the positioning of the combobox dropdown

PositioningShorthand
Default:
none

root

WithSlotShorthandValue<{ as?: "div"; } & Pick<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "key" | keyof HTMLAttributes<...>> & { ...; } & { ...; }>
Default:
none

selectedOptions

An array of selected option keys. Use this with onOptionSelect to directly control the selected option(s) If this is set, the value prop MUST also be controlled.

string[]
Default:
none

size

Controls the size of the combobox faceplate

“small” “medium” “large”
Default:
“‘medium’”