# Popover

Headless, unstyled floating panel anchored to a trigger, non-modal by default. Wires `role="dialog"`, the trigger’s `aria-expanded` and `aria-controls`, and focus on open and close.

## Use for

- a floating panel of interactive content anchored to a button
- a filter or settings panel that leaves the page usable
- a nested popover inside another floating surface

## Practices

- Do: Render `Popover.Title` and `Popover.Description`. They label and describe the positioner only when present.
- Do: Animate with `data-starting-style` and `data-ending-style` on `Popover.Popup`. Its children freeze on their last frame while it closes.
- Do: Set `initialFocus='first'` when the content is meant to be typed into straight away.
- Don't: Pass `id` to `Popover.Title` or `Popover.Description`. The primitive owns both.
- Don't: Use it for a list of actions or hover-only hints. Use `Menu` or `Tooltip` instead.

## API reference

### Popover.Root

Holds the open state, placement and dismissal. Renders no element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` |  | Whether the popover is open, when controlled. |
| `defaultOpen` | `boolean` | `false` | Whether the popover is open on mount, when uncontrolled. |
| `onOpenChange` | `(open: boolean) => void` |  | Called with the new open state. |
| `placement` | `Placement` | `'bottom'` | Where the popup sits against its anchor. |
| `sideOffset` | `number` | `4` | Gap to the anchor in px. |
| `alignOffset` | `number` | `0` | Nudge along the alignment axis in px. |
| `modal` | `boolean` | `false` | Traps focus inside the popup. |
| `initialFocus` | `'auto' \| 'first'` | `'auto'` | `auto` focuses the first tabbable on a keyboard open and the popup on a pointer open. `first` always focuses the first tabbable. |

### Popover.Trigger

A `button` that toggles the popover. Carries `data-open` or `data-closed`.

### Popover.Portal

Portals its children while the popover is mounted.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `root` | `HTMLElement \| null \| React.RefObject<HTMLElement \| null>` | ``the `Portal` container`` | The element to portal into. |

### Popover.Positioner

The floating `div` with `role="dialog"`. Carries `data-side` and the `--cl-anchor-*`, `--cl-available-*` and `--cl-transform-origin` variables, and manages focus.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `anchor` | `HTMLElement \| null` |  | Positions against this element instead of the trigger. |

### Popover.Popup

Wraps the content. Carries `data-open`, `data-closed`, `data-starting-style` and `data-ending-style`.

### Popover.Arrow

An optional `FloatingArrow` `svg` pointing at the anchor. Carries `data-side`.

### Popover.Title

An `h2` that labels the positioner.

### Popover.Description

A `p` that describes the positioner.

### Popover.Close

A `button` that closes the popover.

## Examples

### Settings panel

```tsx
<Popover.Root>
  <Popover.Trigger>Settings</Popover.Trigger>
  <Popover.Positioner>
    <Popover.Popup>
      <Popover.Title>Preferences</Popover.Title>
      <Popover.Close>Done</Popover.Close>
    </Popover.Popup>
  </Popover.Positioner>
</Popover.Root>
```

## Related

- [Menu](/docs/components/menu.md)
- [Tooltip](/docs/components/tooltip.md)
- [Portal](/docs/primitives/portal.md)
