Components/Overlays
Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/popovermenu
A popover menu displays a list of actions when a user either clicks or hovers on a trigger element.
<Popover/> or <Tooltip/>.<FloatingHelper/>.<Dropdown/>.Popover menus are opened by interacting with a trigger element. Common trigger elements are:
<Button/><Text Button/><IconButton/>Popover menus are displayed when a trigger element is either clicked or hovered on.
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.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.
Actions that are unavailable to users at that time should be marked with the disabled prop.
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.
Add additional information that helps explain the purpose of a specific action using the subtitle prop.
Menu items can be organized into groups by adding a <PopoverMenu.Divider/> between them.
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-endright, right-start, right-endbottom (default), bottom-start, bottom-endleft, left-start, left-endBy 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.
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.
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.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.
The small size popover menu should be used in dense layouts and widgets. Irreversible actions should be highlighted with a destructive skin.
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.
A subtitle should be used to explain disabled actions in a popover menu.
| Name | Type | Default | Description |
|---|---|---|---|
appendTo | null | Element | "window" | "scrollParent" | "viewport" | "parent" | Predicate | 'window' | Enables calculations in relation to a DOM element. |
boundaryPadding | number | { right?: number | undefined; left?: number | undefined; top?: number | undefined; bottom?: number | undefined; } | 5 | Sets 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. |
children | ReactNode | — | 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. |
dataHook | string | — | Applies a data-hook HTML attribute to be used in the tests. |
ellipsis | boolean | false | Truncates menu item text that overflows component's max Width. |
fixed | boolean | true | Enables the fixed behaviour. This behaviour is used to keep the overlay at its original placement even when it is being positioned outside the boundary. |
fixedFooter | ReactNode | — | A fixed footer to the list. |
flip | boolean | true | Enables the flip behaviour. This behaviour is used to flip the overlay placement when it starts to overlap the trigger element. |
fluid | boolean | false | Allows truncating the trigger element to a specified parent container width. |
maxHeight | string | number | 'auto' | Sets a maximum height for a Popover menu. |
maxWidth | string | number | string & {} | 204 | Sets a maximum width for a Popover menu. |
minWidth | string | number | string & {} | 144 | Sets a minimum width for a Popover menu. Sets a minimum width for the menu. |
moveBy | MoveByOffset | — | 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 |
ref | null | 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). |
showArrow | boolean | true | Controls 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 />) |
zIndex | number | — | Sets the Popover z-index. |
Import the driver matching your test environment:
| Method | Description |
|---|---|
exists | Returns true of popoverMenu exists |
getTriggerElement | Returns trigger element |
clickAtChild | Select a specific option by its index (requires the menu to be opened) |
clickAtChildByDataHook | Select a specific option by its data-hook (requires the menu to be opened) |
isMenuOpen | Return true if the menu is opened |
childrenCount | Returns children count |
itemContentAt | Returns text of <PopoverMenu.MenuItem/> of a specific index |
isListItemFocused | — |
getContentElement | Returns the content element (<Popover.Content/>) |
element | Gets the component root element. |
click | Clicks on the component root element. |
base | Returns UniDriver for the base element. |
ellipsis prop on PopoverMenu.MenuItem truncates that item's text with a tooltip, overriding PopoverMenu's ellipsis for that item only. (#17584)transitionSettings.type: 'css' to drive the popover open/close transition from stylesheets instead of inline styles (DropdownBase passes transitionSettings through). (#16887)wds-popover-menu* ones. (#16882)WixDesignSystemDefaultPropsProvider, so its props can be defaulted from the provider. (#16715)fixed to false (#15952)Last updated: 30 October 2026