# Popover

> A small panel that opens next to the element people click, for a little input such as a choice, a field and a button.

Source: https://raft-design.botiverse.build/components/popover. Generated from the current release; where it differs from what you remember, this page is right.

A popover is a small panel that opens next to the element people click and holds a little input: a choice of a few options, a field, a button. Snoozing a notification or renaming something fits in one. It closes on a click outside or Esc.

## When to use

| Situation                                               | Use                                                                                                    |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| One sentence about something, on hover                  | [Tooltip](https://raft-design.botiverse.build/components/tooltip.md)                                                                       |
| A summary of a person or an agent, on hover, with links | [PreviewCard](https://raft-design.botiverse.build/components/preview-card.md)                                                         |
| A little choice or input, on click (snooze, rename)     | Popover, with a [RadioGroup](https://raft-design.botiverse.build/components/radio-group.md), an [Input](https://raft-design.botiverse.build/components/input.md) and buttons |
| A list of actions                                       | [DropdownMenu](https://raft-design.botiverse.build/components/dropdown-menu.md)                                                      |
| Something that stays open and scrolls                   | [Drawer](https://raft-design.botiverse.build/components/drawer.md)                                                                          |

Which overlay fits which job is in [Choosing a component](https://raft-design.botiverse.build/components.md#overlays).

## Anatomy

- `Popover`: the root. Owns the open state. Required.
- `PopoverTrigger`: the element that opens it. Required.
- `PopoverContent`: the panel, portaled and positioned next to the trigger. Required.
- `PopoverHeader`: a row with `PopoverTitle` and an optional `PopoverClose`.
- `PopoverTitle` and `PopoverDescription`: the title and a sentence under it.
- `PopoverSeparator`: a hairline between parts of the panel.
- `PopoverClose`: a button that closes the popover.
- `PopoverArrow`: an optional pointer toward the trigger.
- `PopoverBackdrop`: a transparent layer behind the panel that catches clicks outside it.
- `PopoverPortal`, `PopoverViewport` and `PopoverPopup`: lower-level parts. `PopoverPopup` is the panel surface without positioning.

## Behavior

- The popover opens below its trigger, aligned to its start edge, and moves or flips when it meets the window edge ([Elevation](https://raft-design.botiverse.build/foundations/elevation.md#popups)).
- A click outside and Esc close it. A Cancel button closes it too.
- It has no scrim; the page behind it stays as it is.

## Content

- Write button labels in Title Case, with the confirm button repeating the verb: Snooze, Rename ([Writing](https://raft-design.botiverse.build/content/writing.md#actions-and-their-dialogs)).

## Accessibility

- Popover wraps the Base UI Popover. It provides the `dialog` role on the panel, moves focus into it on open, and returns focus to the trigger on Esc.
- Name the panel: `PopoverTitle` labels it. Without a visible title, put an `aria-label` on `PopoverContent`.
- Give an icon-only trigger an `aria-label`.

## Rules

- Make a popover 300px wide, with 16px padding.
- Don't put a pink button in a popover. Confirm with an ink-border button (`variant="outline"`) and cancel with `variant="ghost"`: a popover is a small step, not the screen's primary action.

## API

### Popover

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `actionsRef` | `RefObject<PopoverRootActions \| 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` | `ReactNode \| PayloadChildRenderFunction<unknown>` |  | 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 popover is initially open. |
| `defaultTriggerId` | `string` |  | 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` | `BasePopover.Handle<unknown>` |  | 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` | Determines if the popover enters a modal state when open. - `true`: user interaction is limited to the popover: document page scroll is locked, and pointer interactions on outside elements are disabled. - `false`: user interaction with the rest of the document is allowed. - `'trap-focus'`: focus is trapped inside the popover, but document page scroll is not locked and pointer interactions outside of it remain enabled. |
| `onOpenChange` | `(open: boolean, eventDetails: BasePopover.Root.ChangeEventDetails) => void` |  | Event handler called when the popover is opened or closed. |
| `onOpenChangeComplete` | `(open: boolean) => void` |  | Event handler called after any animations complete when the popover is opened or closed. |
| `open` | `boolean` |  | Whether the popover is currently open. |
| `triggerId` | `string` |  | 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 is not set). |

### PopoverArrow

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### PopoverBackdrop

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### PopoverClose

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `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` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### PopoverContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `container` | `HTMLElement \| ShadowRoot \| RefObject<HTMLElement \| ShadowRoot \| null>` |  |  |
| `portalProps` | `PopoverPortalProps` |  |  |
| `align` | `Align` | `"start"` | How to align the popup relative to the specified side. |
| `alignOffset` | `number \| OffsetFunction` | `0` | Additional offset along the alignment axis in pixels. Also accepts a function that returns the offset to read the dimensions of the anchor and positioner elements, along with its side and alignment. |
| `anchor` | `Element \| VirtualElement \| RefObject<Element \| null> \| (() => Element \| VirtualElement \| null)` |  | An element to position the popup against. By default, the popup will be positioned against the trigger. |
| `arrowPadding` | `number` | `5` | Minimum distance to maintain between the arrow and the edges of the popup. |
| `collisionAvoidance` | `CollisionAvoidance` |  | Determines how to handle collisions when positioning the popup. |
| `collisionBoundary` | `Boundary` | `'clipping-ancestors'` | An element or a rectangle that delimits the area that the popup is confined to. |
| `collisionPadding` | `Padding` | `5` | Additional space to maintain from the edge of the collision boundary. |
| `disableAnchorTracking` | `boolean` | `false` | Whether to disable the popup from tracking any layout shift of its positioning anchor. |
| `finalFocus` | `boolean \| RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => void \| boolean \| HTMLElement \| null)` |  | Determines the element to focus when the popover is closed. |
| `initialFocus` | `boolean \| RefObject<HTMLElement \| null> \| ((openType: InteractionType) => void \| boolean \| HTMLElement \| null)` |  | Determines the element to focus when the popover is opened. By default, focus moves to the first tabbable element inside the popup, except when the popover is opened by touch — then the popup itself is focused to avoid opening the virtual keyboard. |
| `positionMethod` | `"fixed" \| "absolute"` | `"fixed"` | Determines which CSS `position` property to use. |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |
| `side` | `Side` | `"bottom"` | Which side of the anchor element to align the popup against. May automatically change to avoid collisions. |
| `sideOffset` | `number \| OffsetFunction` | `4` | Distance between the anchor and the popup in pixels. Also accepts a function that returns the distance to read the dimensions of the anchor and positioner elements, along with its side and alignment. |
| `sticky` | `boolean` | `false` | Whether to maintain the popup in the viewport after the anchor element was scrolled out of view. |

Also takes the attributes of its element.

### PopoverDescription

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### PopoverHeader

Also takes the attributes of its element.

### PopoverPopup

Also takes the attributes of its element.

### PopoverPortal

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `container` | `HTMLElement \| ShadowRoot \| RefObject<HTMLElement \| ShadowRoot \| null>` |  | A parent element to render the portal element into. |
| `keepMounted` | `boolean` | `false` | Whether to keep the portal mounted in the DOM while the popup is hidden. |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### PopoverSeparator

Also takes the attributes of its element.

### PopoverTitle

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### PopoverTrigger

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `closeDelay` | `number` | `0` | How long to wait before closing the popover that was opened on hover. Specified in milliseconds. |
| `delay` | `number` | `300` | How long to wait before the popover may be opened on hover. Specified in milliseconds. |
| `handle` | `BasePopover.Handle<unknown>` |  | A handle to associate the trigger with a popover. |
| `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 when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (e.g. `<div>`). |
| `openOnHover` | `boolean` | `false` | Whether the popover should also open when the trigger is hovered. |
| `payload` | `{}` |  | A payload to pass to the popover when it is opened. |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### PopoverViewport

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` |  | The content to render inside the transition container. |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.