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.
Density
There are two options for the property density compact and default.
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
Avoid using popover for non-actionable ui
Popovers should not be used to display non-actionable ui that could otherwise live in something less persistent like a tooltip.
Do not nest Popovers or Tooltips
Popovers should not have additional tooltips or popovers within the same content container.
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 | 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 | 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 | number | Token<"100" | "125" | "150" | "175" | "200" | "225" | "250" | "275" | "300" | "350" | "400" | "450" | "500" | "075" | "087" | "025" | "050", string, "space", "wpds"> | theme.space[025] | False |
| width | Width of the popover content | number | 240 | False |
| density | "default" | "compact" | ({ "@reducedMotion"?: "default" | "compact"; "@sm"?: "default" | "compact"; "@md"?: "default" | "compact"; "@lg"?: "default" | "compact"; "@xl"?: "default" | "compact"; ... 19 more ...; "@initial"?: "default" | "compact"; } & { ...; }) | default | False | |
| sticky | "always" | "partial" | ---- | False | |
| asChild | boolean | ---- | False | |
| side | "bottom" | "left" | "right" | "top" | ---- | False | |
| align | "center" | "end" | "start" | ---- | False | |
| alignOffset | number | ---- | False | |
| arrowPadding | number | ---- | False | |
| avoidCollisions | boolean | ---- | False | |
| collisionBoundary | Element | Element[] | ---- | False | |
| collisionPadding | number | Partial<Record<"bottom" | "left" | "right" | "top", number>> | ---- | False | |
| hideWhenDetached | boolean | ---- | False | |
| updatePositionStrategy | "always" | "optimized" | ---- | 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 |
|---|---|---|---|---|
| container | Specify a container element to portal the content into. | HTMLElement | ---- | False |
| forceMount | Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries. | true | ---- | False |
PopoverRoot
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| open | boolean | ---- | False | |
| defaultOpen | boolean | ---- | False | |
| onOpenChange | (open: boolean) => void | ---- | False | |
| modal | 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 | boolean | ---- | False |