Popover

The Popover primitive is an overlay container used to render custom menus, tooltips, selection forms, or contextual popup widgets triggered by anchor buttons.

It's the free-form sibling of Menu — pick this when your popover content isn't a list of choices (e.g. a settings form, an inline editor, a color picker). The Menu primitive gives you list semantics for free; Popover doesn't, but neither does it lock you into one.

Use Popover when you want: an editor popovers anchored to a button, a colour picker palette, an inline + New widget, or any other content that doesn't fit the menu listbox model.

Import

import { Popover } from 'boltdocs/primitives'

Quick Start

A basic Popover implementation using React Aria trigger components:

import { DialogTrigger, Button } from 'react-aria-components'
import { Popover } from 'boltdocs/primitives'

export default function ConfigPopover() {
  return (
    <DialogTrigger>
      <Button className="px-4 py-2 bg-primary-500 text-white rounded-lg">
        Settings
      </Button>
      <Popover className="p-4 bg-surface border border-subtle rounded-xl shadow-xl max-w-sm">
        <div>
          <h4 className="font-bold mb-2">Workspace Config</h4>
          <p className="text-xs text-muted mb-4">Adjust project compiler flags and targets below.</p>
          <button className="px-3 py-1 bg-soft rounded text-xs font-semibold">Done</button>
        </div>
      </Popover>
    </DialogTrigger>
  )
}

Component Props

The Popover component wraps React Aria's Popover properties:

Pitfalls

• Popovers render inside a React portal. position: fixed works as expected; transform: translate(...) doesn't compose with React Aria's positioning math — use the placement / offset props instead.
• Focus trap is on by default. Use DialogTrigger (already in the example) — Popover alone is not a dialog and won't lock focus, so for interactive long-form content prefer <Dialog>.
• Clicks outside close the popover. Set isDismissable={false} if you want explicit close behaviour — but then Escape still closes it. React Aria consistency wins.