Popover

An anchored panel for content and controls.

Preview

Design guidance

Use an anchored panel for related content, settings or a short form. Give the panel a title. Keep long content in a scrollable child region so the arrow, title and actions remain visible. Use Tooltip for a brief noninteractive hint.

Installation

Install

npx shadcn@latest add https://ghost-ui.com/r/popover.json

Basic usage

123456789101112131415import { Popover } from "@/components/ui/popover";

<Popover.Root>
  <Popover.Trigger>Share conversation</Popover.Trigger>
  <Popover.Portal>
    <Popover.Positioner>
      <Popover.Popup>
        <Popover.Arrow />
        <Popover.Title>Share conversation</Popover.Title>
        <Popover.Description>Anyone with the link can view.</Popover.Description>
        <Popover.Close aria-label="Close sharing" />
      </Popover.Popup>
    </Popover.Positioner>
  </Popover.Portal>
</Popover.Root>

Structures

Examples

Change link access and copy the current example link. Feedback follows the actual clipboard result.

Top

Choose a preferred side; Base UI avoids viewport collisions.

Right

Use the same arrow and surface on each side.

Bottom

The arrow remains attached when positioning changes.

Left

Keep sufficient room for the panel.

Comment form

Submit a local comment through Field, Textarea and Button; Escape or Close dismisses the panel.

Constrained members

Only the member list scrolls; the arrow, header and copy action remain outside it.

Controlled open

The caller owns the open value and onOpenChange callback.

API reference

Popover properties
Prop	Type	Default	Description
`Root.open / defaultOpen / onOpenChange`	`boolean / boolean / callback`	`uncontrolled, initially closed`	Keeps Base UI controlled and uncontrolled behavior.
`Trigger.render / ref`	`ReactElement \| render function / ref`	`canonical Button`	Caller render wins. The ref points to the trigger button.
`Positioner.side / align`	`Side / "start" \| "center" \| "end"`	`"bottom" / "center"`	The resolved side can change to avoid collisions.
`Positioner.sideOffset / alignOffset / arrowPadding`	`number or supported offset function / number`	`8 / 0 / 5`	Positioner owns placement and the arrow gap.
`Popup.className / style / ref`	`Base UI popup props`	`one canonical surface`	State callbacks, refs and render composition remain available.
`Arrow`	`Base UI Arrow props`	`decorative SVG`	Renders a real arrow and follows the resolved side. Custom children/render are supported.
`Root.modal`	`false \| true \| "trap-focus"`	`false`	Use Base UI modality when the task requires it.
`Popup.initialFocus / finalFocus`	`Base UI focus props`	`Base UI behavior`	Choose initial focus and restore focus without reimplementing keyboard behavior.
`Title / Description`	`heading / paragraph props`	`13px medium / 12px muted`	Preserves Base UI label and description associations.
`Close.render`	`ReactElement \| render function`	`IconButton, accessible name Close`	Caller render and accessible name override the default. Render a text Button for a text close action.

Advanced handles, detached triggers and additional parts follow Base UI Popover.