Popover

A floating panel anchored to a trigger element.

Installation

$
npx shadcn@latest add https://ui.mattdowney.com/r/popover.json

Usage

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

PropTypeDefaultDescription
openPopoverbooleanNoneControlled open state. Use with onOpenChange.
onOpenChangePopover(open: boolean) => voidNoneCalled when the open state changes.
modalPopoverbooleanfalseWhen 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.
sideOffsetPopoverContentnumber4Distance 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.
flushPopoverContentbooleanfalseDrops 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 | VirtualElementNoneAnchors 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.
classNamePopoverHeaderstringNoneStacks PopoverTitle over PopoverDescription with the trimmed-title gap (12px). Takes div props.
classNamePopoverTitlestringNoneA 14px medium title, cap-trimmed. Sets the popover's accessible name through aria-labelledby.
classNamePopoverDescriptionstringNoneA 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.