On this page
Popover
Headless, unstyled floating panel anchored to a trigger, non-modal by default. Wires role="dialog", the trigger’s aria-expanded and aria-controls, and focus on open and close.
Use for
- a floating panel of interactive content anchored to a button
- a filter or settings panel that leaves the page usable
- a nested popover inside another floating surface
Practices
| Guidance | Practice |
|---|---|
| Do | Render Popover.Title and Popover.Description. They label and describe the positioner only when present. |
| Do | Animate with data-starting-style and data-ending-style on Popover.Popup. Its children freeze on their last frame while it closes. |
| Do | Set initialFocus='first' when the content is meant to be typed into straight away. |
| Don’t | Pass id to Popover.Title or Popover.Description. The primitive owns both. |
| Don’t | Use it for a list of actions or hover-only hints. Use Menu or Tooltip instead. |
API reference
Popover.Root
Holds the open state, placement and dismissal. Renders no element.
| Prop | Type | Description |
|---|---|---|
open | boolean | Whether the popover is open, when controlled. |
defaultOpen | boolean | Whether the popover is open on mount, when uncontrolled.Default: false |
onOpenChange | (open: boolean) => void | Called with the new open state. |
placement | Placement | Where the popup sits against its anchor.Default: 'bottom' |
sideOffset | number | Gap to the anchor in px.Default: 4 |
alignOffset | number | Nudge along the alignment axis in px.Default: 0 |
modal | boolean | Traps focus inside the popup.Default: false |
initialFocus | 'auto' | 'first' | auto focuses the first tabbable on a keyboard open and the popup on a pointer open. first always focuses the first tabbable.Default: 'auto' |
Popover.Trigger
A button that toggles the popover. Carries data-open or data-closed.
Popover.Portal
Portals its children while the popover is mounted.
| Prop | Type | Description |
|---|---|---|
root | HTMLElement | null | React.RefObject<HTMLElement | null> | The element to portal into.Default: the `Portal` container |
Popover.Positioner
The floating div with role="dialog". Carries data-side and the --cl-anchor-*, --cl-available-* and --cl-transform-origin variables, and manages focus.
| Prop | Type | Description |
|---|---|---|
anchor | HTMLElement | null | Positions against this element instead of the trigger. |
Popover.Popup
Wraps the content. Carries data-open, data-closed, data-starting-style and data-ending-style.
Popover.Arrow
An optional FloatingArrow svg pointing at the anchor. Carries data-side.
Popover.Title
An h2 that labels the positioner.
Popover.Description
A p that describes the positioner.
Popover.Close
A button that closes the popover.
Examples
Settings panel
<Popover.Root>
<Popover.Trigger>Settings</Popover.Trigger>
<Popover.Positioner>
<Popover.Popup>
<Popover.Title>Preferences</Popover.Title>
<Popover.Close>Done</Popover.Close>
</Popover.Popup>
</Popover.Positioner>
</Popover.Root>