Popover

An overlay that displays additional information or options when triggered.

Anatomy

To set up the popover correctly, you’ll need to understand its anatomy and how we name its parts.

Each part includes a data-part attribute to help identify them in the DOM.

Examples

Learn how to use the Popover component in your project. Let’s take a look at the most basic example:

Using a Portal

By default, the popover is rendered in the same DOM hierarchy as the trigger. To render the popover within a portal, set the portalled prop to true.

Note: This requires that you render the component within a Portal based on the framework you use.

Adding an arrow

To render an arrow within the popover, render the component Popover.Arrow and Popover.ArrowTip as children of Popover.Positioner.

Listening for open and close events

When the popover is opened or closed, we invoke the onOpenChange callback.

Control the open state

Use the isOpen prop to control the open state of the popover.

Modifying the close behavior

The popover is designed to close on blur and when the esc key is pressed.

To prevent it from closing on blur (clicking or focusing outside), pass the closeOnInteractOutside prop and set it to false.

To prevent it from closing when the esc key is pressed, pass the closeOnEsc prop and set it to false.

Changing the placement

To change the placement of the popover, set the positioning prop.

Changing the modality

In some cases, you might want the popover to be modal. This means that it’ll:

  • trap focus within its content
  • block scrolling on the body
  • disable pointer interactions outside the popover
  • hide content behind the popover from screen readers

To make the popover modal, set the modal prop to true. When modal={true}, we set the portalled attribute to true as well.

API Reference

Root

PropTypeDefault
autoFocus
boolean
closeOnEsc
boolean
closeOnInteractOutside
boolean
defaultOpen
boolean
id
string
ids
Partial<{ anchor: string trigger: string content: string title: string description: string closeTrigger: string positioner: string arrow: string }>
initialFocusEl
HTMLElement | (() => MaybeElement)
lazyMount
booleanfalse
modal
booleanfalse
onEscapeKeyDown
(event: KeyboardEvent) => void
onExitComplete
() => void
onFocusOutside
(event: FocusOutsideEvent) => void
onInteractOutside
(event: InteractOutsideEvent) => void
onOpenChange
(details: OpenChangeDetails) => void
onPointerDownOutside
(event: PointerDownOutsideEvent) => void
open
boolean
portalled
booleantrue
positioning
PositioningOptions
present
boolean
unmountOnExit
booleanfalse

Anchor

PropTypeDefault
asChild
boolean

Arrow

PropTypeDefault
asChild
boolean

ArrowTip

PropTypeDefault
asChild
boolean

CloseTrigger

PropTypeDefault
asChild
boolean

Content

PropTypeDefault
asChild
boolean

Description

PropTypeDefault
asChild
boolean

Indicator

PropTypeDefault
asChild
boolean

Positioner

PropTypeDefault
asChild
boolean

Title

PropTypeDefault
asChild
boolean

Trigger

PropTypeDefault
asChild
boolean