A non-modal React popover with a Liquid Glass panel anchored to a trigger.
Popover renders the trigger, portal, positioner, glass popup, directional arrow, title, description, optional body, and optional action area internally. The arrow follows the resolved side of the popup automatically; set arrow={false} to hide it.
Unlike Dialog and Drawer, Popover is non-modal by default: focus is not trapped, the page stays scrollable, and pressing outside or Escape closes it. Use it for compact settings, contextual actions, and filters.
Pass one element as trigger. It must forward props and refs to its root element, as Button does. The component adds aria-haspopup="dialog" and aria-expanded to the trigger automatically, and clicking it toggles the popover. This example is uncontrolled.
open and onOpenChange control visibility. Footer buttons do not close the popover automatically; update open yourself as the example does.
No release published.
side, align, sideOffset, and alignOffset control the popup position. The popup flips or shifts when it would overflow the viewport.
align, alignOffset, and collisionPadding fine-tune the position after the preferred side is chosen. Set arrow={false} when the popup should sit flat against its trigger.
Popover adds aria-haspopup="dialog" and aria-expanded to the trigger and renders a popup named by title and described by description.
It is non-modal by default: focus is not trapped, the page stays scrollable, and Escape or an outside press closes it. Provide a visible close or done action when the popup changes settings. The modal prop cannot enable focus trapping with this wrapper: Base UI only does that when a Popover.Close part is rendered, and the component does not render one. modal={true} still locks page scroll and blocks outside interaction. See the accessibility guide for focus rules.
| Prop | Type | Default | Description |
|---|---|---|---|
trigger | ReactElement | — | Element that opens the popover. Required. It must forward props and refs. |
title | ReactNode | — | Popover heading. Required. |
description | ReactNode | — | Supporting copy under the title. |
children | ReactNode | — | Body content between the description and the action area. |
footer | ReactNode | — | Bottom action area that can hold any number of controls. |
arrow | boolean | true | Whether to render the directional arrow. |
side | "top" | "bottom" | "left" | "right" | "inline-start" | "inline-end" | "bottom" | Preferred side of the trigger. |
align | "start" | "center" | "end" | "center" | Alignment relative to the trigger. |
sideOffset | number | OffsetFunction | 10 | Distance between the trigger and the popup in pixels. |
alignOffset | number | OffsetFunction | 0 | Offset along the alignment axis in pixels. |
collisionPadding | Padding | 5px per side | Space kept between the popup and the collision boundary. |
open | boolean | — | Controlled open state. |
defaultOpen | boolean | false | Initial open state when uncontrolled. |
onOpenChange | (open: boolean, details) => void | — | Called when the popover opens or closes. |
onOpenChangeComplete | (open: boolean) => void | — | Called after the open or close animation finishes. |
modal | boolean | "trap-focus" | false | true locks page scroll and blocks outside interaction; "trap-focus" leaves scroll and outside interaction enabled. Neither traps focus because the component does not render a Popover.Close part. |
actionsRef | RefObject<Actions | null> | — | Imperative close and unmount actions. |
handle | PopoverHandle | — | Associates the popover with external triggers. |
triggerId | string | null | — | ID of the trigger associated with the popover. |
defaultTriggerId | string | null | — | ID of the trigger used for an initially open popover. |
className | string | — | Tailwind classes merged into the popup. |
style | CSSProperties | — | Inline styles merged into the same element as className. |
ui | { positioner?: ClassValue; popup?: ClassValue; glass?: ClassValue; overlay?: ClassValue; arrow?: ClassValue; content?: ClassValue; title?: ClassValue; description?: ClassValue; body?: ClassValue; footer?: ClassValue } | — | Tailwind classes for internal slots, keyed by data-slot. |
| Attribute | Description |
|---|---|
data-open | Present when the popup is open. |
data-closed | Present when the popup is closed. |
data-starting-style | Present when the popup begins animating in. |
data-ending-style | Present when the popup is animating out. |
data-side | Indicates the resolved side (top, bottom, left, right, inline-start, or inline-end). |
data-align | Indicates the resolved alignment (start, center, or end). |
data-instant | Present when animations should be skipped (click, dismiss, focus, or trigger-change). |
data-anchor-hidden | Present when the anchor is hidden. |
data-uncentered | Present when the arrow is uncentered. |
data-popup-open | Present on the trigger while the popup is open. |
data-pressed | Present while the trigger is pressed. |
data-slot | Marks internal parts (positioner, popup, glass, overlay, arrow, content, title, description, body, footer) for styling. |
The component uses the shared glass material. Tune shared --ui-glass-* tokens on a parent, use className for layout, and use ui for internal slots keyed by data-slot. Component-specific values live in src/theme/popover.ts. See the theming guide for token layers and presets.