Popover
A floating panel anchored to a trigger element.
Installation
$
npx shadcn@latest add https://ui.mattdowney.com/r/popover.jsonUsage
import { Popover, PopoverTrigger, PopoverContent, PopoverHeader, PopoverTitle, PopoverDescription } from "@/components/ui/popover"Examples
Default
A floating panel anchored to its trigger, closed by clicking outside or pressing Escape. PopoverTitle and PopoverDescription label the panel for screen readers; give PopoverContent a width.
Anchored to a point
Pass anchor a rect (or an element or ref) and the popover needs no trigger; control it through the root's open. The rect is in viewport coordinates, so measure it when the event fires.
API Reference
| Prop | Type | Default | Description |
|---|---|---|---|
| openPopover | boolean | None | Controlled open state. Use with onOpenChange. |
| onOpenChangePopover | (open: boolean) => void | None | Called when the open state changes. |
| modalPopover | boolean | false | When true, blocks interaction with outside elements while the popover is open. |
| sidePopoverContent | "top" | "right" | "bottom" | "left" | "bottom" | Preferred edge of the trigger to render against. |
| alignPopoverContent | "start" | "center" | "end" | "center" | Alignment against the trigger along the chosen side. |
| sideOffsetPopoverContent | number | 4 | Distance in pixels between the popover and the trigger. |
| collisionAvoidancePopoverContent | CollisionAvoidance | { fallbackAxisSide: "end" } | Object controlling how the popover avoids viewport collisions on the side and alignment axes, e.g. { side: 'none', align: 'none' } to always honor side/align. |
| flushPopoverContent | boolean | false | Drops the 16px inset for content that pads its own rows and runs edge to edge, such as a list of notifications. Clips to the corners. |
| anchorPopoverContent | Element | RefObject | { x, y, width, height } | () => Element | VirtualElement | None | Anchors the popover to something other than its trigger: an element, a ref, or a rect in viewport coordinates, such as a measured text caret. With a rect there is no trigger, so open it through the root's open. |
| classNamePopoverHeader | string | None | Stacks PopoverTitle over PopoverDescription with the trimmed-title gap (12px). Takes div props. |
| classNamePopoverTitle | string | None | A 14px medium title, cap-trimmed. Sets the popover's accessible name through aria-labelledby. |
| classNamePopoverDescription | string | None | A 13px muted line under the title. Sets the popover's accessible description through aria-describedby. |
openPopoverbooleanControlled open state. Use with onOpenChange. |
| onOpenChangePopover(open: boolean) => voidCalled when the open state changes. |
modalPopoverboolean = falseWhen true, blocks interaction with outside elements while the popover is open. |
| sidePopoverContent"top" | "right" | "bottom" | "left" = "bottom"Preferred edge of the trigger to render against. |
| alignPopoverContent"start" | "center" | "end" = "center"Alignment against the trigger along the chosen side. |
| sideOffsetPopoverContentnumber = 4Distance in pixels between the popover and the trigger. |
collisionAvoidancePopoverContentCollisionAvoidance = { fallbackAxisSide: "end" }Object controlling how the popover avoids viewport collisions on the side and alignment axes, e.g. { side: 'none', align: 'none' } to always honor side/align. |
| flushPopoverContentboolean = falseDrops the 16px inset for content that pads its own rows and runs edge to edge, such as a list of notifications. Clips to the corners. |
anchorPopoverContentElement | RefObject | { x, y, width, height } | () => Element | VirtualElementAnchors the popover to something other than its trigger: an element, a ref, or a rect in viewport coordinates, such as a measured text caret. With a rect there is no trigger, so open it through the root's open. |
| classNamePopoverHeaderstringStacks PopoverTitle over PopoverDescription with the trimmed-title gap (12px). Takes div props. |
classNamePopoverTitlestringA 14px medium title, cap-trimmed. Sets the popover's accessible name through aria-labelledby. |
classNamePopoverDescriptionstringA 13px muted line under the title. Sets the popover's accessible description through aria-describedby. |
"use client"
import * as React from "react"
import { Popover as PopoverPrimitive } from "@base-ui/react/popover"
import { cn } from "@/registry/lib/utils"
// @use-when a small floating panel anchored to the control that opened it, on
// click, holding content you compose. Not a menu, which is DropdownMenu; for
// editing fields in place, EditPopover.
function Popover({
...props
}: React.ComponentProps<typeof PopoverPrimitive.Root>) {
return <PopoverPrimitive.Root data-slot="popover" {...props} />
}
function PopoverTrigger({
...props
}: React.ComponentProps<typeof PopoverPrimitive.Trigger>) {
return <PopoverPrimitive.Trigger data-slot="popover-trigger" {...props} />
}
type PositionerAnchor = React.ComponentProps<typeof PopoverPrimitive.Positioner>["anchor"]
type RectAnchor = { x: number; y: number; width: number; height: number }
// A rect (a DOMRect from a selection or a measured caret) becomes the virtual
// element the positioner expects. Anything else passes through untouched.
function toAnchor(anchor: PositionerAnchor | RectAnchor): PositionerAnchor {
if (
anchor &&
typeof anchor === "object" &&
"width" in anchor &&
"height" in anchor &&
!("getBoundingClientRect" in anchor)
) {
const rect = anchor as RectAnchor
return { getBoundingClientRect: () => DOMRect.fromRect(rect) }
}
return anchor as PositionerAnchor
}
function PopoverContent({
className,
align = "center",
side,
sideOffset = 4,
alignOffset,
collisionAvoidance,
anchor,
flush = false,
...props
}: React.ComponentProps<typeof PopoverPrimitive.Popup> & {
/**
* Anchor the popover to something other than its trigger: an element, a ref,
* or a rect in viewport coordinates (`{ x, y, width, height }`, such as a
* measured text caret). With a rect there is no trigger, so open it by
* controlling the root's `open`.
*/
anchor?: PositionerAnchor | RectAnchor
/**
* Drops the 16px inset, for content that runs edge to edge and pads its own
* rows: a list of notifications, a menu-like set of links. Clips to the
* corners so a row's hover fill or divider stays inside the edge.
*/
flush?: boolean
} &
Pick<
React.ComponentProps<typeof PopoverPrimitive.Positioner>,
"align" | "side" | "sideOffset" | "alignOffset" | "collisionAvoidance"
>) {
return (
<PopoverPrimitive.Portal>
{/* z-50 goes on the Positioner: Base UI leaves the Popup
`position: static`, where z-index is ignored, so a z on the Popup is
inert and the popover falls back to `z-index: auto`. Combobox
composes this, so it inherits the fix. */}
<PopoverPrimitive.Positioner
// positionMethod="fixed": Base UI's Positioner defaults to
// "absolute", which positions the portaled popup in DOCUMENT
// coordinates. On open, Base UI moves focus into the popup before
// Floating UI has computed the transform, so the browser scrolls the
// focused element into view while it is still sitting at the document
// origin, and the whole page jumps to the top. With "fixed" the
// pre-position origin is the viewport, so there is nothing to scroll
// to. It also keeps the popup correct inside a scrolling or
// transformed ancestor.
positionMethod="fixed"
className="z-50"
anchor={anchor === undefined ? undefined : toAnchor(anchor)}
side={side}
align={align}
sideOffset={sideOffset}
alignOffset={alignOffset}
collisionAvoidance={collisionAvoidance}
>
<PopoverPrimitive.Popup
data-slot="popover-content"
className={cn(
"bg-popover text-popover-foreground transition-[opacity,scale,translate] motion-reduce:transition-[opacity] ease-large duration-large data-[ending-style]:duration-small data-[ending-style]:ease-small data-[starting-style]:opacity-0 data-[ending-style]:opacity-0 data-[starting-style]:scale-97 data-[ending-style]:scale-97 data-[side=bottom]:data-[starting-style]:-translate-y-2 data-[side=bottom]:data-[ending-style]:-translate-y-2 data-[side=top]:data-[starting-style]:translate-y-2 data-[side=top]:data-[ending-style]:translate-y-2 data-[side=right]:data-[starting-style]:-translate-x-2 data-[side=right]:data-[ending-style]:-translate-x-2 data-[side=left]:data-[starting-style]:translate-x-2 data-[side=left]:data-[ending-style]:translate-x-2 w-72 origin-(--transform-origin) rounded-md shadow-ring-md outline-hidden break-words",
// p-4, not the p-6 of Dialog, Sheet and Drawer: a popover is the small
// overlay tier, anchored to a trigger and sized to its content, so the
// large-surface inset would swallow it.
flush ? "overflow-hidden" : "p-4",
className
)}
{...props}
/>
</PopoverPrimitive.Positioner>
</PopoverPrimitive.Portal>
)
}
function PopoverHeader({ className, style, ...props }: React.ComponentProps<"div">) {
return (
<div
data-slot="popover-header"
className={cn("flex flex-col", className)}
// Title-to-description gap is the trim-pair rung, set inline: the title
// carries `cap-trim`, so this gap paints the exact number that set it,
// and a `gap-*` class would freeze that number past any override.
style={{ ...style, gap: "var(--spacing-rhythm-trim-pair)" }}
{...props}
/>
)
}
// One step below DialogTitle (text-lg semibold): a popover is a smaller
// surface, so the title is text-sm at font-medium, the heading size the
// popover demo used before this part existed.
function PopoverTitle({
className,
...props
}: React.ComponentProps<typeof PopoverPrimitive.Title>) {
return (
<PopoverPrimitive.Title
data-slot="popover-title"
className={cn("cap-trim text-sm leading-snug font-medium text-pretty", className)}
{...props}
/>
)
}
function PopoverDescription({
className,
...props
}: React.ComponentProps<typeof PopoverPrimitive.Description>) {
return (
<PopoverPrimitive.Description
data-slot="popover-description"
className={cn("text-muted-foreground text-xs text-pretty", className)}
{...props}
/>
)
}
export {
Popover,
PopoverContent,
PopoverDescription,
PopoverHeader,
PopoverTitle,
PopoverTrigger,
}