Skip to content
Mosaic
On this page

Popover

A floating box anchored to a trigger, for content that is not a list of actions. The popup paints no surface of its own.

Use for

  • a small floating panel opened from a button
  • a picker or form in a floating box

Practices

GuidancePractice
DoPut a surface inside Popover.Popup, usually a Card.
DoName the popup: render a Popover.Title, or pass aria-label or aria-labelledby to Popover.Popup. A dev warning fires otherwise.
DoPass initialFocus='first' when the content is typed into at once, such as a search.
Don’tUse it for a list of actions. Use Menu instead.
Don’tUse it for a hint on hover. Use Tooltip instead.

API reference

Popover.Root

Holds the open state and placement. Renders no element.

PropTypeDescription
openbooleanWhether the popover is open, when controlled.
defaultOpenbooleanWhether it starts open, when uncontrolled.Default: false
onOpenChange(open: boolean) => voidCalled with the new open state.
placement'top' | 'right' | 'bottom' | 'left' | 'top-start' | 'top-end' | 'right-start' | 'right-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end'Side and alignment against the trigger or anchor.Default: 'bottom'
sideOffsetnumberGap from the trigger, in px.Default: 4
alignOffsetnumberShift along the trigger edge, in px.Default: 0
modalbooleanTraps focus inside the popup.Default: false
initialFocus'auto' | 'first'auto focuses the first tabbable element after a key press and the popup after a pointer press. first always focuses the first tabbable element.Default: 'auto'

Popover.Trigger

A button that toggles the popover. Pass render to use a Button.

Slot: cl-popover-trigger

Popover.Popup

Portals and positions the content. Resets Button defaults from any group around the trigger.

Slot: cl-popover-popup

PropTypeDescription
sizePopoverSizeWidth: sm, md, lg, or anchor to match the anchor width.Default: 'md'
anchorHTMLElement | nullPositions against this element instead of the trigger.
aria-labelstringThe popup name. Needed unless the content renders a Popover.Title.

Popover.Title

An h2 that names the popup.

Popover.Description

A p that describes the popup.

Popover.Close

A button that closes the popover.

Examples

A popover with a card

TSX
<Popover.Root>
  <Popover.Trigger render={props => <Button {...props} />}>Filters</Popover.Trigger>
  <Popover.Popup>
    <Card.Root>
      <Popover.Title>Filters</Popover.Title>
      …
    </Card.Root>
  </Popover.Popup>
</Popover.Root>