Popover | Base Design System

Popover is the container that positions transient content next to its trigger — a Menu, a form, a bit of detail. It handles anchoring, flipping, and dismissal; what goes inside is yours. For a modal that blocks the page, use Dialog.

DialogTrigger pairs the trigger with the Popover; the popover opens on press and closes on Escape or an outside press.

import { DialogTrigger } from 'react-aria-components';
import { Button } from '@base-org/bds-web/product/button';
import { Popover } from '@base-org/bds-web/product/popover';

DialogTrigger comes from react-aria-components; BDS does not re-export it.

<DialogTrigger>
<Button variant="outline">Open Popover</Button>
<Popover>
  <div className="p-4 text-body text-bds-gray-80">Popover content</div>
</Popover>
</DialogTrigger>

offset defaults to 8px of gap between the trigger and the surface. The popover flips to the opposite side when there is no room, so treat placement as a preference rather than a guarantee.

Entrance

entrance sets how the surface appears. The default, scale, grows it from the trigger. drop also slides it 6px in from the trigger's side, down when it opens below and up when it opens above, so a list feels attached to a compact trigger such as a pill Select. Both leave with the same short fade.

<DialogTrigger>
<Button variant="outline">Open Popover</Button>
<Popover entrance="drop">
  <div className="p-4 text-body text-bds-gray-80">Popover content</div>
</Popover>
</DialogTrigger>

When to use

Use Popover for transient content anchored to its trigger — a short form, a bit of detail — that the reader can dismiss with an outside press.

Use something else when:

The content is required or must not be lost by accident. Use Dialog.
It only names a control. Use Tooltip.
It is a list of actions. Use Menu, which renders inside a Popover for you.

Usage

Give the surface its own padding. Popover clips its content but adds no inset, so lay out the children as you want them.

Don't

Put a required step or a destructive confirmation in a popover. It dismisses on an outside press — anything the reader must not lose belongs in a Dialog.

Props

Prop	Type	Default
`arrowBoundaryOffset` The minimum distance the arrow's edge should be from the edge of the overlay element.	Type`number`	Default`0`
`arrowRef` A ref for the popover arrow element.	Type`RefObject<Element \| null>`	Default—
`boundaryElement` Element that that serves as the positioning boundary.	Type`Element`	Default`document.body`
`children` The children of the component. A function may be provided to alter the children based on	Type`ChildrenOrFunction<PopoverRenderProps>`	Default—
`className` The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the	Type`ClassNameOrFunction<PopoverRenderProps>`	Default—
`containerPadding` The placement padding that should be applied between the element and its	Type`number`	Default`12`
`crossOffset` The additional offset applied along the cross axis between the element and its	Type`number`	Default`0`
`defaultOpen` Whether the overlay is open by default (uncontrolled).	Type`boolean`	Default—
`entrance` How the surface enters. `scale` grows it from the trigger; `drop` also	Type`"scale" \| "drop"`	Default`scale`
`getTargetRect` Overrides the target element's bounding rectangle. Useful for positioning relative to	Type`((target: Element) => DOMRect \| null)`	Default`target.getBoundingClientRect()`
`isEntering` Whether the popover is currently performing an entry animation.	Type`boolean`	Default—
`isExiting` Whether the popover is currently performing an exit animation.	Type`boolean`	Default—
`isKeyboardDismissDisabled` Whether pressing the escape key to close the popover should be disabled.	Type`boolean`	Default`false`
`isNonModal` Whether the popover is non-modal, i.e. elements outside the popover may be	Type`boolean`	Default—
`isOpen` Whether the overlay is open by default (controlled).	Type`boolean`	Default—
`maxHeight` The maxHeight specified for the overlay element.	Type`number`	Default—
`offset` The additional offset applied along the main axis between the element and its	Type`number`	Default`8`
`placement` The placement of the element with respect to its anchor element.	Type`enum`	Default`'bottom'`
`scrollRef` A ref for the scrollable region within the overlay.	Type`RefObject<Element \| null>`	Default`overlayRef`
`shouldCloseOnInteractOutside` When user interacts with the argument element outside of the popover ref,	Type`((element: Element) => boolean)`	Default—
`shouldFlip` Whether the element should flip its orientation (e.g. top to bottom or left to right) when	Type`boolean`	Default`true`
`shouldSkipAnimation` Whether the popover should appear and disappear without an entry or exit animation. This is	Type`boolean`	Default—
`shouldUpdatePosition` Whether the overlay should update its position automatically.	Type`boolean`	Default`true`
`trigger` The name of the component that triggered the popover. This is reflected on the element	Type`string`	Default—
`triggerRef` The ref for the element which the popover positions itself with respect to.	Type`RefObject<Element \| null>`	Default—
`UNSTABLE_portalContainer` The container element in which the overlay portal will be placed. This may have unknown	Type`Element`	Default`document.body`

Accessibility

Popover wraps React Aria's Popover, which is modal by default: while open it hides the rest of the page from assistive technology, dismisses on Escape or an outside press, and returns focus to the trigger on close. Interactive content inside, such as a Menu, carries its own roles, focus handling, and keyboard behaviour.

The surface grows from the trigger as it opens, dropping in slightly with entrance="drop", and leaves with a shorter, smaller fade. When the reader prefers reduced motion, it appears and disappears without animating or moving.