Overview
Go Headless

Changelog

Wix Design System (WDS)
Introduction
About Wix Design System
Get started developing
Get started designing
Theming
Wix Design System AI

Guidelines
Themes
Interaction & Behavior
Guidelines
Localization

Patterns
Patterns Overview
Table Pattern
Grid Switch Pattern
Grid Pattern

Foundations
Tokens and Theming basics
Icon Theming

Contributing
AI-Assisted Development
Component Structure
Contributing to Wix Design System
Creating a New Component
Creating a Pull Request
Deprecating a Component
Documenting
Fixing a Bug
Test Drivers
Contributing Tokens
Token Migration Guidelines
Updating Props
Writing Tests

Components
Actions
Animations
Charts
Feedback
Form
AddressInput Component
AddressInputItem Component
AngleInput Component
AtlasAddressInput Component
AutoComplete Component
AutoCompleteWithLabel Component
Calendar
Checkbox Component
CheckToggle Component
ColorInput Component
ColorPicker Component
CornerRadiusInput Component
DatePicker Component
Dropdown Component
DropdownBase Component
Dropzone Component
FacesRatingBar Component
FieldSet Component
FilePicker Component
FileUpload Component
FillPreview Component
FormField Component
InfoIcon Component
Input Component
InputArea Component
InputShell Component
InputWithLabel Component
ListItemAction Component
ListItemEditable Component
ListItemSection Component
ListItemSelect Component
ListItemSelectIcon Component
MultiSelect Component
MultiSelectCheckbox Component
NumberInput Component
Palette Component
Radio Component
RadioGroup Component
Range Component
RichTextInputArea Component
Search Component
SegmentedToggle Component
Slider Component
StarsRatingBar Component
StatusIndicator Component
Swatches
Tag Component
Thumbnail Component
TimeInput Component
ToggleSwitch Component
VariableInput Component
Layout
Lists
Mechanisms
Media
Navigation
Overlays
Panels
Typography
In This Article

  1. Overview
  2. Code
  3. Testkit
  4. Changelog

Dropdown

Components/Form

Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/dropdown

Overview

Copy

Dropdowns let users select a single item from a predefined list of options.

Do

  • Use when users can select a single item from 5 to 10 options.

Don't

  • Don't use to display two mutually exclusive selections. Use <ToggleSwitch/> instead.
  • Don't use to display two to four options. Use <RadioGroup/> instead.
  • Don't use to display 11 or more options. Use <Autocomplete/> or <SelectorList/> instead.

Feature examples

Size

Adjust the component size using the size prop.

  • large emphasize fields in onboarding flows.
  • medium is the default size used in most cases.
  • small should be used in compact layouts.
  • tiny should be used in very dense layouts. Avoid using this size when possible.
Copy

Border

Style the component using the border prop which supports four styles:

  • For forms, use standard.
  • When the component is used to filter, use round.
  • For titles that can be edited on click, use bottomLine.
  • In the Content Manager's spreadsheet, use none.
Copy

Status

Use the status prop to control component status.

  • error highlights an invalid selection.
  • warning highlights a value that can't be validated or impacts a user's business.
  • loading shows that the value is loading.

Hide the status suffix and indicate the state with a border color by setting hideStatusSuffixto true.

Copy

Status message

Add text that explains the status or what action the user should take with the statusMessage prop.

Showing the status message inline, directly below the dropdown is preferred in all default cases.

  • To add an accessible inline message, wrap the component in a <FormField/> and add the statusMessage.
  • To add a status message in a tooltip that requires users to hover on the icon, use the statusMessage prop. Control tooltip placement with tooltipPlacement prop.

View more inline status message examples in <FormField/>.

Copy

Disabled

Disable all input interactions with the disabled prop. Use it to highlight unavailable functions.

Copy

Affix

Add additional information to prefix and suffix props (e.g. text, icons, buttons) to support the dropdown value.

Copy

Clear button

Enable a button that clears the dropdown value by using the clearButton prop. Show it when the field value is optional or has to be cleared often.

Copy

Fixed header and footer

Add related actions to fixedFooter or fixedHeader areas. These headers and footers keep their position on scroll.

Copy

List item builders

Use three props to build custom layouts:

  • listItemSectionBuilder groups items into sections by type.
  • listItemActionBuilder adds a text button for related list actions.
  • listItemSelectBuilder builds custom list designs.
Copy

List container dimensions

Control the container size for the list of options with these props:

  • maxHeightPixels specifies the maximum height for longer lists.
  • dropdownWidth matches content width or specifies pixels. Set width to 'auto' or 'max-content.'
  • minWidthPixels manually increases dropdown popover width.

By default, the dropdown matches the input field width.

Copy

Marked option

Once the dropdown is opened, use the markedOption to highlight the option.

Copy

Native support

Switch to native support for mobile usage. Avoid using it for desktop applications.

Copy

Text overflow

Control text overflow in the field with the textOverflow. Apply clip or ellipsis.

Dropdown list options wrap by default. To apply ellipsis, select the items to be displayed with the listItemSelectBuilder. This isn't recommended.

Copy

Developer examples

Lazy loading

Gradually load items with infiniteScroll, loadMore and hasMore props.

Copy

Controlled

Component can be used in controlled mode by passing selectedId and onSelect props.

Copy

Common use case examples

Settings panel

Use dropdown to let users select a single item from a predefined list of options in a settings panel.

Copy

Prefix icon

Use listItemSelectBuilder to create custom layouts for options in the dropdown. For example, use avatars, icons or images as prefix icons.

Copy

Grouping

Use listItemSectionBuilder within the drop down to group options into categories.

Copy

Code

Copy

Props

NameTypeDefaultDescription
allowTextSelectionbooleantrueControls whether a user can select a text of a selected value.
ariaControlsstring—Associate a control with the regions that it controls.
ariaDescribedbystring—Associate a region with its descriptions. Similar to aria-controls but instead associating descriptions to the region and description identifiers are separated with a space.
ariaLabelstring—Define a string that labels the current element in case where a text label isn't visible on the screen.
ariaRoledescriptionstring—Sets the aria-roledescription attribute of the <input> element, giving assistive technologies a readable description of its role.
autocompletestring'off'Sets the value of the native autocomplete attribute of the input.
autoFocusboolean—Focus the element on mount (standard React input autoFocus)
autoSelectboolean—Automatically selects the entire input text.
backgroundColorstring—Sets the background color of the input. Accepts any CSS color value.
border"none" | "standard" | "round" | "bottomLine"—Control the border style of input.
childrenReactNode—
clearButtonboolean—Displays clear button (X) on a non-empty input.
clearButtonAriaLabelstring—Aria label for the clear button.
clearButtonTooltipContentReactNode—When provided, hovering displays a tooltip with this content.
clearButtonTooltipPropsTooltipCommonProps—Clear button tooltip props.
closeOnSelectbooleantrueCloses DropdownLayout on option selection.
customDropdownContentReactNode—Accepts any content to render in the dropdown instead of the options list. Ignored when native is true.
customInputReactNode | Function—Render a custom input instead of the default html input tag.
dataHookstring—Applies a data-hook HTML attribute that can be used in the tests.
defaultValuestring | number—Defines the initial value of an input.
disabledboolean—Specifies whether input should be disabled or not.
disableEditingboolean—Restricts input editing.
dropDirectionUpboolean—Specifies whether the list opens upward. Aligns the list container to the bottom and positions the arrow for upward direction.
dropdownOffsetLeftstring'0'Sets the offset of the dropdown from the left.
dropdownWidthstringnullSets the width of the dropdown.
enterKeyHint"search" | "enter" | "done" | "go" | "next" | "previous" | "send"—Sets the label of the virtual keyboard's enter key on touch devices.
fixedFooterReactNode—A fixed footer to the list.
fixedHeaderReactNode—A fixed header to the list.
focusOnClearClickboolean—Specifies whether to focus the field when clear button is clicked.
focusOnOptionstring | number—Marks (not selects) and scrolls view to the option on opening the dropdown by option id.
focusOnSelectedOptionboolean—Scroll view to the selected option on opening the dropdown.
hasMoreboolean—Whether there are more items to be loaded.
hideStatusSuffixboolean—Specifies whether status suffix should be hidden.
highlightboolean—Mark in bold word parts based on search pattern.
idstring—Assigns a unique identifier for the root element.
inContainerboolean—Whether the <DropdownLayout/> is in a container component. If true, some styles such as shadows, positioning and padding are added to the component contentContainer.
infiniteScrollboolean—Set this prop for lazy loading of the dropdown layout items.
initialSelectedIdstring | number—An initial selected option id. (Implies Uncontrolled mode)
inputElementReactElement—Use a customized input component instead of the default
inputmodestring—Sets the value of the native inputmode attribute, which tells mobile browsers which on-screen keyboard to show, for example numeric or email.
inputRefnull | (instance: HTMLInputElement | null) => void | RefObject<HTMLInputElement>—Ref to the underlying <input> DOM element. Accepts callback and object refs. Use for input masking libraries such as use-mask-input. Memoize callback refs to avoid reattaching on every render.
itemHeight"big" | "small"'small'Controls the minimum height of options that aren't builder options.
listboxIdstring—Defines the id for the listbox.
listType"select" | "action"—Defines type of behavior applied in list.
loadMore(page: number) => void—A callback called when more items are requested to be rendered.
markedOptionstring | number | false | true—Sets the default hover behavior when: 1. false means no default 2. true means to hover the first selectable option 3. Any number/string represents the id of option to hover
maxnumber—Sets a maximum value of an input. Similar to html5 max attribute.
maxHeightPixelsstring | number—Set the max height of the dropdownLayout in pixels.
maxLengthnumber—Sets the maximum number of characters that can be inserted to a field.
menuArrowboolean—Specifies whether input should have a dropdown menu arrow on the right side.
minnumber—Sets a minimum value of an input. Similar to HTML5 min attribute.
minWidthPixelsstring | number—Set the min width of the dropdownLayout in pixels.
namestring—Reference element data when a form is submitted.
nativebooleanfalseIndicates whether to render using the native select element.
noLeftBorderRadiusboolean—Specifies whether input shouldn't have rounded corners on its left.
noRightBorderRadiusboolean—Specifies whether input shouldn't have rounded corners on its right.
onBlurFocusEventHandler—Defines a standard input onBlur callback.
onChangeChangeEventHandler—Defines a standard input onChange callback.
onClear(event: KeyboardEvent<HTMLButtonElement> | MouseEvent<HTMLButtonElement, MouseEvent>) => void—Displays clear button (X) on a non-empty input and calls a callback function.
onClickOutside(e: MouseEvent | TouchEvent) => void—Defines a callback function which is called when the user clicks or touches outside the list while it's visible.
onClose() => void—Callback function called whenever the user press the Escape keyboard.
onCompositionChange(isComposing: boolean) => void—Defines a callback function called on compositionstart/compositionend events.
onCopyClipboardEventHandler<HTMLInputElement>—Defines a callback handler that is called when user copies text to a clipboard (using a mouse or keyboard shortcut)
onDrillIn(option: DropdownLayoutValueOption) => void—Called when the user presses ArrowRight on a hovered option. Use to move focus into an interactive child element (e.g. an actions menu).
onDrillOut() => void—Called when the user navigates back from a drilled-in child element (e.g. via ArrowLeft or Escape). Use to restore focus to the trigger input.
onEnterPressedKeyboardEventHandler<HTMLInputElement>—Defines a callback handler that is called when the user presses -enter-.
onEscapePressedKeyboardEventHandler<HTMLInputElement>—Defines a callback handler that is called when the user presses -escape-.
onFocusFocusEventHandler—Defines a standard input onFocus callback.
onInputClickedMouseEventHandler—Defines a standard input onClick callback.
onKeyDownKeyboardEventHandler<HTMLInputElement>—Defines a standard input onKeyDown callback.
onKeyUpKeyboardEventHandler<HTMLInputElement>—Defines a standard input onKeyUp callback.
onManuallyInputManualInputFnSignature—A callback which is called when the user performs a Submit-Action. Submit-Action triggers are: "Enter", "Tab", [typing any defined delimiters], Paste action. `onManuallyInput(values: Array): void - The array of strings is the result of splitting the input value by the given delimiters
onMouseDownMouseEventHandler—Callback function called whenever the user clicks the dropdown layout.
onMouseEnterMouseEventHandler—Callback function called whenever the user entered with the mouse to the dropdown layout.
onMouseLeaveMouseEventHandler—Callback function called whenever the user exited with the mouse from the dropdown layout.
onOptionMarked(option: DropdownLayoutValueOption | null, optionElementId?: string | undefined) => void—Callback function called whenever an option becomes focused (hovered/active). Receives the relevant option object from the original props.options array.
onOptionsHide() => void—A callback which is called when options dropdown is hidden.
onOptionsNavigate(option: DropdownLayoutValueOption | null) => void—Callback function called whenever the user navigates to an option (via keyboard or mouse). Receives the relevant option object from the original props.options array, or null when navigation is cleared.
onOptionsShow() => void—A callback which is called when options dropdown is shown.
onPasteClipboardEventHandler<HTMLInputElement>—Defines a callback handler that is called when user pastes text from a clipboard (using a mouse or keyboard shortcut)
onSelect(option: DropdownLayoutValueOption, sameOptionWasPicked: boolean) => void—Defines a callback function which is called when the user selects an option from the list. When highlight is true, it receives the original option from options.
optionsDropdownLayoutOption[]—Array of objects: - id <string / number> required: the id of the option, should be unique. - value <function / string / node> required: can be a string, react element or a builder function. - disabled <bool> default value- false: whether this option is disabled or not - linkTo <string>: when provided, the option is an anchor to the given value - title <bool> default value- false deprecated: use listItemSectionBuilder to render a title instead. - overrideStyle <bool> default value- false deprecated: use overrideOptionStyle to override option styles instead. - overrideOptionStyle <bool> default value- false - when set to true, the option is responsible for its own styles. No styles are applied from the DropdownLayout itself. - label <string>: the string displayed within an input when the option is selected. This is used when using <DropdownLayout/> with an <Input/>.
overflow"visible" | "hidden" | "auto" | "scroll"—Set overflow of container.
patternstring—Sets a pattern that typed value must match to be valid (regex)
placeholderstring—Sets a placeholder message to display.
popoverPropsPopoverCommonProps—Accepts common popover props that are passed to the options dropdown popover.
prefixReactNode—Pass a component you want to show as the prefix of the input, e.g., text, icon.
readOnlyboolean—Specifies whether input is read only.
requiredboolean—Specifies whether input is mandatory.
rolestring—Specifies the role of the input element for accessibility.
rtlboolean—Specifies text direction. If true, the text is displayed from right to left.
scrollbar"fixed" | "overlay"—Controls which type of scrollbar to render.
scrollToOptionstring | number—Scrolls to the specified option when dropdown is opened without marking it.
selectedHighlightbooleantrueWhether the selected option is highlighted when the dropdown reopens.
selectedIdstring | number—Specifies selected option by its id.
showDrawerOnMobilebooleantrueControls whether to show drawer on mobile devices.
showOptionsIfEmptyInputbooleantrueControls whether to show options if input is empty.
size"small" | "tiny" | "medium" | "large"'medium'Controls the size of the input and its dropdown options. tiny and small inputs render small options, the rest render medium ones.
status"error" | "warning" | "loading"—Specify the status of a field.
statusMessageReactNode—Defines the message to display on status icon hover. If not given or empty, no tooltip is displayed.
statusMessageTooltipPropsTooltipCommonProps—Status message tooltip props.
stepnumber—Specifies the interval between number values.
suffixReactNode—Pass a component you want to show as the suffix of the input, e.g., text, icon.
tabIndexnumber—Indicates that element can be focused and where it participates in sequential keyboard navigation.
textOverflow"ellipsis" | "clip"—Handles text overflow behavior. It can either clip (default) or display ellipsis.
tooltipPlacement"right" | "left" | "top" | "bottom" | "auto" | "auto-start" | "auto-end" | "top-start" | "top-end" | "right-start" | "right-end" | "bottom-end" | "bottom-start" | "left-end" | "left-start"—Controls placement of a status tooltip.
typestring—Specifies the type of <input/> element to display. Default is text.
valuestring | number—Specifies the current value of the element.
valueParser(option: DropdownLayoutValueOption) => ReactNode | RenderOptionFn—Function that receives an option, and should return the value to be displayed.
visibleboolean—Should show or hide the component.
withArrowboolean—Displays an arrow on the list container while it's visible.
withSelectionboolean—

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
exists—
driver—
inputDriver—
dropdownLayoutDriver—

Changelog

  • 1.340.0 (2026-10-21) — maintenance release, no component-specific changes
  • 1.339.0 (2026-10-19) — maintenance release, no component-specific changes
  • 1.338.0 (2026-10-15) — maintenance release, no component-specific changes
  • 1.330.0 (2026-09-28) — maintenance release, no component-specific changes
  • 1.323.0 (2026-09-10) — maintenance release, no component-specific changes
  • 1.317.0 (2026-08-26) — maintenance release, no component-specific changes
  • 1.312.0 (2026-08-14) — maintenance release, no component-specific changes
  • 1.310.0 (2026-08-10) — maintenance release, no component-specific changes
  • 1.292.0 (2026-06-22) — maintenance release, no component-specific changes
  • 1.291.0 (2026-06-19) — maintenance release, no component-specific changes
  • 1.289.0 (2026-06-17) — maintenance release, no component-specific changes
  • 1.287.0 (2026-06-10) — fix: dropdownWidth and popoverProps.width (#16357) — has visual changes
  • 1.278.0 (2026-05-08) — maintenance release, no component-specific changes
  • 1.266.0 (2026-04-07) — maintenance release, no component-specific changes
  • 1.260.0 (2026-03-17) — maintenance release, no component-specific changes
  • 1.241.0 (2025-12-17) — maintenance release, no component-specific changes
  • 1.226.0 (2025-11-10) — feat: displays Drawer in mobile (#15478) — has visual changes
  • 1.220.2 (2025-10-06) — maintenance release, no component-specific changes
  • 1.213.0 (2025-08-19) — maintenance release, no component-specific changes
  • 1.212.0 (2025-08-11) — maintenance release, no component-specific changes
  • 1.211.0 (2025-08-07) — fix: listItemSelectBuilder ability to override size (#15158)
  • 1.210.0 (2025-08-04) — breaking: listItemBuilders respect dropdown size (#15144)
  • 1.205.0 (2025-07-15) — breaking: now items are affected by the Dropdown size (#15054)
  • 1.204.1 (2025-07-09) — fix: adjust selection styling for non-selectable text (#15067)
  • 1.204.0 (2025-07-03) — fix: selectOptionById now closes the popover after selection in visual tests (#14997)
  • 1.203.0 (2025-07-01) — fix: disabled mode (#15028)
  • 1.201.0 (2025-06-23) — feat: allowTextSelection prop added (#14976)
  • 1.199.0 (2025-06-13) — feat: add overlay for Popover content (#14940)
  • 1.191.0 (2025-05-22) — maintenance release, no component-specific changes
  • 1.190.0 (2025-05-22) — maintenance release, no component-specific changes
  • 1.188.1 (2025-05-14) — fix: opens on space or enter key (#14855)
  • 1.188.1 (2025-05-14) — fix: touch up accessibility (#14839)
  • 1.186.0 (2025-05-05) — maintenance release, no component-specific changes
  • 1.185.0 (2025-04-30) — maintenance release, no component-specific changes
  • 1.180.0 (2025-04-14) — maintenance release, no component-specific changes
  • 1.138.1 (2024-10-30) — maintenance release, no component-specific changes
  • 1.124.0 (2024-09-06) — maintenance release, no component-specific changes
  • 1.115.0 (2024-07-17) — maintenance release, no component-specific changes
  • 1.105.2 (2024-05-22) — fix: removed HOC prop exposure to eliminate clashing types (#13762)
  • 1.102.0 (2024-04-16) — maintenance release, no component-specific changes
  • 1.98.0 (2024-03-15) — fix: fix content padding when wrapped in tooltip (#13443)
  • 1.93.0 (2024-02-08) — maintenance release, no component-specific changes
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 26 October 2026

Did this help?