API and Development
Popover displays floating content anchored to a trigger element, useful for tooltips, menus, forms, or additional information that appears on demand. It provides a flexible floating content interface that positions itself relative to a trigger element, supporting various positioning options and interaction patterns. Built on Radix UI's Popover component, it ensures consistent popover patterns across the interface with full keyboard and screen reader accessibility.
| Name | Default | Description |
|---|---|---|
children | required | Popover components (PopoverTrigger, PopoverContent, etc.). |
open | Whether the popover is open (controlled component). | |
onOpenChange | Callback function called when the popover open state changes: (open: boolean) => void. | |
preventOutsideClose | false | Whether to prevent the popover from closing when clicking outside. |
| Name | Default | Description |
|---|---|---|
children | required | The element that triggers the popover when clicked. |
| Name | Default | Description |
|---|---|---|
children | required | The content to display inside the popover. |
side | PopoverContentSide.Bottom | The side of the trigger where the popover appears. Options: Top, Bottom, Left, Right. |
avoidCollisions | true | When false, keeps the requested side even when space is limited. |
collisionPadding | 0 | Distance in pixels from the collision boundary edges. Accepts a number or a partial { top, right, bottom, left } object. |
collisionBoundary | viewport | Element or array of elements treated as obstacles when avoidCollisions is true. Pass an open drawer so the popover flips/shifts around it. |
sideOffset | 4 | Distance in pixels between the trigger and popover. |
align | PopoverContentAlign.Center | Alignment of the popover relative to the trigger. Options: Start, Center, End. |
alignOffset | 0 | Additional offset in pixels for alignment adjustment. |
container | Custom container element for the popover portal. Defaults to PopoverManager or document.body. | |
onOpenAutoFocus | Callback function called when the popover opens and focus is automatically set: (event: Event) => void. | |
onEscapeKeyDown | Callback when Escape is pressed while open: (event: Event) => void. |
| Name | Default | Description |
|---|---|---|
children | required | The element that closes the popover when clicked. |
| Name | Default | Description |
|---|---|---|
children | required | The anchor element for positioning. |
asChild | false | Whether to merge props with the child element. |
virtualRef | Virtual reference for custom positioning: React.RefObject<{ getBoundingClientRect: () => DOMRect }>. |
PopoverAnchor uses the Radix UI Popover primitive (not Themes Popover.Anchor) so it can nest under a Themes Popover.Root while positioning content relative to a non-trigger surface—for example a multi-select chips field that opens from focus or typing rather than a dedicated trigger button.
Use for simple content overlays triggered by user interaction.
sideOffset is a space step (0, 4, 8, 12, 16, 20, or 24); the annotation popover uses 20. Outside dismiss that must skip a marker or a portaled menu uses isOutsideExempt(target) instead of ignoreOutsideCloseSelector. The platform reports an outside press as light-dismiss, and that change is not cancelable, so details.cancel() does not keep the popover open. A press the predicate accepts stays open; Escape still closes and returns focus to the trigger.
Include PopoverManager in your application to enable proper popover rendering.