Popover
Show anchored interactive content from click or hover.
Anatomy#
Content is portaled inside an internal positioning wrapper.
Usage#
Use Popover for anchored interactive content that does not need a labeled modal surface. Use Tooltip for a brief, non-interactive hint. Use DropdownMenu for a compact action list from a visible trigger. Use Dialog or Sheet when the task should take over the page. Use BaseDialog to compose backdrop and content yourself.
Trigger modes and state#
Click toggles the popover by default. openOnHover opens it when a mouse pointer enters the
trigger or the trigger receives keyboard focus, and closes it closeDelay ms after the pointer or
focus leaves the trigger and content (openDelay and closeDelay default to 100). With
openOnHover, clicking the trigger only opens the popover, touch hover is ignored, outside focus
no longer dismisses the content, and focus is not restored to the trigger on close unless
finalFocus is set. Use controlled open state when the application coordinates
visibility.
Placement#
placement chooses the side of the trigger (top, right, bottom, or left; default
bottom), and align lines the content up with the trigger edge (start, center, or end;
default center). gutter sets the gap to the trigger in pixels, and overflowPadding the
minimum distance from the viewport edge (both default to 4). By default, the content moves to
another side when placement does not fit (flip; false keeps the side fixed) and slides along
the trigger edge to stay in the viewport (slide). Read the rendered side from data-side on the
content.
Dismissal and accessibility#
Escape and outside interaction close a popover. Closing restores focus to the trigger, except after
an outside press or focus move, where focus has already gone elsewhere. Give Popover.Content an
accessible name with aria-label when it has no visible label.
modal defaults to false. With modal={true} and a composed Popover.Close, focus stays inside
the content, outside content is hidden from assistive technology, and body scroll is locked.
Without a Close, the popover stays non-modal so users retain a dismissal route, and development
builds log a warning.
modal={false} does not disable Escape or outside dismissal; closeOnEscape and
closeOnOutsideClick control them independently. preventScroll can lock body scroll
independently of modal.
Keyboard interaction#
Keyboard behavior depends on the trigger element and whether the popover is modal. Escape requests
dismissal when closeOnEscape allows it; focusable controls inside non-modal content participate
in normal document focus order. Modal content contains focus. With openOnHover, Tab from the
last control in the content moves to the next focusable element after the trigger, and
Shift+Tab from the first control returns to the trigger.
Examples#
Filter deployments or preview a profile#
Click keeps a filter panel open during selection. openOnHover opens an author preview after a delay.
Label filter settings for dismissal#
Give content an accessible name when it has no visible title. Escape or an outside click closes the popover.
Preview an author card on hover#
Hover or focus the trigger to follow an author. Open and close delays keep the card from flashing.
Keep a popover open until an explicit close#
closeOnEscape={false} and closeOnOutsideClick={false} block Escape and outside clicks.
onClosePrevented counts blocked attempts.
API Reference#
Attributes#
data-closeddata-disableddata-expandeddata-aligndata-sideProps#
Popover#
Trigger#
Renders a <button> element by default.
Content#
Props for the Popover component. Renders a <div> element by default.
Close#
Renders a <button> element by default.