Popover
StableA small non-modal panel anchored to a trigger, for extra detail or a quick choice that does not deserve a dialog: who must review, what a check does, branch info.
When to use
Use it for
- Explaining something next to the control it is about, when the text is too long for a tooltip or contains a link.
- A small form or a couple of actions tied to one control.
- Info icons: Popover (click or openOnHover) instead of Tooltip, so touch and screen reader users can reach it.
Not for
- A list of actions: use Menu, which has the right keyboard model.
- A label for an icon button: use Tooltip.
- A task that must be completed or cancelled: use Dialog.
Do and don't
Every example is rendered with the real component, so it always matches what ships.
Keep it short and anchored
A title, two sentences, at most one or two actions. The arrow shows what it belongs to.
Forms that span several sections
A popover closes on an outside click, so long input gets lost. Use a Dialog or a Drawer.
Accessibility
- Base UI Popover: the trigger exposes aria-expanded and aria-controls; the popup is a dialog named by its title.
- Focus moves into the popup when it opens and back to the trigger when it closes. Escape and outside clicks close it.
- Non-modal by default: the page stays usable. Set modal when the popover holds a small form.
- It flips and shifts to stay in the viewport; the arrow follows the anchor.
Anatomy and tokens
Read from packages/react/src/components/Popover/Popover.module.css at build time. Every value is a token: open one to see its
alias chain in both themes.
- Positioning layer (layer.popover)
.positioner - Surface (popup.bg, popup.border, popup.radius, popup.shadow)
.popup - Surface (popup.bg, popup.border, popup.radius, popup.shadow)
.popup[data-ending-style] - Header
.header - Title
.title - Description
.description - Close button
.close - Arrow
.arrow - Arrow
.arrow[data-side="bottom"] - Arrow
.arrow[data-side="top"] - Arrow
.arrow[data-side="left"], .arrow[data-side="inline-start"] - Arrow
.arrow[data-side="right"], .arrow[data-side="inline-end"]
Props
Parsed from the TypeScript types in packages/react/src/components/Popover/Popover.tsx, so this table cannot drift from the
code.
| Prop | Type | Default | Description |
|---|---|---|---|
open | boolean | none | No description in the code yet. |
defaultOpen | boolean | none | No description in the code yet. |
onOpenChange | (open: boolean) => void | none | No description in the code yet. |
modal | boolean | false | Trap focus and block the page while open. Default false: popovers are light, non-modal surfaces. |
children | ReactNode | none | PopoverTrigger and PopoverContent. |
Playground
Popover has no typed options to play with: it is a container. Compose it with other components and any native attribute. Here it is in both themes.
Workbench
For contributors: every state with the accessibility panel, in the component workbench (Storybook). The stories double as visual test fixtures; the guidance on this page is the user documentation (open Popover in Storybook) .
Embed Storybook stories here (3)
Loads from https://bridge-storybook.floriangouloubi.com (set STORYBOOK_URL at build time). If Storybook is not running, the frames stay
empty.
Default
WithActions
AllStates
Changelog
- New
Overlays: Dialog (sizes, scrolling body, footer, close last in focus order), AlertDialog (destructive confirmations, async confirm), Drawer (start, end, bottom with swipe), Popover, Tooltip with TooltipProvider, Menu (icons, shortcuts, groups, submenus, checkbox and radio items, danger items). Every popup carries the theme, brand and density scope. Adds menu and drawer component tokens.
Unreleased (current version 0.1.0, no release tagged yet) , Oct 17, 2026