Chapter 33: Popover

Core Idea

A non-modal-by-default anchored popup for supplementary content — same Handle/detached-trigger and Viewport content-transition machinery as Dialog/Menu, positioned relative to its Trigger (or a separate anchor) rather than centered on screen.

Key Concepts

• Anatomy: Root → Trigger, Portal → Backdrop, Positioner → Popup → Arrow, Viewport → Title, Description, Close.
• Non-modal by default: unlike Dialog (modal=true default), Popover defaults to non-modal — set modal explicitly if the popover should trap focus/block outside interaction.
• Hover trigger: Trigger supports openOnHover/delay/closeDelay directly (the pattern demoed in ch006 Animation and ch002 Getting Started uses click by default; hover is opt-in).
• Viewport: same content-transition part as Menu/Navigation Menu — animate between different popover "pages" of content in place.
• Positioning: full anchored-positioning family shared with every popup component — side/sideOffset, align/alignOffset, anchor (position relative to an element other than Trigger), collisionBoundary/collisionPadding/collisionAvoidance, sticky, positionMethod.
• CSS variables (from ch005/Getting Started demo): Popup exposes --available-height/--available-width, --anchor-width/--anchor-height, --transform-origin for sizing/animating relative to the anchor and available viewport space.
• Detached triggers: same Handle/createHandle() system as Dialog/AlertDialog/Menu.

Reference Tables

Part	Notable props	Notable data attributes
Root	open/onOpenChange, modal, handle, actionsRef, triggerId/defaultTriggerId	—
Trigger	openOnHover, delay, closeDelay, handle, payload	data-popup-open, data-pressed
Positioner	side/sideOffset, align/alignOffset, anchor, collisionBoundary/collisionPadding/collisionAvoidance, sticky, positionMethod	data-anchor-hidden, data-align, data-side
Popup	initialFocus, finalFocus	data-instant, animation attrs (CSS vars --available-height/-width, --anchor-width/-height, --transform-origin)

Key Takeaways

1. Popover defaults to non-modal — explicitly set modal if the design needs focus-trapping/backdrop-blocking behavior; don't assume it matches Dialog's defaults.
2. Use anchor when the popover should position relative to an element other than its own Trigger (e.g. a popover opened programmatically, anchored to a table row).
3. Reuse the --available-height/--anchor-width CSS variables for popup sizing instead of hardcoded max-heights — they track the live viewport/anchor geometry.

Connects To

• ch005 (Styling), ch006 (Animation): the Getting Started demo (ch002) builds a Popover step by step using this exact part set.
• ch021 (Dialog): the modal-by-default sibling for content that should block the page.
• ch034 (Preview Card): a more specialized hover-preview popup building on similar positioning concepts.