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

DropdownBase

Components/Form/DropdownBase

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

Overview

Copy

The DropdownBase is a mechanism that allows the user to open up a dropdown layout via a specified trigger element and return a selected value for it.

Do

  • Use it to build custom filters.
  • Use it to build "sort by" actions.

Don't

  • Don't use it to select relevant value in forms. Use standard <Dropdown/> instead.
  • Don't use it to build menus. Use <PopoverMenu/> instead.

Feature examples

Structure

This component consists of a list of options inside a popover that is called out via a `trigger` element. The `trigger` can be any interactive WSR component. Usually it's `TextButton.`

Copy

Trigger action

Call out a popover on click or hover interactions.

Copy

Placement

Control the dropdown layout location around a trigger with the `placement` prop. It accepts all <Popover/> placement options. Move it farther from the trigger on X and Y axis with the `moveBy` prop.

Copy

Dimensions

Control dropdown layout dimensions with:
 - `maxHeight` - limit the height for longer list of options.
 - `minWidth` - control minimum width when the trigger element is narrow.
 - `maxWidth` - limit the width when the list contains long titles.
 - `dynamicWidth` - match the dropdown width to the trigger element width.

Copy

Arrow

Control the popover arrow visibility with the `showArrow` prop. It's not displayed by default.

Copy

List item builders

Build custom dropdown layouts with:
 - `listItemSectionBuilder` - use this element to group items into sections by type. See ListItemSection for more details.
 - `listItemActionBuilder` - use this element to add text button for related list actions, e.g. "Manage categories". See ListItemAction for more details.
 - `listItemSelectBuilder` - use this element to build custom list designs. See ListItemSelect for more details.

Copy

Focus on option

Control a focused element inside of dropdown with:
 - `focusOnOption` - control which option is highlighted when nothing is selected yet.
 - `focusOnSelectedOption` - scrolls list to display selected option when dropdown is opened.

Copy

Animate

Create smooth transitions by adding enter and exit animations to the popover with the `animate` prop.

Copy

Common use case examples

Content filters

Use DropdownBase to build custom filters for page or card content.

Copy

Assign task or item

Use DropdownBase to call out popovers for the user to assign a person. Once selected, replace the trigger button with a tag representing the user.

Copy

Code

Copy

Props

NameTypeDefaultDescription
animatebooleanfalseAdds enter and exit animation.
appendTonull | Element | "window" | "scrollParent" | "viewport" | "parent" | Predicate'parent'Specifies where popover should be inserted as a last child - whether parent or window containers.
autoFocusboolean—Specifies whether first list item should be focused.
boundaryPaddingnumber | { right?: number | undefined; left?: number | undefined; top?: number | undefined; bottom?: number | undefined; }5Sets the minimum distance, in pixels, to keep between the <Popover/> and the edges of the area it's positioned in. Accepts a single value for every side, or an object to set sides individually. Sides that are left out keep the default distance.
childrennull | string | number | false | true | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | ChildrenFnArgs<any>—Specifies a target component to be rendered. If a regular node is passed, it's rendered as-is. If a function is passed, it's expected to return a React element. The function accepts an object containing the following properties: * open - opens the Popover * close - closes the Popover * toggle - toggles the Popover * isOpen - indicates whether the items list is currently open * delegateKeyDown - the underlying DropdownLayout's keydown handler. It can be called inside another keyDown event in order to delegate it. * selectedOption - the currently selected option Check inserted component documentation for more information on available properties.
dataHookstring—Applies a data-hook HTML attribute that can be used in the tests.
dynamicWidthbooleantrueSet popover's content width to a minimum width of a trigger element, but it can expand up to the defined value of maxWidth
fixedboolean—Specifies whether to enable the fixed behaviour. If enabled, keep its original placement even when it's being positioned outside the boundary.
fixedFooterReactNode—A fixed footer to the list.
fixedHeaderReactNode—A fixed header to the list.
flipboolean—Specifies whether to flip the placement when it starts to overlap the target element (<Popover.Element/>)
fluidbooleanfalseStretches trigger element to fill its parent container width.
focusOnOptionstring | number—Focus to the specified option when dropdown is opened.
focusOnSelectedOptionboolean—Focus to the selected option when dropdown is opened.
hasMoreboolean—Specifies whether there are more items to load.
infiniteScrollboolean—Specifies whether lazy loading of the dropdown items is enabled.
initialSelectedIdstring | number—Sets the initially selected option in the list. Used when selection behaviour is being controlled.
listType"select" | "action"'select'Defines type of behavior applied in list.
loadMore(page: number) => void—Defines a callback function which is called on a request to render more list items.
markedOptionstring | number | false | true—Sets the initial marking of an option in the list when opened: - false - no initially hovered list item - true - hover first selectable option - any number/string specify the id of an option to be hovered
maxHeightstring | number'260px'Controls the maximum height of dropdown layout.
maxWidthstring | number | string & {}—Controls the maximum width of dropdown layout.
minWidthstring | number | string & {}192Controls the minimum width of dropdown layout.
moveByMoveByOffset—Moves dropdown content relative to the parent on X or Y axis by a defined amount of pixels.
onClickOutside() => void—Defines a callback function which is called when user clicks outside of a dropdown.
onClose(reason: DropdownBaseCloseReason) => void—Defines a callback function which is called when the user closes the dropdown. reason is 'outside-press' for a click outside of it, 'escape-key' for the Esc key and 'drag' for dragging its mobile drawer closed. A parent that controls open closes the dropdown here.
onHide() => void—Defines a callback function which is called when dropdown is closed.
onMouseDownMouseEventHandler—Callback function called whenever the user clicks the dropdown layout.
onMouseEnter() => void—Defines a callback function which is called on onMouseEnter event on the entire component.
onMouseLeave() => void—Defines a callback function which is called on onMouseLeave event on the entire component.
onSelect(option: DropdownLayoutValueOption) => void—Defines a callback function which is called whenever user selects a different option in the list.
onShow() => void—Defines a callback function which is called when dropdown is opened.
openboolean—Control whether the should be opened.
optionsDropdownLayoutOption[]—Specifies an array of options for a dropdown list. Objects must have an id and can include string value or node. If value is '-', a divider is rendered instead (dividers don't require and id).
overflow"visible" | "hidden" | "auto" | "scroll"—Handles container overflow behaviour.
placement"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"'bottom'Control popover placement.
scrollToOptionstring | number—Scrolls to the specified option when dropdown is opened without marking it.
selectedIdstring | number—Define the selected option in the list.
showArrowbooleanfalseSpecifies whether popover arrow should be shown.
tabIndexnumber—Indicates that element can be focused and where it participates in sequential keyboard navigation.
transitionSettings{ type?: "css" | undefined; openDelay?: number | undefined; closeDelay?: number | undefined; duration?: number | { open?: number | undefined; close?: number | undefined; } | undefined; opacity?: { ......—Specifies popover content transitioning, passed through to PopoverNext.
zIndexnumber—Specifies the stack order (z-index) of a dropdown layout.

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
getListTypeReturns the list type prop value
clickTargetElementReturns the target element
hoverTargetElementHover the target element
isDropdownShownReturns true if the dropdown is being shown
selectOptionSelect a specific option (requires the DropdownBase to be opened)
selectOptionByDataHookSelect a specific option by its data hook (requires the DropdownBase to be opened)
clickOutsideClick outside of the component
optionsCountOptions count (requires the DropdownBase to be opened)
optionContentAt—
getSelectedOptionIdReturns the selected option (requires the DropdownBase to be opened)
getMarkedOptionReturns the marked option (requires the DropdownBase to be opened)
mouseEnter—
mouseLeave—
existsChecks whether the component found with the given data hook.
elementGets the component root element.
clickClicks on the component root element.
baseReturns UniDriver for the base element.

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.335.0 (2026-10-12) — maintenance release, no component-specific changes
  • 1.333.0 (2026-10-06) — maintenance release, no component-specific changes
  • 1.330.3 (2026-09-29) — maintenance release, no component-specific changes
  • 1.329.0 (2026-09-24) — maintenance release, no component-specific changes
  • 1.328.0 (2026-09-22) — maintenance release, no component-specific changes
  • 1.325.0 (2026-09-17) — maintenance release, no component-specific changes
  • 1.324.0 (2026-09-14) — maintenance release, no component-specific changes
  • 1.317.0 (2026-08-26) — maintenance release, no component-specific changes
  • 1.316.0 (2026-08-25) — fix: styles migrated from Stylable to semantic classnames — rendering is unchanged, but the component's internal Stylable-generated classnames are replaced by wds-dropdown-base* ones. (#16884)
  • 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.279.0 (2026-05-13) — maintenance release, no component-specific 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.254.0 (2026-02-03) — maintenance release, no component-specific changes
  • 1.252.0 (2026-01-28) — maintenance release, no component-specific changes
  • 1.246.0 (2026-01-09) — maintenance release, no component-specific changes
  • 1.242.0 (2025-12-19) — maintenance release, no component-specific changes
  • 1.241.0 (2025-12-17) — maintenance release, no component-specific changes
  • 1.240.0 (2025-12-16) — maintenance release, no component-specific changes
  • 1.236.0 (2025-12-04) — maintenance release, no component-specific changes
  • 1.232.0 (2025-11-28) — fix: make DropdownBase (fixedHeader/fixedFooter) accessible by keyboard navigation (#15527)
  • 1.229.0 (2025-11-18) — fix: ensure autoFocus=false correctly prevents focusing (#15519)
  • 1.226.0 (2025-11-10) — feat: displays Drawer in mobile (#15477) — has visual changes
  • 1.225.0 (2025-11-07) — maintenance release, no component-specific changes
  • 1.204.0 (2025-07-03) — maintenance release, no component-specific changes
  • 1.202.0 (2025-06-27) — maintenance release, no component-specific changes
  • 1.191.1 (2025-05-27) — maintenance release, no component-specific changes
  • 1.181.0 (2025-04-18) — fix: normal word break (#14741)
  • 1.179.1 (2025-04-10) — fix: specify dropdown css to avoid overriding by a tooltip (#14735)
  • 1.179.0 (2025-04-09) — maintenance release, no component-specific changes
  • 1.172.0 (2025-03-20) — maintenance release, no component-specific changes
  • 1.169.0 (2025-03-10) — maintenance release, no component-specific changes
  • 1.155.0 (2025-01-23) — maintenance release, no component-specific changes
  • 1.154.0 (2025-01-17) — maintenance release, no component-specific changes
  • 1.149.0 (2024-12-19) — maintenance release, no component-specific changes
  • 1.144.0 (2024-12-03) — maintenance release, no component-specific changes
  • 1.138.1 (2024-10-30) — maintenance release, no component-specific changes
  • 1.103.1 (2024-04-24) — maintenance release, no component-specific changes
  • 1.102.0 (2024-04-16) — maintenance release, no component-specific changes
  • 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: 30 October 2026

Did this help?