# Popover

A floating panel anchored to a trigger element.

- Category: Core Elements
- Page: https://wunderui.com/components/popover
- Tier: Free

## Install

```bash
npx wunderui-cli add popover
```

## Import

```tsx
import { Popover, PopoverClose, PopoverContent, PopoverTrigger } from "@/components/ui/popover"
```

## Minimal usage

Then use it:

```tsx
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.

## Usage

```tsx
import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover"
import { Button } from "@/components/ui/button"
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"

export function Example() {
  return (
    <Popover>
      <PopoverTrigger render={<Button variant="plain" />}>Dimensions</PopoverTrigger>
      <PopoverContent className="w-64">
        <div className="flex flex-col gap-1">
          <p className="text-sm font-semibold text-foreground">Dimensions</p>
          <p className="text-sm text-text-secondary">Set the dimensions for the layer.</p>
        </div>
        <div className="mt-4 flex flex-col gap-2">
          <Label className="grid grid-cols-[3.5rem_1fr] gap-3">
            Width
            <Input size="sm" defaultValue="100%" />
          </Label>
          <Label className="grid grid-cols-[3.5rem_1fr] gap-3">
            Height
            <Input size="sm" defaultValue="25px" />
          </Label>
        </div>
      </PopoverContent>
    </Popover>
  )
}
```

## 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

- [Tooltip](https://wunderui.com/components/tooltip) for a short label on a control, with nothing to click
- [Hover Card](https://wunderui.com/components/hover-card) for a read-only preview of a link, shown on hover
- [Dropdown Menu](https://wunderui.com/components/dropdown-menu) for a list of actions where people pick one
- [Dialog](https://wunderui.com/components/dialog) for a task that needs full attention, with the page behind it blocked

## Keyboard

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.

| Key | Action |
|---|---|
| `Enter` or `Space` | On the trigger: opens the panel and moves focus into it. On the trigger of an open panel: closes it. |
| `Tab` or `Shift+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

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

- `Popover`: Holds the open state and links the trigger to the panel, controlled or not. Modal decides whether the page behind stays usable.
- `PopoverTrigger`: 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.
- `PopoverContent`: 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.
- `PopoverClose`: 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.
- Set a width, such as 16 rem. Without one the panel is as wide as its widest line.
- Wrap Cancel and Apply in the close part, so focus goes back to the trigger.
- 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 use it for a short label on an icon. A Tooltip is for that, and it needs no click.
- Don't open one popover from inside another. Move the second choice into the first panel.
- 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

| Prop | Type | Default | Description |
|---|---|---|---|
| actionsRef | React.RefObject<PopoverRoot.Actions \| null> |  | A ref to imperative actions. - `unmount`: Manually unmounts the popover. Call this after any externally controlled closing animation finishes. - `close`: Closes the popover imperatively when called. |
| children | React.ReactNode \| PayloadChildRenderFunction<Payload> |  | The content of the popover. This can be a regular React node or a render function that receives the `payload` of the active trigger. |
| defaultOpen | boolean | false | Whether the panel starts open, for an uncontrolled popover. `false` by default. |
| defaultTriggerId | string \| null |  | ID of the trigger that the popover is associated with. This is useful in conjunction with the `defaultOpen` 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. |
| modal | boolean \| 'trap-focus' | false | `false` keeps the page behind the panel usable, `true` locks the scroll and the pointer outside the panel, and `"trap-focus"` only keeps the focus inside. `false` by default. |
| onOpenChange | ((open: boolean, eventDetails: PopoverRoot.ChangeEventDetails) => void) |  | Called with the new open state whenever the panel opens or closes, with details about what caused it. |
| onOpenChangeComplete | ((open: boolean) => void) |  | Event handler called after any animations complete when the popover is opened or closed. |
| open | boolean |  | Whether the panel is open, for a controlled popover. Pair it with `onOpenChange`. |
| triggerId | string \| null |  | ID of the trigger that the popover is associated with. This is useful in conjunction with the `open` prop to create a controlled popover. There's no need to specify this prop when the popover is uncontrolled (that is, when the `open` prop… |

### PopoverClose

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| nativeButton | boolean | true | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Replaces the close element, usually with a `Button` or an `IconButton`. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.ButtonHTMLAttributes attributes.

### PopoverContent

| Prop | Type | Default | Description |
|---|---|---|---|
| align | "center" \| "end" \| "start" | 'center' | How the panel lines up with the trigger along that side: `start`, `center` or `end`. `center` by default. |
| anchor | Element \| null \| VirtualElement \| React.RefObject<Element \| null> \| (() => Element \| VirtualElement \| null) |  | An element or a ref the panel is positioned against instead of the trigger. |
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| finalFocus | boolean \| React.RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => void \| boolean \| HTMLElement \| null) |  | The element that gets the focus when the panel closes. By default the trigger. |
| initialFocus | boolean \| React.RefObject<HTMLElement \| null> \| ((openType: InteractionType) => void \| boolean \| HTMLElement \| null) |  | The element that gets the focus when the panel opens. By default the first control in the panel. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| side | "left" \| "right" \| "bottom" \| "top" \| "inline-end" \| "inline-start" | 'bottom' | The side of the trigger the panel opens on: `top`, `right`, `bottom` or `left`. It flips to the other side when there is no room. |
| sideOffset | number \| OffsetFunction | 8 | The distance between the trigger and the panel in pixels. 8 by default. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.HTMLAttributes attributes.

### PopoverTrigger

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| closeDelay | number | 0 | How long after the pointer has left the trigger and the panel the panel closes with `openOnHover`, in milliseconds. |
| delay | number | 300 | How long the pointer must rest on the trigger before the panel opens with `openOnHover`, 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 `triggerId` prop). |
| nativeButton | boolean | true | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). Whether the component renders a native `<button>` element whe… |
| 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. `false` by default. |
| payload | Payload |  | A payload to pass to the popover when it is opened. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Replaces the trigger element, usually with a `Button` or an `IconButton`, so the trigger looks like the rest of your buttons. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.ButtonHTMLAttributes attributes.

## Examples

### Trigger: a button, an icon button or text

```tsx
import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover"
import { Button } from "@/components/ui/button"

export function Example() {
  return (
    <Popover>
      <PopoverTrigger render={<Button variant="plain" />}>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 unless a dedicated pool is set.</p>
        <dl className="mt-4 grid grid-cols-[auto_1fr] gap-x-6 gap-y-1 text-sm">
          <dt className="text-text-secondary">Region</dt>
          <dd className="text-right font-medium text-foreground">Frankfurt</dd>
          <dt className="text-text-secondary">Status</dt>
          <dd className="text-right font-medium text-foreground">Active</dd>
        </dl>
      </PopoverContent>
    </Popover>
  )
}
```

### Position: the side and the alignment

```tsx
import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover"
import { IconButton } from "@/components/ui/icon-button"
import { Info } from "lucide-react"

export function Example() {
  return (
    <Popover>
      <PopoverTrigger render={<IconButton variant="plain" aria-label="Pipeline details" />}>
        <Info />
      </PopoverTrigger>
      <PopoverContent className="w-52">
        <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>
  )
}
```

### Content state: loaded, loading, empty and error

```tsx
import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover"
import { Button } from "@/components/ui/button"

export function Example() {
  return (
    <Popover>
      <PopoverTrigger render={<Button variant="plain" />}>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 unless a dedicated pool is set.</p>
        <dl className="mt-4 grid grid-cols-[auto_1fr] gap-x-6 gap-y-1 text-sm">
          <dt className="text-text-secondary">Region</dt>
          <dd className="text-right font-medium text-foreground">Frankfurt</dd>
          <dt className="text-text-secondary">Status</dt>
          <dd className="text-right font-medium text-foreground">Active</dd>
        </dl>
      </PopoverContent>
    </Popover>
  )
}
```

## In context

### Filter with checkboxes

A filter button opens a short list of options and two buttons. Apply and Clear close the panel.

```tsx
import { Popover, PopoverClose, PopoverContent, PopoverTrigger } from "@/components/ui/popover"
import { Button } from "@/components/ui/button"
import { Checkbox } from "@/components/ui/checkbox"
import { Label } from "@/components/ui/label"
import { ListFilter } from "lucide-react"

export function StatusFilter() {
  return (
    <Popover>
      <PopoverTrigger render={<Button variant="plain" />}>
        <ListFilter data-icon="inline-start" />
        Filter
      </PopoverTrigger>
      <PopoverContent className="w-56" align="start">
        <p className="text-sm font-semibold text-foreground">Status</p>
        <div className="mt-3 flex flex-col gap-3">
          <Label className="font-normal">
            <Checkbox defaultChecked />
            Open
          </Label>
          <Label className="font-normal">
            <Checkbox defaultChecked />
            In review
          </Label>
          <Label className="font-normal">
            <Checkbox />
            Done
          </Label>
        </div>
        <div className="mt-4 flex justify-end gap-2">
          <PopoverClose render={<Button variant="plain" size="sm" />}>Clear</PopoverClose>
          <PopoverClose render={<Button variant="gradient" size="sm" />}>Apply</PopoverClose>
        </div>
      </PopoverContent>
    </Popover>
  )
}
```

### Share a link

The panel is aligned to the end of the button, so it stays inside the page on the right. The link is read only; the icon button copies it.

```tsx
import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover"
import { Button } from "@/components/ui/button"
import { IconButton } from "@/components/ui/icon-button"
import { Input } from "@/components/ui/input"
import { Copy } from "lucide-react"

export function ShareLink() {
  return (
    <Popover>
      <PopoverTrigger render={<Button variant="plain" />}>Share</PopoverTrigger>
      <PopoverContent className="w-80" align="end">
        <p className="text-sm font-semibold text-foreground">Share this project</p>
        <p className="mt-1 text-sm text-text-secondary">Anyone with the link can view it.</p>
        <div className="mt-4 flex gap-2">
          <Input aria-label="Link" readOnly defaultValue="wunderui.com/p/q4-roadmap" />
          <IconButton variant="plain" aria-label="Copy link">
            <Copy />
          </IconButton>
        </div>
      </PopoverContent>
    </Popover>
  )
}
```

### Confirm before deleting

A small question next to the icon button that asks it. It says what is lost, and both buttons close the panel.

```tsx
import { Popover, PopoverClose, PopoverContent, PopoverTrigger } from "@/components/ui/popover"
import { Button } from "@/components/ui/button"
import { IconButton } from "@/components/ui/icon-button"
import { Trash2 } from "lucide-react"

export function ConfirmDelete() {
  return (
    <Popover>
      <PopoverTrigger render={<IconButton variant="plain" aria-label="Delete Q4 roadmap" />}>
        <Trash2 />
      </PopoverTrigger>
      <PopoverContent className="w-72" align="end">
        <p className="text-sm font-semibold text-foreground">Delete Q4 roadmap?</p>
        <p className="mt-1 text-sm text-text-secondary">18 tasks and their comments are deleted with it. This can't be undone.</p>
        <div className="mt-4 flex justify-end gap-2">
          <PopoverClose render={<Button variant="plain" size="sm" />}>Cancel</PopoverClose>
          <PopoverClose render={<Button variant="destructive" size="sm" />}>Delete project</PopoverClose>
        </div>
      </PopoverContent>
    </Popover>
  )
}
```

## For AI agents

`get_component("popover")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
