BetaOverlays

Popover

A panel anchored to whatever opened it. The component the Select was written before: the two share their positioning, their measuring pass and their entrance.

Source Markdown

Overview

A panel anchored to whatever opened it. The component the Select was written before: the two share their positioning, their measuring pass and their entrance.

First example

<Popover>
  <Popover.Trigger asChild>
    <Button variant="tertiary">Détails</Button>
  </Popover.Trigger>
  <Popover.Overlay />
  <Popover.Content placement="top">
    <Popover.Title>Livraison</Popover.Title>
    <Popover.Description>Sous trois jours ouvrés.</Popover.Description>
  </Popover.Content>
</Popover>

Anatomy

<Popover>
  <Popover.Trigger>…</Popover.Trigger>
  <Popover.Overlay />
  <Popover.Content>
    <Popover.Title>…</Popover.Title>
    <Popover.Description>…</Popover.Description>
    <Popover.Close>…</Popover.Close>
  </Popover.Content>
</Popover>

Popover — state and resolved style. It renders no node.
Popover.Trigger — what opens the panel, and the rectangle it anchors to.
Popover.Overlay — the backdrop. Optional, and what closes the panel on a press outside.
Popover.Content — the panel, positioned against the trigger, in a portal.
Popover.Title / Popover.Description — its two texts.
Popover.Close — anything that closes it.

Popover.Overlay and Popover.Content render into the nearest PortalHost rather than where they are written. Their place in the JSX says when they exist, not where they appear.

Usage

Basic

<Popover>
  <Popover.Trigger asChild>
    <Button variant="tertiary">Détails</Button>
  </Popover.Trigger>
  <Popover.Overlay />
  <Popover.Content placement="top">
    <Popover.Title>Livraison</Popover.Title>
    <Popover.Description>Sous trois jours ouvrés.</Popover.Description>
  </Popover.Content>
</Popover>

asChild is the normal way to write the trigger. It paints nothing of its own — a popover's trigger is usually a Button, an Icon or a word in a sentence, and giving it a surface would put a second box around one of those.

Placement

<Popover.Content placement="end" align="start" offset={12} width={280} />

placement takes all four sides, which is what separates this from Select.Content. A select's list is as wide as the field it drops out of, and one hanging off the side of that field reads as a menu; a popover belongs to nothing, so it can sit anywhere.

align runs along the axis the side does not pin — horizontal for a panel above or below, vertical for one beside — and clamps to the screen insets.

avoidCollisions is on by default and flips to the opposite side, but only when that side has strictly more room. A panel two points short stays where it was asked, because a flip on a near miss reads as a glitch.

Both axes are clamped to the insets, whether or not it flips. The side decides where the panel wants to go; the insets decide where it is allowed to be. A panel beside a trigger with no room for it is pushed inside the screen and may overlap the trigger — which is the right trade: a panel covering the button that opened it is legible, and a panel past the edge of the screen is not.

No backdrop

Omit Popover.Overlay and nothing captures the press outside: a Popover.Close, or your own state, is what closes the panel. That is the answer for a popover inside a sheet that already dims its background.

Controlled

const [isOpen, setOpen] = useState(false)

<Popover isOpen={isOpen} onOpenChange={setOpen}>…</Popover>

Style as props

<Popover.Content padding={20} backgroundColor="#111" />
<Popover.Title fontSize={22} />

Full RN names, full RN values (R14). Every node takes them.