Stable in React

Popover

An accessible popup anchored to a button.

Compare Popover in all 5 frameworks

Loading React 19.3.1…

Hover a part or use it. The code follows. · Loading React…

996Tests passing in React · 0 failing

48.6 KiBSize

2.20 msOpen

1.50 msClose

1.03 MiBMemory

productdevbook and 22 upstream authors17 commits · last Nov 4

Install#

One package per framework. Popover's parts come from it; the anatomy tab at the top shows how they nest.

bun add @▢▢▢▢/react

11 parts. The example uses 8 of them; the data does not say which are required.

Popover.RootGroups all parts of the popover.
Popover.TriggerA button that opens the popover.
Popover.PortalA portal element that moves the popup to a different part of the DOM.
Popover.PositionerPositions the popover against the trigger.
Popover.PopupA container for the popover contents.
Popover.ArrowDisplays an element positioned against the popover anchor.
Popover.TitleA heading that labels the popover.
Popover.DescriptionA paragraph with additional information about the popover.
Popover.BackdropAn overlay displayed beneath the popover. Not in the example.
Popover.CloseA button that closes the popover. Not in the example.
Popover.ViewportA viewport for displaying content transitions. Not in the example.

Examples#

Common ways to put it to work. Each one runs live.

openOnHover and delay open the popover when the pointer rests on the trigger.

PopoverOpenOnHover.tsx

Styling and accessibility#

The parts ship no styles. Style their states with these attributes; the CSS tab at the top has a sheet. The same CSS works in all five frameworks.

[data-popup-open]Present when the corresponding popover is open. On Trigger.
[data-pressed]Present when the trigger is pressed. On Trigger.
[data-disabled]Present when the trigger is disabled. On Trigger.
[data-open]Present when the popup is open. On Positioner, Popup, Arrow, Backdrop.
[data-closed]Present when the popup is closed. On Positioner, Popup, Arrow, Backdrop.
[data-anchor-hidden]Present when the anchor is hidden. On Positioner.
[data-side]Indicates which side the popup is positioned relative to the trigger. On Positioner, Popup, Arrow.
[data-align]Indicates how the popup is aligned relative to specified side. On Positioner, Popup, Arrow.
--available-widthThe available width between the trigger and the edge of the viewport. On Positioner.
--available-heightThe available height between the trigger and the edge of the viewport. On Positioner.
--anchor-widthThe anchor's width. On Positioner.
--anchor-heightThe anchor's height. On Positioner.
--transform-originThe coordinates that this element is anchored to. Used for animations and transitions. On Positioner.
--positioner-widthThe width of the popover's positioner. It is important to set width to this value when using CSS to animate size changes. On Positioner.
--positioner-heightThe height of the popover's positioner. It is important to set height to this value when using CSS to animate size changes. On Positioner.
[data-starting-style]Present when the popup begins animating in. On Popup, Backdrop.
[data-ending-style]Present when the popup is animating out. On Popup, Backdrop.
[data-instant]Present if animations should be instant. On Popup, Viewport.
--popup-widthThe width of the popup. On Popup, Viewport.
--popup-heightThe height of the popup. On Popup, Viewport.
[data-uncentered]Present when the popover arrow is uncentered. On Arrow.
[data-current]Applied to the direct child of the viewport when no transitions are present or the new content when it's entering. On Viewport.
[data-previous]Applied to the direct child of the viewport that contains the exiting content when transitions are present. On Viewport.
[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. On Viewport.
[data-transitioning]Indicates that the viewport is currently transitioning between old and new content. On Viewport.

Keyboard

EnterSpaceOpens and closes the popover, also when Trigger renders an element other than <button> On Trigger.
EscapeCloses the popover On Popup.
TabFrom the last element in the popup, moves on to the element after the trigger On Popup.
ShiftTabFrom the popup, moves back to the trigger On Popup.

Set for you

aria-haspopup="dialog", aria-expanded, aria-controlsa screen reader says the button opens a popup and whether it is openTrigger
role="dialog", aria-labelledby to Title, aria-describedby to Descriptionthe popup is announced with its heading and descriptionPopup
sits right after the trigger in the tab order, wherever it is portaledkeyboard users reach the content from the button that opened itPopup
aria-hidden="true"the decorative arrow is not readArrow
role="presentation"the overlay is not readBackdrop

API reference#

35 props across 11 parts, in React syntax, and className, style, render once for every part. Open a row to try it.

Filter props

Popover · all parts

Shared propsEvery part that renders an element takes these.

classNameCSS class applied to the element, or a function that returns a class based on the component's state.string | ((state: State) => string | undefined)

styleStyle applied to the element, or a function that returns a style object based on the component's state.React.CSSProperties | ((state: State) => React.CSSProperties | undefined)

renderAllows you to replace the component's HTML element with a different tag, or compose it with another component.React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, State>

Use it in React#

What differs from the React API. Switch the framework at the top of the page.

@▢▢▢▢/react is the React 19 package. Its parts, props, data attributes and error messages are upstream Base UI's, and upstream's own tests run against it.

Parts
Each component is its own entry point and exports one namespace named after it.
```
import { Switch } from '@base-ui-next/react/switch'

export function Example() {
  return (
    <Switch.Root>
      <Switch.Thumb />
    </Switch.Root>
  )
}
```
A part renders the element its API reference names, such as a <span> for Switch.Root.
Props and events
Props and callbacks have upstream's names and signatures: onCheckedChange(checked, details), onOpenChange(open, details), onValueChange(value, details). details carries reason, event, cancel() and allowPropagation(). Native handlers are React's (onClick, onKeyDown), and event.preventBaseUIHandler() stops a part's own handler.
Styling
className takes a string or a function (state) => string; style takes an object or a function (state) => object. The state's data-* attributes are on the element for CSS.
render
render takes an element (render={<a href="/docs" />}) or a function (props, state) => element that spreads props on what it returns.
Refs
ref reaches the part's element. Imperative handles are ref props, as upstream: inputRef, and actionsRef ({ validate } on Field and Form, { unmount, close } on Dialog).
Binding
A part is controlled when its value prop (checked, open, value) is set, and uncontrolled with the default form (defaultChecked, defaultOpen, defaultValue). React has no two-way binding: pair the value with its change callback.
From @base-ui/react
Change the import from @base-ui/react/<component> to @▢▢▢▢/react/<component>.
From @base-ui/react
Nothing else changes: props, parts, data attributes and errors are the same.