# 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

- 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 | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` |  | Whether the popover is open, when controlled. |
| `defaultOpen` | `boolean` | `false` | Whether it starts open, when uncontrolled. |
| `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'` | `'bottom'` | Side and alignment against the trigger or anchor. |
| `sideOffset` | `number` | `4` | Gap from the trigger, in px. |
| `alignOffset` | `number` | `0` | Shift along the trigger edge, in px. |
| `modal` | `boolean` | `false` | Traps focus inside the popup. |
| `initialFocus` | `'auto' \| 'first'` | `'auto'` | `auto` focuses the first tabbable element after a key press and the popup after a pointer press. `first` always focuses the first tabbable element. |

### 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 | Default | Description |
| --- | --- | --- | --- |
| `size` | `PopoverSize` | `'md'` | Width: `sm`, `md`, `lg`, or `anchor` to match the anchor width. |
| `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

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

## Related

- [Menu](/docs/components/menu.md)
- [Tooltip](/docs/components/tooltip.md)
- [Card](/docs/components/card.md)
- [Dialog](/docs/components/dialog.md)
