> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/mui/base-ui/llms.txt
> Use this file to discover all available pages before exploring further.

# Popover

> A floating panel that displays rich content in a portal, positioned relative to a trigger element.

# Popover

A popover displays rich content in a floating panel that's positioned relative to a trigger element. It can be opened on click, hover, or focus.

## Import

```jsx theme={null}
import { Popover } from '@base-ui/react/popover';
```

## Basic Usage

```jsx theme={null}
<Popover.Root>
  <Popover.Trigger>Settings</Popover.Trigger>
  <Popover.Portal>
    <Popover.Positioner>
      <Popover.Popup>
        <Popover.Title>Display Settings</Popover.Title>
        <Popover.Description>
          Customize how content is displayed
        </Popover.Description>
        <div>
          <label>
            <input type="checkbox" />
            Dark mode
          </label>
        </div>
        <Popover.Close>Done</Popover.Close>
        <Popover.Arrow />
      </Popover.Popup>
    </Popover.Positioner>
  </Popover.Portal>
</Popover.Root>
```

## Sub-components

### Root

Groups all parts of the popover. Doesn't render its own HTML element.

**Key Props:**

* `open` (boolean): Whether the popover is currently open
* `defaultOpen` (boolean): Whether the popover is initially open (default: `false`)
* `modal` (boolean | 'trap-focus'): Determines if the popover enters a modal state (default: `false`)
  * `true`: page scroll is locked, outside interactions disabled
  * `false`: user interaction with the rest of the document is allowed
  * `'trap-focus'`: focus is trapped but page scroll and outside interactions are enabled
* `onOpenChange` ((open: boolean, eventDetails) => void): Event handler called when the popover is opened or closed
* `onOpenChangeComplete` ((open: boolean) => void): Event handler called after animations complete
* `handle` (PopoverHandle): A handle to associate the popover with an external trigger
* `actionsRef` (React.RefObject): A ref to imperative actions (`unmount`, `close`)

### Trigger

The button that toggles the popover.

### Portal

Portals the popover content to a different part of the DOM.

### Positioner

Positions the popover relative to the trigger using Floating UI.

**Key Props:**

* `anchor` (Element | VirtualElement): The anchor element to which the popover is positioned
* `side` ('top' | 'right' | 'bottom' | 'left'): The side of the anchor to position against (default: `'bottom'`)
* `alignment` ('start' | 'center' | 'end'): The alignment of the popover relative to the anchor (default: `'center'`)
* `sideOffset` (number): The distance in pixels from the anchor (default: `0`)
* `alignmentOffset` (number): The offset in pixels along the alignment axis (default: `0`)

### Popup

The container for the popover content.

### Title

An accessible title for the popover.

### Description

An accessible description for the popover.

### Close

A button that closes the popover.

### Arrow

An optional arrow that points to the trigger element.

### Backdrop

An optional backdrop that covers the screen when the popover is open.

### Viewport

Defines the viewport element to which the popover is confined.

## Styling Example

```css theme={null}
.PopoverPopup {
  background: white;
  border: 1px solid #e0e0e0;
  border-radius: 8px;
  padding: 16px;
  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.1);
  max-width: 300px;
  animation: scaleIn 150ms cubic-bezier(0.16, 1, 0.3, 1);
}

.PopoverTitle {
  font-size: 1rem;
  font-weight: 600;
  margin: 0 0 4px;
}

.PopoverDescription {
  font-size: 0.875rem;
  color: #666;
  margin: 0 0 16px;
}

.PopoverArrow {
  fill: white;
  stroke: #e0e0e0;
  stroke-width: 1px;
}

@keyframes scaleIn {
  from {
    opacity: 0;
    transform: scale(0.9);
  }
  to {
    opacity: 1;
    transform: scale(1);
  }
}
```

## Key Features

* Automatic positioning with collision detection
* Opens on hover, focus, or click
* Optional modal behavior with backdrop
* Arrow pointing to trigger
* Nested popover support
* Supports virtual elements as anchors

## Accessibility

* Has appropriate ARIA roles
* Title and description are automatically linked via `aria-labelledby` and `aria-describedby`
* Pressing Escape closes the popover
* Focus management with optional focus trapping
* Clicking outside closes the popover (when not modal)