Popover

Common Popover Variants

Placement Options

All placements should include flip and shift middleware — if the popover would overflow the viewport, it automatically repositions. Configure shadow depth with the Shadow Tool to signal elevation.

Arrow Variants

• With arrow: A triangular indicator pointing from the popover to its trigger. Clarifies the anchor relationship. Essential when multiple triggers are close together.
• Without arrow: Cleaner look, works well when the spatial relationship is obvious (e.g., popover directly below a button).

Popover Properties

Important: When triggerAction is 'hover', include a delay (150–300ms) to prevent accidental triggers, and ensure the popover remains visible while the user moves their cursor from the trigger to the popover content (bridge the gap with a hover-safe zone).

Design Token Mappings

The shadow depth is critical for popovers. They float above the page surface and need a shadow that communicates this elevation. Use --shadow-lg or higher — a subtle --shadow-sm will make the popover look "stuck" to the page rather than floating above it.

Popover States

Focus management states:

• Non-modal: Focus moves into the popover but is not trapped. Tab can leave the popover, which closes it.
• Modal: Focus is trapped within the popover. Requires explicit close action (Escape or close button).

Accessibility Requirements

Semantic Structure:

• The trigger must have aria-haspopup="dialog" (for interactive popovers) or aria-haspopup="true" (for menu-like popovers).
• The trigger must have aria-expanded="true|false" reflecting the popover's open state.
• The popover container should have role="dialog" and aria-label or aria-labelledby referencing its title.
• Use aria-controls on the trigger pointing to the popover's id.

WCAG Compliance:

• SC 1.4.3 (Contrast – Minimum): All text within the popover must meet 4.5:1 contrast against the popover background. Verify with Contrast Checker.
• SC 1.4.11 (Non-text Contrast): The popover border or shadow must provide 3:1 contrast against the underlying page, ensuring the popover boundary is perceivable.
• SC 2.1.1 (Keyboard): The popover must be openable and closable via keyboard. Click-triggered popovers should also open on Enter/Space.
• SC 2.1.2 (No Keyboard Trap): If the popover is non-modal, Tab must be able to leave the popover (closing it). If modal, Escape must close it.
• SC 2.4.3 (Focus Order): When opened, focus should move to the first interactive element inside the popover (or the popover itself if no interactive elements). On close, focus must return to the trigger.
• SC 2.4.7 (Focus Visible): Focus rings must be visible on all interactive elements within the popover.
• SC 1.4.13 (Content on Hover or Focus): If the popover is hover-triggered, it must remain visible while the pointer is over it, must be dismissible without moving the pointer (Escape), and must persist until dismissed or the information is no longer valid. This is a Level AA requirement often missed.

Hover-Triggered Popovers (SC 1.4.13 compliance): Three requirements that are frequently violated:

1. Dismissible: User can dismiss without moving pointer (Escape key).
2. Hoverable: User can move pointer over the popover content without it closing.
3. Persistent: Content stays visible until user dismisses it, hovers away, or it becomes invalid.

Usage Guidelines

Do:

• Keep popover content focused and concise. If you need scrolling, consider a Drawer or Dialog.
• Always provide keyboard access — Enter/Space to open, Escape to close.
• Use shadows (Shadow Tool) to clearly separate the popover from the page content below.
• Include a close button (✕) for touch devices and discoverability, even if click-outside also closes.
• Position the arrow precisely — a misaligned arrow is worse than no arrow.
• Use portal rendering (React portal or teleporting to <body>) to avoid overflow: hidden clipping from parent containers.

Don't:

• Don't nest popovers inside popovers. It's disorienting and nearly impossible to manage focus correctly.
• Don't use popovers for critical information that the user must see — they can be dismissed too easily.
• Don't auto-open popovers on page load. They should always be user-triggered.
• Don't use a popover when a Tooltip suffices. If the content is a single line of non-interactive text, it's a tooltip.
• Don't use a popover with both hover and click triggers simultaneously — this creates confusing behavior on hybrid devices (touch + mouse).
• Don't forget collision detection. A popover that renders off-screen is worse than no popover at all.

Radix UI provides a comprehensive Popover primitive with Root, Trigger, Anchor, Portal, Content, Close, and Arrow compound components. Key props include side, sideOffset, align, alignOffset, collisionPadding, avoidCollisions, sticky, and hideWhenDetached. Radix handles focus management, Escape dismissal, click-outside dismissal, and portal rendering out of the box. The modal prop toggles between non-modal (focus can leave) and modal (focus trapped) behavior. Radix uses Floating UI internally for positioning.

Headless UI provides a Popover component with Popover.Button (trigger), Popover.Panel (content), Popover.Overlay (optional backdrop), and Popover.Group (for coordinating multiple popovers). Headless UI's Popover.Group is unique — it allows only one popover in the group to be open at a time, with focus moving between panels. Transition support is built in via Transition component wrapping Popover.Panel. Configure transition timing with the Transition Tool.

Material Design 3 uses the Popover from MUI with anchorEl, open, onClose, anchorOrigin (which corner of the anchor to attach to), transformOrigin (which corner of the popover aligns to the anchor), elevation (shadow depth), marginThreshold (viewport margin), and TransitionComponent (defaults to Grow). MUI's approach is anchor-origin based rather than side-based, which offers more control but is less intuitive than Radix/Floating UI's side/align API.

Ant Design provides Popover with title, content, trigger ('hover' | 'click' | 'focus' | 'contextMenu'), placement (12 positions), arrow (true | false | { pointAtCenter: true }), open (controlled), overlayClassName, overlayStyle, and getPopupContainer. Ant extends its Tooltip component under the hood, adding support for richer content. The getPopupContainer prop solves the common overflow: hidden clipping issue by letting you specify the portal target.

Chakra UI provides Popover with PopoverTrigger, PopoverContent, PopoverHeader, PopoverBody, PopoverFooter, PopoverArrow, and PopoverCloseButton. Chakra supports trigger="hover" and trigger="click", placement (all Popper.js positions), closeOnBlur, closeOnEsc, initialFocusRef, and returnFocusOnClose. Chakra uses Popper.js v2 for positioning with automatic flipping and boundary detection. The compound component API with semantic sections (Header/Body/Footer) encourages consistent internal structure.

Use the Shadow Tool to design the popover's elevation shadow and the Transition Tool to configure open/close animations across implementations.