Skip to main content

​
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

import { Popover } from '@base-ui/react/popover';

​
Basic Usage

<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

.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)