Components/Form/DropdownBase
Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/dropdownbase
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.
<Dropdown/> instead.<PopoverMenu/> instead.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.`
Call out a popover on click or hover interactions.
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.
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.
Control the popover arrow visibility with the `showArrow` prop. It's not displayed by default.
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.
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.
Create smooth transitions by adding enter and exit animations to the popover with the `animate` prop.
Use DropdownBase to build custom filters for page or card content.
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.
| Name | Type | Default | Description |
|---|---|---|---|
animate | boolean | false | Adds enter and exit animation. |
appendTo | null | Element | "window" | "scrollParent" | "viewport" | "parent" | Predicate | 'parent' | Specifies where popover should be inserted as a last child - whether parent or window containers. |
autoFocus | boolean | — | Specifies whether first list item should be focused. |
boundaryPadding | number | { right?: number | undefined; left?: number | undefined; top?: number | undefined; bottom?: number | undefined; } | 5 | Sets 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. |
children | null | 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. |
dataHook | string | — | Applies a data-hook HTML attribute that can be used in the tests. |
dynamicWidth | boolean | true | Set popover's content width to a minimum width of a trigger element, but it can expand up to the defined value of maxWidth |
fixed | boolean | — | Specifies whether to enable the fixed behaviour. If enabled, |
fixedFooter | ReactNode | — | A fixed footer to the list. |
fixedHeader | ReactNode | — | A fixed header to the list. |
flip | boolean | — | Specifies whether to flip the |
fluid | boolean | false | Stretches trigger element to fill its parent container width. |
focusOnOption | string | number | — | Focus to the specified option when dropdown is opened. |
focusOnSelectedOption | boolean | — | Focus to the selected option when dropdown is opened. |
hasMore | boolean | — | Specifies whether there are more items to load. |
infiniteScroll | boolean | — | Specifies whether lazy loading of the dropdown items is enabled. |
initialSelectedId | string | 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. |
markedOption | string | 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 |
maxHeight | string | number | '260px' | Controls the maximum height of dropdown layout. |
maxWidth | string | number | string & {} | — | Controls the maximum width of dropdown layout. |
minWidth | string | number | string & {} | 192 | Controls the minimum width of dropdown layout. |
moveBy | MoveByOffset | — | 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. |
onMouseDown | MouseEventHandler | — | 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. |
open | boolean | — | Control whether the |
options | DropdownLayoutOption[] | — | 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. |
scrollToOption | string | number | — | Scrolls to the specified option when dropdown is opened without marking it. |
selectedId | string | number | — | Define the selected option in the list. |
showArrow | boolean | false | Specifies whether popover arrow should be shown. |
tabIndex | number | — | 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. |
zIndex | number | — | Specifies the stack order (z-index) of a dropdown layout. |
Import the driver matching your test environment:
| Method | Description |
|---|---|
getListType | Returns the list type prop value |
clickTargetElement | Returns the target element |
hoverTargetElement | Hover the target element |
isDropdownShown | Returns true if the dropdown is being shown |
selectOption | Select a specific option (requires the DropdownBase to be opened) |
selectOptionByDataHook | Select a specific option by its data hook (requires the DropdownBase to be opened) |
clickOutside | Click outside of the component |
optionsCount | Options count (requires the DropdownBase to be opened) |
optionContentAt | — |
getSelectedOptionId | Returns the selected option (requires the DropdownBase to be opened) |
getMarkedOption | Returns the marked option (requires the DropdownBase to be opened) |
mouseEnter | — |
mouseLeave | — |
exists | Checks whether the component found with the given data hook. |
element | Gets the component root element. |
click | Clicks on the component root element. |
base | Returns UniDriver for the base element. |
wds-dropdown-base* ones. (#16884)autoFocus=false correctly prevents focusing (#15519)Last updated: 30 October 2026