Popover
FreeA panel that opens next to a button on click and holds content people can read and use, such as a short form or a few actions.
npx wunderui-cli add popoverPlayground
Installation
npx wunderui-cli add popoverWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import {
Popover,
PopoverClose,
PopoverContent,
PopoverTrigger,
} from "@/components/ui/popover"Then use it:
import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover"
export function PipelineDetails() {
return (
<Popover>
<PopoverTrigger>Pipeline</PopoverTrigger>
<PopoverContent className="w-64">
<p className="text-sm font-semibold text-foreground">Pipeline</p>
<p className="mt-1 text-sm text-text-secondary">Runs on the shared cluster.</p>
</PopoverContent>
</Popover>
)
}Expected result: You should see a button named Pipeline. Pressing it opens a small panel under it with a title and a line of text; pressing Escape or clicking elsewhere closes it.
When to use
Use Popover for
- Content people read or use in place: a short form, a list of options or a few actions
- A small question next to the button that asks it, such as a confirmation before deleting
- Settings for one object, opened from a button on that object
Use something else for
- Tooltip for a short label on a control, with nothing to click
- Hover Card for a read-only preview of a link, shown on hover
- Dropdown Menu for a list of actions where people pick one
- Dialog for a task that needs full attention, with the page behind it blocked
Trigger
The trigger is a native button. Pass your own button or icon button instead, or style the trigger as text.
Position
The panel opens below the trigger by default, and you can choose the side and how it lines up with the trigger. It flips to the other side when there is no room.
Content state
A panel that loads shows a skeleton of the final layout, and one that cannot show anything says so and names the next step.
Keyboard interactions
The trigger is a native button, so the browser provides focus and activation. The panel is not a menu: its controls are reached with Tab.
- EnterorSpace
- On the trigger: opens the panel and moves focus into it. On the trigger of an open panel: closes it.
- TaborShift+Tab
- Moves focus through the controls in the panel. Moving focus out of the panel closes it.
- Escape
- Closes the panel and gives the focus back to the trigger.
Behavior and motion
What the panel does with focus, the page behind it and motion.
- Opening
- Clicking the trigger, or pressing Enter or Space on it, opens the panel and moves focus to the first control, or to the panel if it has none. You can choose which element gets focus.
- Closing
- Escape, a click outside, the close part, or moving focus out of the panel closes it. Focus goes back to the trigger unless you send it elsewhere.
- The page behind
- By default the page behind stays usable and scrolls, and a click on it closes the panel. Modal locks scroll and pointer outside; the trap-focus option only keeps focus inside.
- Position and size
- The panel opens below the trigger, centred, 8 px away, and you can pick another side and alignment. It flips when there is no room and slides to stay on screen.
- Content that loads
- Show a skeleton of the final layout while content loads, and a short line with the next step when it fails, so the panel never opens empty. Mark a loading panel as busy.
- Previews in these docs
- In these docs the previews draw the panel inside the preview and show it only while the whole preview is on screen. It starts open; click the trigger to close and reopen it.
- Opening and closing
- The panel fades in and scales up from 95 % with an overshoot curve, growing from the side of the trigger. It leaves with a fade and a scale down to 99 %.
- Reduced motion
- With reduced motion the scale is off and the panel only fades in and out.
Anatomy
The parts of a popover, numbered in the figure. The title, text and controls inside the panel are yours: the panel is a plain container.
- data-slot="popover"
Holds the open state and links the trigger to the panel, controlled or not. Modal decides whether the page behind stays usable.
- 1data-slot="popover-trigger"
The native button that opens and closes the panel; pass your own button or icon button to replace it. It carries aria-expanded and aria-controls.
- 2data-slot="popover-content"
The panel, with its own portal and positioner. It opens 8 px from the trigger, sizes to its content (set a width yourself) and has 16 px padding, a 12 px radius, a border and a shadow.
- 3data-slot="popover-close"Optional
Closes the popover when pressed. Render it as an icon button for a close X, or around the Cancel and Apply buttons of a form.
Best practices
- Do
Give the panel one clear job: a short form, a list of options, or a question with its buttons. Keep a title and a line of text so people know what they opened.
- Do
Set a width, such as 16 rem. Without one the panel is as wide as its widest line.
- Do
Wrap Cancel and Apply in the close part, so focus goes back to the trigger.
- Do
Put the trigger where people expect the content to belong, and align the panel so it stays inside the page at the screen edge.
- Don’t
Don't put a long form, a table or a multi-step task in a popover. Use a Dialog or a side panel when people need the room.
- Don’t
Don't use it for a short label on an icon. A Tooltip is for that, and it needs no click.
- Don’t
Don't open one popover from inside another. Move the second choice into the first panel.
- Don’t
Don't hide the only way to do something in a popover that opens on hover. Touch screens cannot hover, so keep the click.
API reference
Popover wraps the Base UI popover and passes its props on. The root takes the open state; the trigger and content also take a class name, style and render prop.
Holds the open state and links the trigger to the panel, controlled or not. Modal decides whether the page behind stays usable.
| Prop | Type | Default | Description |
|---|---|---|---|
| open | boolean | — | Whether the panel is open, for a controlled popover. Pair it with . |
| defaultOpen | boolean | false | Whether the panel starts open, for an uncontrolled popover. by default. |
| onOpenChange | (open, eventDetails) => void | — | Called with the new open state whenever the panel opens or closes, with details about what caused it. |
| modal | boolean | "trap-focus" | false | keeps the page behind the panel usable, locks the scroll and the pointer outside the panel, and only keeps the focus inside. by default. |
| actionsRef | RefObject<PopoverRoot.Actions | null> | — | A ref to imperative actions. - : Manually unmounts the popover. Call this after any externally controlled closing animation finishes. - : Closes the popover imperatively when called. |
| children | ReactNode | PayloadChildRenderFunction<Payload> | — | The content of the popover. This can be a regular React node or a render function that receives the of the active trigger. |
| defaultTriggerId | string | null | — | ID of the trigger that the popover is associated with. This is useful in conjunction with the prop to create an initially open popover. |
| handle | PopoverHandle<Payload> | — | A handle to associate the popover with a trigger. If specified, allows external triggers to control the popover's open state. |
| onOpenChangeComplete | (open) => void | — | Event handler called after any animations complete when the popover is opened or closed. |
| triggerId | string | null | — | ID of the trigger that the popover is associated with. This is useful in conjunction with the prop to create a controlled popover. There's no need to specify this prop when the popover is uncontrolled (that is, when the prop… |
The native button that opens and closes the panel; pass your own button or icon button to replace it. It carries aria-expanded and aria-controls.
| Prop | Type | Default | Description |
|---|---|---|---|
| render | ReactElement | (props, state) => ReactElement | — | Replaces the trigger element, usually with a or an , so the trigger looks like the rest of your buttons. |
| openOnHover | boolean | false | Opens the panel when the pointer rests on the trigger as well as on click. Touch screens cannot hover, so keep the click working. by default. |
| delay | number | 300 | How long the pointer must rest on the trigger before the panel opens with , in milliseconds. |
| closeDelay | number | 0 | How long after the pointer has left the trigger and the panel the panel closes with , in milliseconds. |
| handle | PopoverHandle<Payload> | — | A handle to associate the trigger with a popover. |
| id | string | — | ID of the trigger. In addition to being forwarded to the rendered element, it is also used to specify the active trigger for the popover in controlled mode (with the PopoverRoot prop). |
| nativeButton | boolean | true | Whether the component renders a native element when replacing it via the prop. Set to if the rendered element is not a button (for example, ). Whether the component renders a native element whe… |
| payload | Payload | — | A payload to pass to the popover when it is opened. |
The panel, with its own portal and positioner. It opens 8 px from the trigger, sizes to its content (set a width yourself) and has 16 px padding, a 12 px radius, a border and a shadow.
| Prop | Type | Default | Description |
|---|---|---|---|
| side | "left" | "right" | "bottom" | "top" | "inline-end" | "inline-start" | "bottom" | The side of the trigger the panel opens on: , , or . It flips to the other side when there is no room. |
| align | "center" | "end" | "start" | "center" | How the panel lines up with the trigger along that side: , or . by default. |
| sideOffset | number | OffsetFunction | 8 | The distance between the trigger and the panel in pixels. 8 by default. |
| anchor | Element | null | VirtualElement | RefObject<Element | null> | () => unknown | — | An element or a ref the panel is positioned against instead of the trigger. |
| initialFocus | boolean | RefObject<HTMLElement | null> | (openType) => unknown | — | The element that gets the focus when the panel opens. By default the first control in the panel. |
| finalFocus | boolean | RefObject<HTMLElement | null> | (closeType) => unknown | — | The element that gets the focus when the panel closes. By default the trigger. |
Closes the popover when pressed. Render it as an icon button for a close X, or around the Cancel and Apply buttons of a form.
| Prop | Type | Default | Description |
|---|---|---|---|
| render | ReactElement | (props, state) => ReactElement | — | Replaces the close element, usually with a or an . |
| nativeButton | boolean | true | Whether the component renders a native element when replacing it via the prop. Set to if the rendered element is not a button (for example, ). |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("popover")npx wunderui-cli add popoverThe full library index for assistants is at /llms.txt.