Skip to contents

Popover

An accessible popup anchored to a button.

View as Markdown View source

Anatomy

Import the component and assemble its parts:

Anatomy

Examples

Opening on hover

This example shows how you can configure the popover to open on hover using the openOnHover prop.

You can use the delay prop to specify how long to wait (in milliseconds) before the popover opens on hover.

Detached triggers

A popover can be controlled by a trigger located either inside or outside the <Popover.Root> component. For simple, one-off interactions, place the <Popover.Trigger> inside <Popover.Root>, as shown in the example at the top of this page.

However, if defining the popover's content next to its trigger is not practical, you can use a detached trigger. This involves placing the <Popover.Trigger> outside of <Popover.Root> and linking them with a handle created by the Popover.createHandle() function.

The imperative methods on the handle, such as open() and close(), require a <Popover.Root> using the same handle to be mounted. Calls made while no root is attached to the handle — before one mounts, or after it unmounts — are ignored. Each time a root mounts, it starts from fresh state: a call made while no root was attached is not replayed, and no open state carries over from a previous mount.

Detached triggers

Multiple triggers

A single popover can be opened by multiple trigger elements. You can achieve this by using the same handle for several detached triggers, or by placing multiple <Popover.Trigger> components inside a single <Popover.Root>.

Multiple triggers within the Root part
Multiple detached triggers

The popover can render different content depending on which trigger opened it. This is achieved by passing a payload to the <Popover.Trigger> and using the children snippet of <Popover.Root>, which receives the payload.

The payload can be strongly typed by providing a type argument to the createHandle() function:

Detached triggers with payload

Controlled mode with multiple triggers

You can control the popover's open state externally by binding the open prop on <Popover.Root>. This allows you to manage the popover's visibility based on your application's state. When using multiple triggers, you have to manage which trigger is active by binding the triggerId prop on <Popover.Root> and setting the id prop on each <Popover.Trigger>.

Note that there is no separate onTriggerIdChange prop. bind:triggerId follows the trigger that opens or closes the popover. The onOpenChange callback also receives an additional argument, eventDetails, which contains the trigger element that initiated the state change.

Animating the Popover

You can animate a popover as it moves between different trigger elements. This includes animating its position, size, and content.

Position and Size

To animate the popover's position, apply CSS transitions to the left, right, top, and bottom properties of the Positioner part. To animate its size, transition the width and height of the Popup part.

Content

The popover also supports content transitions. This is useful when different triggers display different content within the same popover.

To enable content animations, wrap the content in the <Popover.Viewport> part. This part provides features to create direction-aware animations. It renders a div with a data-activation-direction attribute that indicates the new trigger's position relative to the previous one. The value is a space-separated set of up to two tokens (one per axis) — left or right for the horizontal axis and up or down for the vertical axis (for example, right down). Match a single token with the ~= attribute selector, such as [data-activation-direction~='right'].

Inside the <Popover.Viewport>, the content is further wrapped in divs with data attributes to help with styling:

  • data-current: The currently visible content when no transitions are present or the incoming content.
  • data-previous: The outgoing content during a transition.

You can use these attributes to style the enter and exit animations.

API reference

Root

Groups all parts of the popover. Does not render its own HTML element.

open boolean false
Name
open
Description

Whether the popover is open. Use bind:open to share it with the parent. A value passed without bind: holds until the parent changes it.

Type
boolean
Default
false
Binding
bind:open
onOpenChange function —
Name
onOpenChange
Description

Called before the open state changes. Call eventDetails.cancel() to veto it.

Type
(open: boolean, details: PopoverChangeEventDetails) => void
onOpenChangeComplete function —
Name
onOpenChangeComplete
Description

Called after the open or close transition finishes.

Type
(open: boolean) => void
modal PopoverModal false
Name
modal
Description

true limits interaction to the popover. 'trap-focus' traps focus without a backdrop.

Type
PopoverModal
Default
false
triggerId string | null —
Name
triggerId
Description

Id of the trigger that owns the popover. A string wins over the trigger that opened it. An id written by a trigger press resets to null once the popup unmounts.

Type
string | null
Binding
bind:triggerId
handle PopoverHandle<Payload> —
Name
handle
Description

Associates detached triggers and imperative open, close, and unmount.

Type
PopoverHandle<Payload>
children Snippet<[{ payload: Payload | undefined }]> —
Name
children
Type
Snippet<[{ payload: Payload | undefined }]>
open boolean
Name
open
Type
boolean
modal PopoverModal
Name
modal
Type
PopoverModal
payload unknown
Name
payload
Type
unknown

Trigger

A button that opens the popover. Renders a <button> element.

disabled boolean | null —
Name
disabled
Type
boolean | null
nativeButton boolean true
Name
nativeButton
Description

Whether the host is a native <button>. Set false when render supplies a non-button element.

Type
boolean
Default
true
handle PopoverHandle<Payload> —
Name
handle
Type
PopoverHandle<Payload>
payload Payload —
Name
payload
Type
Payload
id string | null —
Name
id
Type
string | null
openOnHover boolean false
Name
openOnHover
Description

Opens the popover when the pointer rests on the trigger.

Type
boolean
Default
false
delay number 300
Name
delay
Description

Hover open delay in milliseconds.

Type
number
Default
300
closeDelay number 0
Name
closeDelay
Description

Hover close delay in milliseconds.

Type
number
Default
0
render Snippet<[props: PopoverTriggerHostProps, state: PopoverTriggerState, children: Snippet | undefined]> —
Name
render
Type
Snippet<[props: PopoverTriggerHostProps, state: PopoverTriggerState, children: Snippet | undefined]>
disabled boolean
Name
disabled
Type
boolean
open boolean
Name
open
Description

Whether the popover is open and was opened by this trigger.

Type
boolean
data-popup-open
Present when the corresponding popover is open.
data-pressed
Present when the trigger is pressed.
data-disabled
Present when the trigger is disabled.

Backdrop

An overlay displayed beneath the popover. Renders a <div> element.

render Snippet<[props: HTMLAttributes<HTMLDivElement>, state: PopoverBackdropState, children: Snippet | undefined]> —
Name
render
Type
Snippet<[props: HTMLAttributes<HTMLDivElement>, state: PopoverBackdropState, children: Snippet | undefined]>
open boolean
Name
open
Type
boolean
transitionStatus 'starting' | 'ending' | 'idle' | undefined
Name
transitionStatus
Type
'starting' | 'ending' | 'idle' | undefined
data-open
Present when the popup is open.
data-closed
Present when the popup is closed.
data-starting-style
Present when the popup begins animating in.
data-ending-style
Present when the popup is animating out.

Portal

A portal element that moves the popup to a different part of the DOM. By default, the portal element is appended to <body>.

keepMounted boolean false
Name
keepMounted
Description

Keep the portal mounted while the popup is closed.

Type
boolean
Default
false
container HTMLElement | ShadowRoot | null —
Name
container
Description

Element the portal is appended to. undefined uses the parent portal or document.body. null waits and does not mount until an element or shadow root is set. There is no ref object.

Type
HTMLElement | ShadowRoot | null
render Snippet<[props: HTMLAttributes<HTMLDivElement> & Record<symbol, Attachment<HTMLDivElement>>, state: PopoverPortalState, children: Snippet | undefined]> —
Name
render
Description

Replace the portal element. The snippet receives host props, an empty state, and the children snippet. Host props include the move attachment.

Type
Snippet<[props: HTMLAttributes<HTMLDivElement> & Record<symbol, Attachment<HTMLDivElement>>, state: PopoverPortalState, children: Snippet | undefined]>

Positioner

Positions the popover against the trigger. Renders a <div> element.

anchor Anchor —
Name
anchor
Description

An element to position the popup against. By default, the popup will be positioned against the trigger.

Type
Anchor
positionMethod "absolute" | "fixed" 'absolute'
Name
positionMethod
Description

Determines which CSS position property to use.

Type
"absolute" | "fixed"
Default
'absolute'
side Side 'bottom'
Name
side
Description

Which side of the anchor element to align the popup against. May automatically change to avoid collisions.

Type
Side
Default
'bottom'
align Align 'center'
Name
align
Description

How to align the popup relative to the specified side.

Type
Align
Default
'center'
sideOffset number | OffsetFunction 0
Name
sideOffset
Description

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.

The function takes a data object parameter with the following properties: - data.anchor: the dimensions of the anchor element with properties width and height. - data.positioner: the dimensions of the positioner element with properties width and height. - data.side: which side of the anchor element the positioner is aligned against. - data.align: how the positioner is aligned relative to the specified side.

Type
number | OffsetFunction
Default
0
alignOffset number | OffsetFunction 0
Name
alignOffset
Description

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.

The function takes a data object parameter with the following properties: - data.anchor: the dimensions of the anchor element with properties width and height. - data.positioner: the dimensions of the positioner element with properties width and height. - data.side: which side of the anchor element the positioner is aligned against. - data.align: how the positioner is aligned relative to the specified side.

Type
number | OffsetFunction
Default
0
collisionBoundary Boundary 'clipping-ancestors'
Name
collisionBoundary
Description

An element or a rectangle that delimits the area that the popup is confined to.

Type
Boundary
Default
'clipping-ancestors'
collisionPadding Padding 5
Name
collisionPadding
Description

Additional space to maintain from the edge of the collision boundary.

Type
Padding
Default
5
arrowPadding number 5
Name
arrowPadding
Description

Minimum distance to maintain between the arrow and the edges of the popup.

Use it to prevent the arrow element from hanging out of the rounded corners of a popup.

Type
number
Default
5
sticky boolean false
Name
sticky
Description

Whether to maintain the popup in the viewport after the anchor element was scrolled out of view.

Type
boolean
Default
false
disableAnchorTracking boolean false
Name
disableAnchorTracking
Description

Whether to disable the popup from tracking any layout shift of its positioning anchor.

Type
boolean
Default
false
collisionAvoidance CollisionAvoidance —
Name
collisionAvoidance
Description

Determines how to handle collisions when positioning the popup.

side controls overflow on the preferred placement axis (top/bottom or left/right): - 'flip': keep the requested side when it fits; otherwise try the opposite side (top and bottom, or left and right). - 'shift': never change side; keep the requested side and move the popup within the clipping boundary so it stays visible. - 'none': do not correct side-axis overflow.

align controls overflow on the alignment axis (start/center/end): - 'flip': keep side, but swap start and end when the requested alignment overflows. - 'shift': keep side and requested alignment, then nudge the popup along the alignment axis to fit. - 'none': do not correct alignment-axis overflow.

fallbackAxisSide controls fallback behavior on the perpendicular axis when the preferred axis cannot fit: - 'start': allow perpendicular fallback and try the logical start side first (top before bottom, or left before right in LTR). - 'end': allow perpendicular fallback and try the logical end side first (bottom before top, or right before left in LTR). - 'none': do not fallback to the perpendicular axis.

When side is 'shift', explicitly setting align only supports 'shift' or 'none'. If align is omitted, it defaults to 'flip'.

Type
CollisionAvoidance
render Snippet<[props: HTMLAttributes<HTMLDivElement>, state: PopoverPositionerState, children: Snippet | undefined]> —
Name
render
Type
Snippet<[props: HTMLAttributes<HTMLDivElement>, state: PopoverPositionerState, children: Snippet | undefined]>
open boolean
Name
open
Type
boolean
side Side
Name
side
Type
Side
align Align
Name
align
Type
Align
anchorHidden boolean
Name
anchorHidden
Type
boolean
instant PopoverInstant | undefined
Name
instant
Type
PopoverInstant | undefined
data-open
Present when the popup is open.
data-closed
Present when the popup is closed.
data-anchor-hidden
Present when the anchor is hidden.
data-align
Indicates how the popup is aligned relative to specified side.
data-side
Indicates which side the popup is positioned relative to the trigger.
--anchor-height
The anchor's height.
--anchor-width
The anchor's width.
--available-height
The available height between the trigger and the edge of the viewport.
--available-width
The available width between the trigger and the edge of the viewport.
--positioner-height
The height of the popover's positioner. It is important to set height to this value when using CSS to animate size changes.
--positioner-width
The width of the popover's positioner. It is important to set width to this value when using CSS to animate size changes.
--transform-origin
The coordinates that this element is anchored to. Used for animations and transitions.

A container for the popover contents. Renders a <div> element.

initialFocus FocusTarget —
Name
initialFocus
Description

Element to focus when the popover opens. A function receives the open method. true and null use the default. Touch focuses the popup itself so the virtual keyboard stays closed.

Type
FocusTarget
finalFocus FocusTarget —
Name
finalFocus
Description

Element to focus when the popover closes. A function receives the close interaction. null falls back to the trigger. true returns focus there when it is still inside.

Type
FocusTarget
render Snippet<[props: HTMLAttributes<HTMLDivElement>, state: PopoverPopupState, children: Snippet | undefined]> —
Name
render
Type
Snippet<[props: HTMLAttributes<HTMLDivElement>, state: PopoverPopupState, children: Snippet | undefined]>
open boolean
Name
open
Type
boolean
side Side
Name
side
Type
Side
align Align
Name
align
Type
Align
transitionStatus 'starting' | 'ending' | 'idle' | undefined
Name
transitionStatus
Type
'starting' | 'ending' | 'idle' | undefined
instant PopoverInstant | undefined
Name
instant
Type
PopoverInstant | undefined
data-open
Present when the popup is open.
data-closed
Present when the popup is closed.
data-align
Indicates how the popup is aligned relative to specified side.
data-instant
Present if animations should be instant.
data-side
Indicates which side the popup is positioned relative to the trigger.
data-starting-style
Present when the popup begins animating in.
data-ending-style
Present when the popup is animating out.
--popup-height
The height of the popup.
--popup-width
The width of the popup.

Arrow

Displays an element positioned against the popover anchor. Renders a <div>.

render Snippet<[props: HTMLAttributes<HTMLDivElement>, state: PopoverArrowState, children: Snippet | undefined]> —
Name
render
Type
Snippet<[props: HTMLAttributes<HTMLDivElement>, state: PopoverArrowState, children: Snippet | undefined]>
open boolean
Name
open
Type
boolean
side Side
Name
side
Type
Side
align Align
Name
align
Type
Align
uncentered boolean
Name
uncentered
Type
boolean
data-open
Present when the popup is open.
data-closed
Present when the popup is closed.
data-uncentered
Present when the popover arrow is uncentered.
data-align
Indicates how the popup is aligned relative to specified side.
data-side
Indicates which side the popup is positioned relative to the trigger.

Title

A heading that labels the popover. Renders an <h2> element.

render Snippet<[props: HTMLAttributes<HTMLHeadingElement>, state: PopoverTitleState, children: Snippet | undefined]> —
Name
render
Type
Snippet<[props: HTMLAttributes<HTMLHeadingElement>, state: PopoverTitleState, children: Snippet | undefined]>

Description

A paragraph with additional information about the popover. Renders a <p> element.

render Snippet<[props: HTMLAttributes<HTMLParagraphElement>, state: PopoverDescriptionState, children: Snippet | undefined]> —
Name
render
Type
Snippet<[props: HTMLAttributes<HTMLParagraphElement>, state: PopoverDescriptionState, children: Snippet | undefined]>

Close

A button that closes the popover. Renders a <button> element.

disabled boolean | null —
Name
disabled
Type
boolean | null
nativeButton boolean true
Name
nativeButton
Type
boolean
Default
true
render Snippet<[props: HTMLButtonAttributes, state: PopoverCloseState, children: Snippet | undefined]> —
Name
render
Type
Snippet<[props: HTMLButtonAttributes, state: PopoverCloseState, children: Snippet | undefined]>

Viewport

A viewport for displaying content transitions. Renders a <div> element.

render Snippet<[props: HTMLAttributes<HTMLDivElement>, state: PopoverViewportState, children: Snippet | undefined]> —
Name
render
Type
Snippet<[props: HTMLAttributes<HTMLDivElement>, state: PopoverViewportState, children: Snippet | undefined]>
activationDirection string | undefined
Name
activationDirection
Description

The direction from the previous trigger to the new one, as a horizontal and a vertical value separated by a space. Either value is empty when that axis did not move, so 'right ' and ' down' are valid, as in Base UI.

Type
string | undefined
transitioning boolean
Name
transitioning
Type
boolean
instant PopoverInstant | undefined
Name
instant
Type
PopoverInstant | undefined

The Viewport is optional — reach for it only when a single popup is opened by multiple triggers, its content differs per trigger, and the switch between them is animated. When used, set width: var(--positioner-width) and height: var(--positioner-height) on the Positioner so its box is frozen to the measured size during the transition; otherwise content-driven resizing can make the popup thrash or flip to another side.

data-activation-direction
Indicates the direction from which the popup was activated. This can be used to create directional animations based on how the popup was triggered. Contains space-separated values for both horizontal and vertical axes.
data-current
Applied to the direct child of the viewport when no transitions are present or the new content when it's entering.
data-instant
Present if animations should be instant.
data-previous
Applied to the direct child of the viewport that contains the exiting content when transitions are present.
data-transitioning
Indicates that the viewport is currently transitioning between old and new content.
--popup-height
The height of the parent popup. This variable is placed on the 'previous' container and stores the height of the popup when the previous content was rendered. It can be used to freeze the dimensions of the popup when animating between different content.
--popup-width
The width of the parent popup. This variable is placed on the 'previous' container and stores the width of the popup when the previous content was rendered. It can be used to freeze the dimensions of the popup when animating between different content.

createHandle

Creates a new handle to connect a Popover.Root with detached Popover.Trigger components.

Handle

Controls a Popover imperatively and associates detached Popover.Trigger components with a Popover.Root. Create one with Popover.createHandle() and pass it to the handle prop of the root and of any triggers rendered outside of it.

The imperative methods take effect only while a root using this handle is mounted; calls made before a root attaches (or after it unmounts) are ignored.

PropertyTypeModifiersDescription
isOpenbooleanreadonlyWhether the popover is currently open. Returns false while no root is attached to the handle.
payloadPayload \| undefinedreadonlyThe payload of the trigger that opened the popover.

Opens the popover and associates it with the trigger with the given id. It throws when no trigger with that id is registered, because the popover needs a trigger to anchor to.

This method should only be called in an event handler or an effect (not during rendering).

Closes the popover.

This method should only be called in an event handler or an effect (not during rendering).

Ends the closing phase of the popover immediately.