Popover

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>

Examples

Hover Trigger

Open popover on hover instead of click using the openOnHover prop.

With Backdrop

Add a backdrop overlay when popover is open for a modal-like experience.

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();

Passing data from the trigger to the popover

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.