Overlaysstable
Popover
A floating content container that displays rich content in a portal, positioned relative to a trigger element.
Installation
Install the component directly into your project using the Pittaya CLI.
npx pittaya@latest add popover
When to use
Use Popover when you need to display additional information, actions, or controls in a lightweight overlay without navigating away from the current context. It's perfect for tooltips with rich content, quick actions, or contextual information.
Popovers are ideal for displaying content like user profiles, color pickers, date selectors, or action menus that need to appear temporarily and shouldn't interrupt the user's workflow.
Best practices
- Keep popover content concise and focused on a single purpose or piece of information.
- Position popovers so they don't obscure important content or trigger elements.
- Use popovers for secondary actions or information—critical actions should be more prominent.
- Ensure popovers are dismissible by clicking outside or pressing the Escape key.
- Avoid nesting multiple popovers—this creates a poor user experience and confusion.
- Consider using dialogs instead of popovers for complex forms or multi-step interactions.
Accessibility
The Popover component is built on Radix UI primitives and includes comprehensive accessibility features. It manages focus automatically, supports keyboard navigation, and includes proper ARIA attributes for screen readers.
Users can close popovers with the Escape key, and focus is properly managed when the popover opens and closes. The component uses Portal to render content in a separate DOM tree, preventing z-index issues while maintaining accessibility.
Examples
Combine variants and sizes to meet your needs.
Basic popover
A simple popover with text content triggered by a button.
With form controls
Popover containing form elements for quick data entry.
Custom positioning
Control the popover position using side and align props.
User menu
Real-world example of a user menu with profile actions.
Properties
TSX interface that combines variants and default attributes.
| Prop | Type | Default | Description |
|---|---|---|---|
open | boolean | — | Controls the open state of the popover. Use with onOpenChange for controlled behavior. |
onOpenChange | (open: boolean) => void | — | Callback fired when the popover open state changes. Use with open for controlled behavior. |
defaultOpen | boolean | false | The initial open state when the popover is uncontrolled. |
modal | boolean | false | When true, interaction with outside elements is disabled and only the popover content is visible to screen readers. |
align | 'start' | 'center' | 'end' | 'center' | The preferred alignment of the popover relative to the trigger element. |
side | 'top' | 'right' | 'bottom' | 'left' | 'bottom' | The preferred side of the trigger to position the popover against. |
sideOffset | number | 4 | The distance in pixels from the trigger element. |
alignOffset | number | 0 | The distance in pixels from the aligned edge. |