Popover

A small panel opened from a button: a short form, settings or a date picker, with the page usable around it.

Installation

npx @yolkui/cli add popover

Usage

Pass the button that opens it through render: render={<Button variant="outline" />}. PopoverContent opens 6 below it, centred, and flips when there is no room; PopoverHeader holds a PopoverTitle and a PopoverDescription. A click opens it, and Escape, a click outside or the button again close it; focus moves to the first control inside and goes back to the button. The page around it stays usable.

  • There is no × by default. When a popover needs a visible way out, or actions, add a PopoverClose rendered as a Button.
  • It is 288 wide with 16 inside; change both with className (className="w-auto p-0" for a Calendar).
  • For a short text on hover use a Tooltip; for something that needs the person's full attention, a Dialog.

Buttons that close it

PopoverClose rendered as a Button closes the popover from inside: Cancel and Send here. Run your request in its onClick.

Alignment

align lines it up with the trigger's start, centre (the default) or end; side puts it above, below or beside it (top, bottom, inline-start, inline-end). In a right-to-left app start and the inline sides follow Base UI's DirectionProvider.

Right to left

In a right-to-left app wrap the root in <DirectionProvider direction="rtl"> beside dir="rtl": align="start" then lines the popover up with the trigger's right edge, and inline-start and inline-end swap sides. The content is in a portal, so give it dir and lang too, or set them once on <html>.

Date picker

A Calendar in a Popover is the date picker; the example is on the Calendar page.

API

Our defaults on top of Base UI's Popover (open, defaultOpen, onOpenChange, modal, openOnHover, delay, actionsRef, handle and the rest work as in Base UI).

PropOnValuesDefault
sidePopoverContent"top" · "bottom" · "inline-start" · "inline-end""bottom"
sideOffsetPopoverContentpx from the trigger6
alignPopoverContent"start" · "center" · "end""center"
alignOffsetPopoverContentpx along the trigger0
collisionPaddingPopoverContentpx it keeps from the screen's edges8
anchorPopoverContentan element or ref to open beside, instead of the triggerthe trigger
createPopoverHandle()—links triggers anywhere to one popover, with a payload—

Accessibility

The popover is a dialog to a screen reader, named by its PopoverTitle and described by its PopoverDescription. The button that opens it says it has a popup and whether it is open.

  • Give every popover a name: a PopoverTitle, or an aria-label on PopoverContent when it has no title (a date picker). In development a warning says when it has none.
  • Focus moves inside when it opens and back to the button when it closes, so keyboard users never lose their place.
  • It is not modal: Tab can leave it, and the page stays usable. For something that must be answered first, use a Dialog.
  • modal (or modal="trap-focus") keeps focus inside, but only when a PopoverClose is in it (Base UI's rule, so touch screen-reader users can leave); it may be visually hidden with className="sr-only". In development a warning says when it is missing.
  • A disabled trigger (disabled on the Button) stays focusable and never opens, so a Tooltip can say why.