Skip to content
Mosaic
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

GuidancePractice
DoRender Popover.Title and Popover.Description. They label and describe the positioner only when present.
DoAnimate with data-starting-style and data-ending-style on Popover.Popup. Its children freeze on their last frame while it closes.
DoSet initialFocus='first' when the content is meant to be typed into straight away.
Don’tPass id to Popover.Title or Popover.Description. The primitive owns both.
Don’tUse 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.

PropTypeDescription
openbooleanWhether the popover is open, when controlled.
defaultOpenbooleanWhether the popover is open on mount, when uncontrolled.Default: false
onOpenChange(open: boolean) => voidCalled with the new open state.
placementPlacementWhere the popup sits against its anchor.Default: 'bottom'
sideOffsetnumberGap to the anchor in px.Default: 4
alignOffsetnumberNudge along the alignment axis in px.Default: 0
modalbooleanTraps 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.

PropTypeDescription
rootHTMLElement | 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.

PropTypeDescription
anchorHTMLElement | nullPositions 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

TSX
<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>