WPDS - Popover | Components

Anatomy

Note: Image is not to scale

Content Container

Options

Positioning

The Popover can be positioned top, left, right, and bottom with each having ability to be positioned at the start, center, or end of the trigger.

Note: This option sets the preferred position of the popover to render against when open. Will be reversed when collisions occur with other elements.


Open in Playroom

Density

There are two options for the property density compact and default.


Open in Playroom

Offset

The property sideOffset can use any spacing token to offset its position from the origin point of the tooltip. The default offset is the spacing token 025.

Behavior

Avoids collisions

When close to the edge of the viewable area the side will be reversed to be visible.

Guidance

Popovers should not be used to display non-actionable ui that could otherwise live in something less persistent like a tooltip.


Open in Playroom

Do not nest Popovers or Tooltips

Popovers should not have additional tooltips or popovers within the same content container.


Open in Playroom

Accessibility

Keyboard controls

A Popover will show/hide without delay when the trigger is in focus and space/enter is selected on the keyboard. If the Popover is open and either shift+tab, or tab, is selected on the keyboard it will move focus to the next focusable element. When Esc is selected on the keyboard it will close the popover and move the focus to the trigger.

API Reference

PopoverAnchor

Prop	Description	Type	Default	Required
asChild		enum boolean	----	False
virtualRef		RefObject<Measurable>	----	False

PopoverClose

Prop	Description	Type	Default	Required
css	WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides.	CSS	----	False
asChild		enum boolean	----	False

PopoverContent

Prop	Description	Type	Default	Required
css	WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides.	CSS	----	False
sideOffset	Distance between trigger and content	enum number \| Token<200 \| 050 \| 025 \| 100 \| 125 \| 150 \| 175 \| 225 \| 250 \| 275 \| 300 \| 350 \| 400 \| 450 \| 500 \| 075 \| 087, string, space, wpds>	theme.space[025]	False
width	Width of the popover content	number	240	False
density		enum default \| compact	default	False
asChild		enum boolean	----	False
side		enum bottom \| left \| right \| top	----	False
align		enum center \| end \| start	----	False
alignOffset		number	----	False
arrowPadding		number	----	False
collisionBoundary		enum Element \| Element[]	----	False
collisionPadding		enum number \| Partial<Record<bottom \| left \| right \| top, number>>	----	False
sticky		enum always \| partial	----	False
hideWhenDetached		enum boolean	----	False
avoidCollisions		enum boolean	----	False
onEscapeKeyDown	Event handler called when the escape key is down. Can be prevented.	(event: KeyboardEvent) => void	----	False
onPointerDownOutside	Event handler called when the a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented.	(event: PointerDownOutsideEvent) => void	----	False
onFocusOutside	Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented.	(event: FocusOutsideEvent) => void	----	False
onInteractOutside	Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented.	(event: PointerDownOutsideEvent \| FocusOutsideEvent) => void	----	False
onOpenAutoFocus	Event handler called when auto-focusing on open. Can be prevented.	(event: Event) => void	----	False
onCloseAutoFocus	Event handler called when auto-focusing on close. Can be prevented.	(event: Event) => void	----	False
forceMount	Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.	true	----	False

PopoverPortal

Prop	Description	Type	Default	Required
forceMount	Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.	true	----	False
container		HTMLElement	----	False

PopoverRoot

Prop	Type	Default	Required
open	enum boolean	----	False
defaultOpen	enum boolean	----	False
onOpenChange	(open: boolean) => void	----	False
modal	enum boolean	----	False

PopoverTrigger

Prop	Description	Type	Default	Required
css	WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides.	CSS	----	False
asChild		enum boolean	----	False

Popover

Table of Contents