On this page
Popover
A floating box anchored to a trigger, for content that is not a list of actions. The popup paints no surface of its own.
Use for
- a small floating panel opened from a button
- a picker or form in a floating box
Practices
| Guidance | Practice |
|---|---|
| Do | Put a surface inside Popover.Popup, usually a Card. |
| Do | Name the popup: render a Popover.Title, or pass aria-label or aria-labelledby to Popover.Popup. A dev warning fires otherwise. |
| Do | Pass initialFocus='first' when the content is typed into at once, such as a search. |
| Don’t | Use it for a list of actions. Use Menu instead. |
| Don’t | Use it for a hint on hover. Use Tooltip instead. |
API reference
Popover.Root
Holds the open state and placement. Renders no element.
| Prop | Type | Description |
|---|---|---|
open | boolean | Whether the popover is open, when controlled. |
defaultOpen | boolean | Whether it starts open, when uncontrolled.Default: false |
onOpenChange | (open: boolean) => void | Called with the new open state. |
placement | 'top' | 'right' | 'bottom' | 'left' | 'top-start' | 'top-end' | 'right-start' | 'right-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end' | Side and alignment against the trigger or anchor.Default: 'bottom' |
sideOffset | number | Gap from the trigger, in px.Default: 4 |
alignOffset | number | Shift along the trigger edge, in px.Default: 0 |
modal | boolean | Traps focus inside the popup.Default: false |
initialFocus | 'auto' | 'first' | auto focuses the first tabbable element after a key press and the popup after a pointer press. first always focuses the first tabbable element.Default: 'auto' |
Popover.Trigger
A button that toggles the popover. Pass render to use a Button.
Slot: cl-popover-trigger
Popover.Popup
Portals and positions the content. Resets Button defaults from any group around the trigger.
Slot: cl-popover-popup
| Prop | Type | Description |
|---|---|---|
size | PopoverSize | Width: sm, md, lg, or anchor to match the anchor width.Default: 'md' |
anchor | HTMLElement | null | Positions against this element instead of the trigger. |
aria-label | string | The popup name. Needed unless the content renders a Popover.Title. |
Popover.Title
An h2 that names the popup.
Popover.Description
A p that describes the popup.
Popover.Close
A button that closes the popover.
Examples
A popover with a card
<Popover.Root>
<Popover.Trigger render={props => <Button {...props} />}>Filters</Popover.Trigger>
<Popover.Popup>
<Card.Root>
<Popover.Title>Filters</Popover.Title>
…
</Card.Root>
</Popover.Popup>
</Popover.Root>