PopoverMenu

Components/Overlays

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

Overview

Copy

A popover menu displays a list of actions when a user either clicks or hovers on a trigger element.

Do

  • Display a list of actions when there is not enough space to expose them right away.
  • Display secondary actions that are hidden to the user until clicked or hovered on.

Don't

  • Don't use it to explain the functions of an item. Instead, use <Popover/> or <Tooltip/>.
  • Don't use it to promote new features. Instead, use <FloatingHelper/>.
  • Don't use it to display a list of options. Instead, use <Dropdown/>.

Feature examples

Trigger element

Popover menus are opened by interacting with a trigger element. Common trigger elements are:

Copy

Trigger interaction

Popover menus are displayed when a trigger element is either clicked or hovered on.

Copy

Size

The size of menu items can be controlled using the textSize prop.

There are two sizes to choose from:

  • medium is the default used in common cases.
  • small should be used in dense layouts.
Copy

Skin

The appearance of each menu item can be controlled using the skin prop.

There are two skins to choose from:

  • dark should be used for all common cases.
  • destructive should be used to highlight destructive and permanent actions, e.g., deleting a contact.

Note: Destructive actions should be placed last in the menu.

Copy

Disabled

Actions that are unavailable to users at that time should be marked with the disabled prop.

Copy

Prefix

Icons can be added to menu items using the prefixIcon prop. It can help users identify actions quicker.

Note: small size popovers should use the small icon size, 18x18.

Copy

Subtitle

Add additional information that helps explain the purpose of a specific action using the subtitle prop.

Copy

Divider

Menu items can be organized into groups by adding a <PopoverMenu.Divider/> between them.

Copy

Placement

The placement of the menu in relation to the trigger element can be controlled using the placement prop.

There are four placement types to choose from:

  • top, top-start, top-end
  • right, right-start, right-end
  • bottom (default), bottom-start, bottom-end
  • left, left-start, left-end
Copy

Pointer arrow

By default, a pointer arrow is visible on the top edge of the menu, pointing to the trigger element. To remove the pointer, use the showArrow prop.

Copy

Text overflow

Define what happens with menu item text when it exceeds the popover maxWidth.

By default, text wraps into multiple lines. To limit menu item text to a single line, use the ellipsis prop. The full title is revealed in a tooltip on mouse hover.

To truncate a single item, set ellipsis on that PopoverMenu.MenuItem. An item's ellipsis overrides the menu's ellipsis for that item only.

Copy

Custom dimensions

Popover dimensions can be adjusted using the following props:

  • minWidth - sets the minimum pixel width (default: 144 px).
  • maxWidth - sets the maximum pixel width (default: 204 px).
  • maxHeight - sets the maximum pixel height. When the list of actions exceeds it, a scrollbar is visible.
Copy

Developer examples

Fluid

The trigger element can be resized to a specific container width using the fluid prop. Use it with ellipsis inside the trigger element to display the full label in a tooltip on hover.

Copy

Common use case examples

Secondary actions in widgets

The small size popover menu should be used in dense layouts and widgets. Irreversible actions should be highlighted with a destructive skin.

Copy

Secondary page actions

Popover menus can be used to display a list of secondary page actions.

Use <PopoverMenu.Divider/> to organize actions into groups.

To make sure action titles will not wrap to multiple lines, set the minWidth value to max-content.

Copy

Disabled action explanation

A subtitle should be used to explain disabled actions in a popover menu.

Copy

Code

Copy

Props

NameTypeDefaultDescription
appendTonull | Element | "window" | "scrollParent" | "viewport" | "parent" | Predicate'window'Enables calculations in relation to a DOM element.
boundaryPaddingnumber | { right?: number | undefined; left?: number | undefined; top?: number | undefined; bottom?: number | undefined; }5Sets the minimum distance, in pixels, to keep between a Popover menu 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. Use it to reserve space taken by fixed UI such as a bottom bar, so that the menu flips or shifts instead of opening underneath it.
childrenReactNode—Stores Popover menu compound components: - <PopoverMenu.MenuItem /> - <PopoverMenu.Divider /> (optional) - <PopoverMenu.SectionTitle /> (optional) <PopoverMenu.MenuItem> component has these fields: * text - Sets a label for a Popover menu item * onClick - Defines a callback function which is called when a Popover menu item is clicked on * skin - Controls the appearance of a Popover menu item (one of standard, dark, destructive) * prefixIcon - Contains an icon at the start of a Popover menu item * dataHook - Applies a data-hook HTML attribute to be used in the tests * suffixIcon - suffix icon property * disabled - Disables a Popover menu item * subtitle - Sets a text for a Popover menu item subtitle * ellipsis - Truncates the item's text and shows it in full in a tooltip on hover. Overrides PopoverMenu's ellipsis for this item only <PopoverMenu.Divider> component has these fields: * dataHook - Applies a data-hook HTML attribute to be used in the tests <PopoverMenu.SectionTitle> component has these fields: * dataHook - Applies a data-hook HTML attribute to be used in the tests * title - Acts as a title for following list items.
dataHookstring—Applies a data-hook HTML attribute to be used in the tests.
ellipsisbooleanfalseTruncates menu item text that overflows component's max Width.
fixedbooleantrueEnables the fixed behaviour. This behaviour is used to keep the overlay at its original placement even when it is being positioned outside the boundary.
fixedFooterReactNode—A fixed footer to the list.
flipbooleantrueEnables the flip behaviour. This behaviour is used to flip the overlay placement when it starts to overlap the trigger element.
fluidbooleanfalseAllows truncating the trigger element to a specified parent container width.
maxHeightstring | number'auto'Sets a maximum height for a Popover menu.
maxWidthstring | number | string & {}204Sets a maximum width for a Popover menu.
minWidthstring | number | string & {}144Sets a minimum width for a Popover menu. Sets a minimum width for the menu.
moveByMoveByOffset—Moves Popover menu overlay relative to its trigger element by a defined number of px: - horizontally (on X-axis) - or vertically (on Y-axis)
onHide() => void—Defines a callback function which is called when a Popover menu is closed.
onShow() => void—Defines a callback function which is called when a Popover menu is opened.
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'Defines the Popover menu's overlay placement in relation to its trigger element: * auto-start * auto * auto-end * top-start * top * top-end * right-start * right * right-end * bottom-start * bottom * bottom-end * left-start * left * left-end
refnull | string | (instance: PopoverMenuRefHandle | null) => void | RefObject<PopoverMenuRefHandle>—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).
showArrowbooleantrueControls visibility of the pointer arrow.
textSize"small" | "medium"'medium'Sets the size of text in Popover menu items.
triggerElement (required)ReactNode | FC<PopoverTriggerElementProps>—Defines a component that calls out a Popover menu (<IconButton />, <Button /> or <Text Button />)
zIndexnumber—Sets the Popover z-index.

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
existsReturns true of popoverMenu exists
getTriggerElementReturns trigger element
clickAtChildSelect a specific option by its index (requires the menu to be opened)
clickAtChildByDataHookSelect a specific option by its data-hook (requires the menu to be opened)
isMenuOpenReturn true if the menu is opened
childrenCountReturns children count
itemContentAtReturns text of <PopoverMenu.MenuItem/> of a specific index
isListItemFocused—
getContentElementReturns the content element (<Popover.Content/>)
elementGets the component root element.
clickClicks on the component root element.
baseReturns UniDriver for the base element.

Changelog

  • 1.341.0 (2026-10-22) — feat: new ellipsis prop on PopoverMenu.MenuItem truncates that item's text with a tooltip, overriding PopoverMenu's ellipsis for that item only. (#17584)
  • 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.0 (2026-09-28) — 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) — feat: opens with the motion-spec rise animation in Harmony (odeditor) and Studio 2.0 (odeditor-dark) — the panel and its content slide up into place (disabled under reduced motion); other themes keep the existing fade. PopoverNext: add transitionSettings.type: 'css' to drive the popover open/close transition from stylesheets instead of inline styles (DropdownBase passes transitionSettings through). (#16887)
  • 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-popover-menu* ones. (#16882)
  • 1.310.0 (2026-08-10) — maintenance release, no component-specific changes
  • 1.307.0 (2026-08-03) — fix: supported by WixDesignSystemDefaultPropsProvider, so its props can be defaulted from the provider. (#16715)
  • 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.276.0 (2026-05-04) — breaking: added background and backdrop-filter (#16229)
  • 1.272.0 (2026-04-27) — maintenance release, no component-specific changes
  • 1.260.0 (2026-03-17) — maintenance release, no component-specific changes
  • 1.258.0 (2026-02-23) — fix: default fixed to false (#15952)
  • 1.252.0 (2026-01-28) — fix: onhide event handler being fired when not needed (#15877)
  • 1.249.0 (2026-01-26) — feat: merge user ref with internal ref for trigger elements (#15835)
  • 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) — fix: add missing width property (#15627)
  • 1.235.0 (2025-12-04) — feat: add fixed footer (#15618)
  • 1.232.0 (2025-11-28) — fix: remove unnecessary onShow call (#15582)
  • 1.225.0 (2025-11-07) — maintenance release, no component-specific changes
  • 1.221.0 (2025-10-15) — fix: fix E3 PopoverMenu dropdown container overflow (#15409)
  • 1.212.0 (2025-08-11) — feat: add border-radius token (#15166)
  • 1.204.0 (2025-07-03) — maintenance release, no component-specific changes
  • 1.180.0 (2025-04-14) — maintenance release, no component-specific changes
  • 1.179.1 (2025-04-10) — maintenance release, no component-specific changes
  • 1.148.0 (2024-12-16) — fix: align minWidth/maxWidth prop types with DropdownBase (#14387)
  • 1.138.1 (2024-10-30) — maintenance release, no component-specific changes
  • 1.122.0 (2024-08-21) — breaking: don't use deprecated dark skin of ListItemAction internally (#14044)
  • 1.120.0 (2024-08-02) — feat: add 'standard' option to skin and make it the default. (#13996)
  • 1.115.0 (2024-07-17) — maintenance release, no component-specific changes
  • 1.103.3 (2024-04-30) — maintenance release, no component-specific changes
  • 1.103.1 (2024-04-24) — maintenance release, no component-specific changes
  • 1.103.0 (2024-04-23) — breaking: tokenization (#13614)
  • 1.102.0 (2024-04-16) — maintenance release, no component-specific changes
  • 1.94.0 (2024-02-14) — feat: add SectionTitle as possible menu item (#13278)
  • 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?