Components/Overlays
Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/popover
Popover is a structural component used for showing and positioning pop-ups and tooltips over a given element. It uses Popper.js as engine.
<Tooltip/> instead.<PopoverMenu/> instead.<FloatingHelper/> instead.appendTo="viewport"This is similar to the default placement.
appendTo="parent"If you inspect the content, you'll see it is attached to a new div next to the target element (the Button).
appendTo="scrollParent"If you inspect the content, you'll see it is attached to a new div under the list container.
appendTo="parent"appendTo="window"placement="right"placement="right"placement="top"placement="top"| Name | Type | Default | Description |
|---|---|---|---|
animate | boolean | — | Whether to animate the popover content when it is shown or hidden. |
appendTo | null | Element | "window" | "scrollParent" | "viewport" | "parent" | Predicate | — | Enables calculations in relation to a dom element. |
aria-describedby | string | — | |
aria-label | string | — | |
aria-labelledby | string | — | |
autoUpdateOptions | { animationFrame?: boolean | undefined; } | — | Options controlling how the popover keeps its position in sync with the trigger element while it is shown. |
children | ReactNode | — | Sets the trigger and the content of the popover, as Popover.Element and Popover.Content elements. |
customArrow | (placement: Placement, arrowProps: object) => ReactNode | — | Custom arrow element. |
dataHook | string | — | Hook for testing purposes. |
disableClickOutsideWhenClosed | boolean | true | Breaking change: When true, onClickOutside is called only when popover content is shown. |
dynamicWidth | boolean | — | popovers content is set to minimum width of trigger element, but it can expand up to the value of maxWidth. |
excludeClass | string | — | Clicking on elements with this excluded class doesn't trigger the onClickOutside callback. |
fixed | boolean | — | Whether to enable the fixed behaviour. This behaviour is used to keep the <Popover/> at it's original placement even when it's being positioned outside the boundary. |
flip | boolean | — | Whether to enable the flip behaviour. This behaviour is used to flip the <Popover/>'s placement when it starts to overlap the target element (<Popover.Element/>). |
flipModifier | ModifierFn | — | Custom modifier function for the flip behavior. Receives Popper.js data object and should return the modified data. Use this to implement custom flip logic (e.g., flipping variations on the same side). |
fluid | boolean | — | |
hideDelay | number | — | Hide Delay in ms. |
id | string | — | Sets the id HTML attribute of the popover content element. |
interactive | boolean | true | Enables hovering the popover content. |
maxWidth | string | number | — | popover content maxWidth value - number value which converts to css with px - string value that contains px |
minWidth | string | number | — | popover content minWidth value - number value which converts to css with px - string value that contains px |
moveArrowTo | number | — | Moves arrow by amount. |
moveBy | Partial<{ x: number; y: number; }> | — | Moves popover relative to the parent. |
onClick | MouseEventHandler | — | onClick on the component. |
onClickOutside | (event: Event) => void | — | Provides callback to invoke when clicked outside of the popover. |
onEscPress | KeyboardEventHandler<HTMLDivElement> | — | Provides callback to invoke when popover loses focus. |
onHide | () => void | — | Callback to invoke when popover is hidden. |
onKeyDown | KeyboardEventHandler<HTMLDivElement> | — | onKeyDown on the target component. |
onMouseEnter | MouseEventHandler | — | onMouseEnter on the component. |
onMouseLeave | MouseEventHandler | — | onMouseLeave on the component. |
onShow | () => void | — | Callback to invoke when popover is shown. |
onTabOut | (event: KeyboardEvent) => void | — | Provides callback to invoke when popover loses focus. |
overlay | ReactNode | — | Enables overlay for content. |
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" | — | The location to display the content. |
ref | null | string | (instance: PopoverComponent | null) => void | RefObject<PopoverComponent> | — | Allows getting a ref to the component instance. Once the component unmounts, React will set ref.current to null (or call the ref with null if you passed a callback ref). |
role | string | — | Sets the role HTML attribute of the popover content element. |
showArrow | boolean | — | Show show arrow from the content. |
showDelay | number | — | Show Delay in ms. |
shown | boolean | — | Is the content shown or not. |
skin | "light" | "dark" | — | Components skin value. Can be dark or light. |
style | object | — | Applies inline styles to the root element of the component. |
tabIndex | number | — | tabindex for popover content element. |
theme | "light" | "dark" | — | Controls the color scheme of the popover content. |
timeout | number | { enter: number; exit: number; } | — | Sets the duration of the show and hide animations in milliseconds. Accepts a single number or an object with separate enter and exit values. |
width | string | number | — | popover content width value - number value which converts to css with px - string value that contains px |
zIndex | string & {} | "-moz-initial" | "inherit" | "initial" | "revert" | "revert-layer" | "unset" | "auto" | number & {} | — | Sets the z-index CSS property of the popover content. |
Import the driver matching your test environment:
| Method | Description |
|---|---|
click | Clicks on the target element |
getTargetElement | Gets the target element |
isTargetElementExists | Checks whether target element exists |
getPortalElement | Gets the portal element |
getContentElement | Gets the content element |
isContentElementExists | Checks whether content element exists |
mouseEnter | Triggers a mouseEnter event |
mouseLeave | Triggers a mouseLeave event |
clickOutside | Clicks outside the target element (triggers mouseDown and mouseUp events) |
getArrowOffset | Gets the arrow offset |
getContentElementUniDriver | Gets content as unidriver element |
exists | Checks whether the component found with the given data hook. |
element | Gets the component root element. |
base | Returns UniDriver for the base element. |
WixDesignSystemDefaultPropsProvider — a Popover key in defaults now applies to every instance in the subtree, with instance props still winning. (#17120)wds-popover* classnames on the root, trigger element, portal, content, and arrow alongside the existing Stylable classes, including the transition status (--status-open/--status-close) and resolved placement on the content wrapper. (#16899)Last updated: 30 October 2026