Popover

A surface anchored to the control that opened it, holding content the user has to read or act on. Unlike a tooltip it is announced to screen readers, it can be tabbed into, and it opens on touch — so it is the right home for anything that matters.

Popover or tooltip?

The question is what the trigger is for, not how much text the popup holds.

• If the trigger's purpose is to open the popup — the little "i" info icon is the usual case — it is a popover.
• If the trigger does something else and the popup merely labels it, it is a tooltip.

That distinction decides who can reach the content. A tooltip is never announced, never tabbable, and never opens on touch; a popover is all three. So whenever the content matters, this is the component, and the info-icon pattern in particular belongs here rather than in a tooltip — see Opening on hover below, which gives pointer users the same feel without stranding everyone else.

Import

import { Popover } from "@forte-ui/react";

Anatomy

Popover.Popup collapses Base UI's Portal, Backdrop and Positioner into one part, so the common case is a single element. Its props are drawn from all four.

<Popover.Root>
  <Popover.Trigger />
  <Popover.Popup>
    <Popover.Arrow />
    <Popover.Title />
    <Popover.Description />
    <Popover.Viewport />
    <Popover.Footer>
      <Popover.Close />
    </Popover.Footer>
  </Popover.Popup>
</Popover.Root>

Title, Description and Close belong inside Popover.Popup: that is what wires up aria-labelledby and aria-describedby, and in a modal popover a close button outside the popup is unreachable.

The arrow

There is no arrow prop. Render <Popover.Arrow /> as a child of Popover.Popup and the wedge appears, pointing back at the trigger; leave it out and the popup is a plain rectangle. Nothing else is needed — it positions and rotates itself from the side the popup resolved to, and it takes the popup's own fill and hairline, so a re-skinned popover re-skins the arrow with it.

<Popover.Popup>
  <Popover.Arrow />
  <Popover.Title>Notifications</Popover.Title>
</Popover.Popup>

Two things to know. sideOffset has to leave room for it — the default 8px clears the default arrow, so only a smaller offset is a problem. And with a Popover.Viewport, keep the arrow outside the viewport, as a direct child of the popup: the viewport clips, and the arrow lives past the popup's edge.

Examples

Sides

side on Popover.Popup picks the edge the popup opens from, and align moves it along that edge. Both are hints: the popup flips to the opposite side when it would overflow the collision boundary, which is why the left and right popovers below may land elsewhere in a narrow frame. Alongside the four physical sides, "inline-start" and "inline-end" follow writing direction instead of staying pinned to a physical edge.

Sizes

size sets a width cap, not a width. The popup shrinks to fit its content and only grows this wide when the content asks for it — and it is clamped again to whatever room the positioner reports as available, so a wide popover on a narrow screen narrows rather than overflowing.

Opening on hover

openOnHover on Popover.Trigger reveals the popup on hover as well as on press, with delay and closeDelay tuning the wait. This is the accessible version of the info-icon affordance: pointer users get the tooltip feel, while the content stays announced, tabbable and available on touch.

A form inside

A popover can hold real controls. initialFocus on Popover.Popup says where focus lands when it opens — by default the first tabbable element, except on a touch open, where Base UI focuses the popup itself rather than throwing up the virtual keyboard.

Popover.Footer is the action row. It is not a Base UI part; it exists for the same reason Dialog.Footer does, and takes the same align values — "between" being the one for a destructive action pushed away from the safe one.

Modal

modal on Popover.Root takes the page over: true locks page scroll and disables pointer interaction outside the popup, "trap-focus" traps the keyboard without either. backdrop on Popover.Popup adds the scrim, and belongs with modal={true} — on a non-modal popover a dim page would claim an inertness that is not there.

Tall content

The popup deliberately never scrolls. The Arrow is placed outside the popup's box by the positioner, so any overflow other than visible would crop the wedge off. Put the scroll on something inside instead — a ScrollArea is the ready-made answer — and cap it with --available-height, the room the positioner measured between the anchor and the viewport edge, which the popup passes down by inheritance.

Multiple triggers

One Popover.Root can serve several triggers. Each hands the popup a payload, and the popup reads it from the render-function form of Root's children — so the content is written once and only one popup element is ever mounted.

Guard on payload being undefined. It is undefined before the first open, and again while the popup animates out, because Base UI keeps the popup mounted until the exit transition finishes.

Detached triggers

Popover.createHandle() connects a Popover.Root to triggers that are not its children, for when defining the popup next to its trigger is not practical — a toolbar at the top of a layout and its content at the bottom, say. Pass the same handle to the root and to every trigger. The handle is also an imperative remote: open(triggerId) and close().

Create the handle outside render. One made during render is a new object on every pass, and the root and its triggers stop recognising each other. open() takes a trigger id rather than a payload — the popup still has to be anchored to something — so give each detached trigger an explicit id.

Controlled, with multiple triggers

A controlled multi-trigger popover has two pieces of state: open, and triggerId naming the trigger it is anchored to. There is no separate onTriggerIdChange — the trigger that caused the change arrives on onOpenChange's event details, so both are updated from the one handler. Changing triggerId alone re-anchors the popup without closing it.

Animating between triggers

Popover.Viewport animates the swap when one popup serves several triggers and its content changes between them. It keeps a clone of the outgoing panel mounted for the length of the transition, slides the two past each other in the direction the new trigger lies, and resizes the popup to follow.

Two placement rules. Wrap only the content that changes, and keep Popover.Arrow outside the viewport: the viewport clips, and the arrow lives past the popup's edge. Without a viewport the content still swaps correctly — it just cuts rather than sliding, which is the right choice when the panels are similar enough that the movement would be noise.

Accessibility

Base UI wires the trigger to the popup with aria-haspopup and aria-controls, gives the popup role="dialog", and points aria-labelledby / aria-describedby at Popover.Title and Popover.Description when they are present. Render a title in every popover that holds more than a sentence: it is the popup's accessible name, and without one a screen reader announces an unnamed dialog.

An outside press closes a non-modal popover, and so does focus leaving it. Both report through onOpenChange with a reason, and the event can be cancelled — which is how a popover holding an unsaved form asks before it goes.

In forced-colors mode the popup's shadow is stripped by the browser, so the component carries a transparent border that becomes the visible system-coloured boundary, and the arrow is drawn as two SVG paths rather than the traditional CSS-border triangle, which would degrade into a filled rectangle. Reduced motion is handled by the motion tokens: the travel collapses to 0px and the scale to exactly 1, leaving a plain opacity fade.

Theming

Every value below is a custom property you can override. --forte-popover-z-index is declared on the positioner and --forte-popover-backdrop-z-index on the backdrop; the viewport pair is declared on the viewport, and everything else on the popup.

Where you set these matters. Each one is declared on its own element, so setting it on an ancestor, on :root or on a theme scope has no effect — an element's own declaration wins over an inherited value. Override them on the element that declares them: className on Popover.Popup for most, positionerClassName for the stacking one, backdropClassName for the scrim's. The portal makes the ancestor route doubly useless: the popup renders on document.body, so nothing above the trigger is an ancestor of it in the first place.

To re-skin every popover at once, re-point the global tokens the defaults resolve to — --forte-color-overlay, --forte-color-border, --forte-radius-surface, --forte-surface-p, --forte-shadow-4, --forte-space-*, --forte-font-*, --forte-travel-sm. The popup only reads those and never re-declares them, so a value set on :root or a theme scope does reach it. The knobs with literal defaults — --forte-popover-max-width, --forte-popover-border-width, --forte-popover-arrow-width, --forte-popover-arrow-height and the two z-indexes — have no global token behind them, so those can only be changed on the element itself.

The hairline is worth a word, because Dialog and Drawer do without one. Those sit on a scrim that has already darkened the page behind them; a popover floats over undimmed content, where the overlay and the page background are a single step apart on the grey ramp and the shadow is doing nearly all the separating — which is not enough in dark mode, and less than that over a bright photo. --forte-popover-border-color: transparent gives you the shadow-only look back, and the arrow follows: its outline is the same token, so the wedge flattens in step with the surface rather than keeping an outline the popup no longer has.

The stylesheet also computes --forte-popover-enter-x / --forte-popover-enter-y from --forte-popover-travel and the resolved data-side, and --forte-popover-viewport-x from --forte-popover-viewport-travel and data-activation-direction. They are internal; change the travel tokens instead.

API reference

Popover.Root

Popover.Trigger

Popover.Popup

Renders the portal, the optional backdrop, the positioner and the popup as one part, so its props are drawn from all four.

Popover.Arrow

Popover.Title

Popover.Description

Popover.Close

Popover.Footer

Popover.Viewport

Popover.createHandle

Popover.createHandle<Payload>() returns a handle connecting a Popover.Root to detached Popover.Triggers. Pass it to the handle prop of both. It also exposes open(triggerId), close() and isOpen, which take effect only while a root using the handle is mounted.