Popover

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

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.

Props

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.

PopoverTrigger

Name	Default	Description
`children`	`required`	The element that triggers the popover when clicked.

PopoverContent

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`.

PopoverClose

Name	Default	Description
`children`	`required`	The element that closes the popover when clicked.

PopoverAnchor

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.

Use popovers for contextual forms or input fields.

Use popovers for contextual menus or option lists.

Positioning

Control where the popover appears relative to the trigger.

Side Positioning

Position the popover on different sides of the trigger.

Alignment

Control how the popover aligns with the trigger.

Custom Offsets

Adjust spacing using offset props.

Control popover state programmatically.

Prevent the popover from closing when clicking outside.

Include a close button within the popover content.

Custom Trigger

Use any element as a trigger, including custom components.

Virtual Anchor

Use a virtual anchor for fixed positioning or custom placement.

Prevent Auto Focus

Control focus behavior when the popover opens.

The design-system popover is not a path-only rewrite of this page. 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.

Put ToolbarItem outside PopoverTrigger, with Popover wrapping both the item and PopoverContent. PopoverTrigger forwards the item's roving props to the control child.

PopoverManager Setup

Include PopoverManager in your application to enable proper popover rendering.

Popover / Usage

Accessibility / Keyboard Support