Popover

Components/Overlays

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

Overview

Copy

Popover is a structural component used for showing and positioning pop-ups and tooltips over a given element. It uses Popper.js as engine.

Do

  • Use it to build custom floating content attached to an element when no dedicated component fits.
  • Close it when users click outside it or press Escape, with the onClickOutside and onEscPress props.

Don't

  • Don't use it for short labels or explanations. Use <Tooltip/> instead.
  • Don't use it for a list of actions. Use <PopoverMenu/> instead.
  • Don't use it to introduce new features. Use <FloatingHelper/> instead.

Feature examples

appendTo="viewport"

This is similar to the default placement.

Copy

appendTo="parent"

If you inspect the content, you'll see it is attached to a new div next to the target element (the Button).

Copy

appendTo="scrollParent"

If you inspect the content, you'll see it is attached to a new div under the list container.

Copy

Interactive with appendTo="parent"

Copy

Non-Interactive with appendTo="window"

Copy

Interactive with appendTo="parent"

Copy

Non-Interactive with appendTo="window"

Copy

Flip enabled and placement="right"

Copy

Flip disabled and placement="right"

Copy

Fixed disabled (default) and placement="top"

Copy

Fixed enabled and placement="top"

Copy

Code

Copy

Props

NameTypeDefaultDescription
animateboolean—Whether to animate the popover content when it is shown or hidden.
appendTonull | Element | "window" | "scrollParent" | "viewport" | "parent" | Predicate—Enables calculations in relation to a dom element.
aria-describedbystring—
aria-labelstring—
aria-labelledbystring—
autoUpdateOptions{ animationFrame?: boolean | undefined; }—Options controlling how the popover keeps its position in sync with the trigger element while it is shown.
childrenReactNode—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.
dataHookstring—Hook for testing purposes.
disableClickOutsideWhenClosedbooleantrueBreaking change: When true, onClickOutside is called only when popover content is shown.
dynamicWidthboolean—popovers content is set to minimum width of trigger element, but it can expand up to the value of maxWidth.
excludeClassstring—Clicking on elements with this excluded class doesn't trigger the onClickOutside callback.
fixedboolean—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.
flipboolean—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/>).
flipModifierModifierFn—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).
fluidboolean—
hideDelaynumber—Hide Delay in ms.
idstring—Sets the id HTML attribute of the popover content element.
interactivebooleantrueEnables hovering the popover content.
maxWidthstring | number—popover content maxWidth value - number value which converts to css with px - string value that contains px
minWidthstring | number—popover content minWidth value - number value which converts to css with px - string value that contains px
moveArrowTonumber—Moves arrow by amount.
moveByPartial<{ x: number; y: number; }>—Moves popover relative to the parent.
onClickMouseEventHandler—onClick on the component.
onClickOutside(event: Event) => void—Provides callback to invoke when clicked outside of the popover.
onEscPressKeyboardEventHandler<HTMLDivElement>—Provides callback to invoke when popover loses focus.
onHide() => void—Callback to invoke when popover is hidden.
onKeyDownKeyboardEventHandler<HTMLDivElement>—onKeyDown on the target component.
onMouseEnterMouseEventHandler—onMouseEnter on the component.
onMouseLeaveMouseEventHandler—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.
overlayReactNode—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.
refnull | 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).
rolestring—Sets the role HTML attribute of the popover content element.
showArrowboolean—Show show arrow from the content.
showDelaynumber—Show Delay in ms.
shownboolean—Is the content shown or not.
skin"light" | "dark"—Components skin value. Can be dark or light.
styleobject—Applies inline styles to the root element of the component.
tabIndexnumber—tabindex for popover content element.
theme"light" | "dark"—Controls the color scheme of the popover content.
timeoutnumber | { 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.
widthstring | number—popover content width value - number value which converts to css with px - string value that contains px
zIndexstring & {} | "-moz-initial" | "inherit" | "initial" | "revert" | "revert-layer" | "unset" | "auto" | number & {}—Sets the z-index CSS property of the popover content.

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
clickClicks on the target element
getTargetElementGets the target element
isTargetElementExistsChecks whether target element exists
getPortalElementGets the portal element
getContentElementGets the content element
isContentElementExistsChecks whether content element exists
mouseEnterTriggers a mouseEnter event
mouseLeaveTriggers a mouseLeave event
clickOutsideClicks outside the target element (triggers mouseDown and mouseUp events)
getArrowOffsetGets the arrow offset
getContentElementUniDriverGets content as unidriver element
existsChecks whether the component found with the given data hook.
elementGets the component root element.
baseReturns UniDriver for the base element.

Changelog

  • 1.344.0 (2026-10-28) — maintenance release, no component-specific changes
  • 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.332.0 (2026-10-05) — maintenance release, no component-specific changes
  • 1.331.0 (2026-10-01) — maintenance release, no component-specific changes
  • 1.330.3 (2026-09-29) — maintenance release, no component-specific changes
  • 1.330.0 (2026-09-28) — maintenance release, no component-specific changes
  • 1.328.0 (2026-09-22) — maintenance release, no component-specific changes
  • 1.327.0 (2026-09-21) — feat: supported by WixDesignSystemDefaultPropsProvider — a Popover key in defaults now applies to every instance in the subtree, with instance props still winning. (#17120)
  • 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.320.1 (2026-09-04) — maintenance release, no component-specific changes
  • 1.317.0 (2026-08-26) — fix: render semantic 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)
  • 1.310.0 (2026-08-10) — maintenance release, no component-specific changes
  • 1.303.0 (2026-07-23) — 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.279.0 (2026-05-13) — feat: add autoUpdateOptions.animationFrame prop (#16261)
  • 1.278.0 (2026-05-08) — maintenance release, no component-specific changes
  • 1.272.0 (2026-04-27) — maintenance release, no component-specific changes
  • 1.267.0 (2026-04-09) — 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.256.1 (2026-02-10) — fix: clickoutside not working when old popover used with a new one (#15914)
  • 1.248.0 (2026-01-23) — feat: add flipModifier prop for custom flip logic (#15834)
  • 1.247.2 (2026-01-21) — maintenance release, no component-specific changes
  • 1.247.0 (2026-01-13) — maintenance release, no component-specific changes
  • 1.241.0 (2025-12-17) — maintenance release, no component-specific changes
  • 1.220.3 (2025-10-13) — fix: resolve bug in older floating-ui versions (#15400)
  • 1.220.0 (2025-09-29) — maintenance release, no component-specific changes
  • 1.213.0 (2025-08-19) — fix: react16 support (#15212)
  • 1.204.0 (2025-07-03) — maintenance release, no component-specific changes
  • 1.199.0 (2025-06-13) — maintenance release, no component-specific changes
  • 1.196.0 (2025-06-04) — feat: deprecate theme prop (#14942)
  • 1.165.0 (2025-02-27) — maintenance release, no component-specific changes
  • 1.156.0 (2025-01-29) — feat: reactive appendTo & appendTo prop type extension (#14484)
  • 1.155.0 (2025-01-23) — maintenance release, no component-specific changes
  • 1.145.0 (2024-12-09) — fix: trigger onClickOutside when popover is closed and disableClickOutsideWhenClosed is false (#14344)
  • 1.144.0 (2024-12-03) — maintenance release, no component-specific changes
  • 1.143.1 (2024-11-27) — maintenance release, no component-specific changes
  • 1.143.0 (2024-11-25) — maintenance release, no component-specific changes
  • 1.141.0 (2024-11-19) — maintenance release, no component-specific changes
  • 1.139.0 (2024-11-07) — maintenance release, no component-specific changes
  • 1.138.1 (2024-10-30) — maintenance release, no component-specific changes
  • 1.137.0 (2024-10-25) — maintenance release, no component-specific changes
  • 1.116.0 (2024-07-22) — maintenance release, no component-specific changes
  • 1.114.0 (2024-07-11) — maintenance release, no component-specific changes
  • 1.109.2 (2024-06-17) — maintenance release, no component-specific changes
  • 1.109.1 (2024-06-11) — maintenance release, no component-specific changes
  • 1.108.0 (2024-06-03) — 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?