Popover

A popover floats rich, interactive content next to a trigger. Use it for notification panels, quick forms, or detail cards; for a plain hover label, use Tooltip, and for picking from a list bound to a form field, use Select.

Preview

Installation

npx shadcn@latest add @cubby-ui/popover

Usage


import {
  Popover,
  PopoverContent,
  PopoverTrigger,
  PopoverTitle,
  PopoverDescription,
} from "@/components/ui/cubby-ui/popover";


<Popover>
  <PopoverTrigger />
  <PopoverContent>
    <PopoverTitle />
    <PopoverDescription />
  </PopoverContent>
</Popover>

Composition


Popover
├── PopoverTrigger
└── PopoverContent
    ├── PopoverTitle
    └── PopoverDescription

PopoverContent composes the portal, positioner, popup, viewport, and optional arrow internally, so you place your content directly inside it.

Examples

Hover Trigger

Set openOnHover on Popover to open on hover instead of click.

With Backdrop

Render PopoverBackdrop for a dimmed overlay behind the open popover.

Detached Trigger

Use createPopoverHandle() to link a trigger outside the Popover component.

Animated Transitions

Animate the popover's position, size, and content when switching between multiple triggers with different payloads.

Controlled

Control the popover's open state externally using the open and onOpenChange props.

API Reference

The Popover component is built on top of Base UI's Popover. All Base UI props are supported. The documentation below only covers custom props and modified defaults specific to our implementation.

For the complete Base UI API, see the Base UI Popover documentation.

Utilities

createPopoverHandle

Creates a handle that connects a popover to one or more external PopoverTrigger components. Useful when the triggers need to live outside the Popover, for example when each row in a list has its own trigger but they all share one popover.


import { createPopoverHandle } from "@/registry/default/popover/popover";
 
const handle = createPopoverHandle();

The handle accepts an optional <Payload> generic that types a value each trigger can pass along. The popover reads it through a render-prop child, so you can render different content per trigger without duplicating the popover markup.


type User = { id: string; name: string };
 
const handle = createPopoverHandle<User>();
 
// Multiple triggers, each with its own payload:
users.map((user) => (
  <PopoverTrigger key={user.id} handle={handle} payload={user}>
    {user.name}
  </PopoverTrigger>
));
 
// One shared popover that renders based on the active trigger:
<Popover handle={handle}>
  <PopoverContent>
    {({ payload: user }) => <p>{user?.name}</p>}
  </PopoverContent>
</Popover>;

Without the <User> generic, payload inside the render prop resolves to unknown.

Props

PopoverContent

Composed component for common popover layouts. Combines Popover.Portal, Popover.Positioner, Popover.Popup, and Popover.Viewport. Optionally renders Popover.Arrow. Props are forwarded to the Positioner and Popup components.

Prop

Type

Default