Popover
A floating content container that displays rich content or actions when triggered, anchored to a reference element with automatic positioning.
Basic Popover
Positions
Popover can be positioned on any side of the trigger element.
Without Arrow
Remove the arrow pointer by setting showArrow to false.
Rich Content
Popovers can contain complex content including lists, buttons, and interactive elements.
Form in Popover
Use the composable API for more complex interactions like forms.
User Profile Card
A common pattern for displaying user information in a popover.
Props (Convenience API)
| Name | Type | Default | Description |
|---|---|---|---|
trigger* | ReactNode | - | Trigger element that opens the popover |
children* | ReactNode | - | Content to display in the popover |
side | 'top' | 'bottom' | 'left' | 'right' | 'bottom' | Position of popover relative to trigger |
align | 'start' | 'center' | 'end' | 'center' | Alignment of popover relative to trigger |
showArrow | boolean | true | Whether to show arrow pointer |
open | boolean | - | Controlled open state |
onOpenChange | (open: boolean) => void | - | Callback when open state changes |
Composable Parts
For more control, use the composable API with individual components.
| Name | Type | Default | Description |
|---|---|---|---|
PopoverRoot | Component | - | Root container component for composable API |
PopoverTrigger | Component | - | Trigger element wrapper (use with asChild) |
PopoverContent | Component | - | Content container with positioning logic |
PopoverClose | Component | - | Close button wrapper (use with asChild) |
Usage Guidelines
When to use
- •Display contextual information or actions related to a trigger element
- •Show additional details without navigating away from the current page
- •Present forms or actions in a compact, focused interface
- •Display user profiles, help text, or tooltips with rich content
Best practices
- •Keep content concise and focused on the trigger context
- •Use appropriate positioning to avoid blocking important content
- •Provide a clear way to close the popover (close button or outside click)
- •Use the composable API for complex interactions with multiple interactive elements
- •Consider using Tooltip for simple, non-interactive content
Accessibility
- •Proper ARIA attributes (aria-haspopup, aria-expanded) are automatically applied
- •Keyboard navigation: Press Escape to close, Tab to navigate between elements
- •Focus management: Focus returns to trigger element when popover closes
- •Portal rendering: Content is rendered at document body level for proper layering
- •Automatic positioning adjusts to stay within viewport boundaries
Do's and Don'ts
✓ Do
- •Use popovers for contextual information and actions
- •Keep content focused and relevant to the trigger
- •Provide clear close actions for complex popovers
- •Use appropriate positioning to avoid blocking content
✗ Don't
- •Don't overload popovers with too much content
- •Don't use popovers for critical information that must be seen
- •Don't nest popovers inside other popovers
- •Don't use popovers when a simple tooltip would suffice
Related Components
Tooltip
Simple hover information for UI elements
Dropdown Menu
Action menus triggered by a button
Dialog
Modal dialogs for focused interactions