Skip to content

Popover

The one floating surface on the Popover API, covering click popovers and tooltips.

Anatomy

<span data-cap="popover">
  <button type="button" class="cap-btn" popovertarget="pop-dims" aria-haspopup="dialog" aria-expanded="false">Dimensions</button>
  <div class="cap-popover" id="pop-dims" popover="auto" role="dialog" aria-labelledby="pop-dims-title" data-side="bottom" data-align="start">
    <div class="cap-popover-header">
      <h2 class="cap-popover-title" id="pop-dims-title">Dimensions</h2>
      <p class="cap-popover-description">Set the size of the status badge.</p>
    </div>
    <button type="button" class="cap-btn" data-popover-close>Done</button>
  </div>
</span>

<span data-cap="popover">
  <button type="button" class="cap-btn">Retry job</button>
  <div class="cap-popover" id="tip-retry" popover="manual" role="tooltip" data-variant="tooltip" data-side="top">Runs job_7c21 again. <kbd>R</kbd></div>
</span>
<Popover>
  <PopoverTrigger>Dimensions</PopoverTrigger>
  <PopoverContent side="bottom" align="start" arrow>
    <PopoverHeader><PopoverTitle>Dimensions</PopoverTitle><PopoverDescription>Set the size.</PopoverDescription></PopoverHeader>
  </PopoverContent>
</Popover>

<Popover kind="tooltip">
  <PopoverTrigger>Retry job</PopoverTrigger>
  <PopoverContent>Runs job_7c21 again.</PopoverContent>
</Popover>
ClassIs
.cap-popoverthe root
.cap-popover-arrowa part
.cap-popover-descriptiona part
.cap-popover-headera part
.cap-popover-titlea part

Data attributes

AttributeValues
data-alignend start
data-cappopover
data-ending-stylepresent or absent
data-flushpresent or absent
data-placedbottom left right top
data-placed-byjs pending
data-sidebottom inline-end inline-start left right top
data-sizeauto lg sm
data-starting-stylepresent or absent
data-varianttooltip
StateRead from
:focusthe platform
:popover-openthe platform

Keyboard

KeyDoes
Enter or Space on the triggerOpens the popover; focus moves into it
Tab, Shift+TabMoves through its controls; leaving it closes it
EscCloses it; focus returns to the trigger
Tab onto a tooltip's triggerShows the tooltip at once
Esc with a tooltip shownHides only the tooltip; it stays hidden until focus or the pointer moves on

API

Popover

PropTypeRequiredDoes
kindKind"dialog" (default): a click popover. "tooltip": detail on hover and keyboard focus.
childrenReactNodeYes

PopoverTrigger

And every attribute of <button>.

PopoverContent

PropTypeRequiredDoes
sideSide
alignAlign
offsetnumberGap from the trigger in px. Default 4.
size"sm" | "md" | "lg" | "auto"
arrowbooleanDraws the arrow pointing at the trigger.

And every attribute of <element>.

PopoverHeader

And every attribute of <element>.

PopoverTitle

And every attribute of <element>.

PopoverDescription

And every attribute of <element>.

Functions

FunctionSignatureDoes
supportsAnchor(): boolean
place(anchor: Element | VirtualAnchor, popup: HTMLElement, options?: PlaceOptions): Placement
attach(trigger: HTMLElement, popup: HTMLElement): () => voidWires a trigger to its popup. The popup's role picks the behavior. Returns a function that unwires it.
openAt(popup: HTMLElement, anchor: VirtualAnchor, options?: PlaceOptions & { returnFocus?: HTMLElement | null | undefined; }): () => voidOpens a popup at a virtual anchor (a text selection, a point in a canvas): shown, placed by script beside the anchor's box, kept beside it as the page scrolls or resizes. Esc and a press outside close it (a popover="auto" popup's own light dismiss), and focus goes back to returnFocus (the editor the selection is in). Returns a function that closes it.
open(popup: HTMLElement): voidOpens a popup (placing it) whether or not it was attached.
close(popup: HTMLElement): void
toggle(popup: HTMLElement): void
enhance(root?: ParentNode): () => voidAttaches every [data-cap="popover"] under root not yet attached. Returns a function that detaches them.

CSS variables

VariableDefault
--_alset by the page
--_arrow0px
--_axset by the page
--_ayset by the page
--_invar(--dur-base)
--_linevar(--line)
--_offcalc(var(--cap-offset, 4px) + var(--_arrow))
--_origintop
--_sidebottom
--_tx0px
--_ty0px
--cap-arrow-x50%
--cap-arrow-y50%
--cap-offset4px
--cap-popover-x0px
--cap-popover-y0px
--transform-originvar(--_origin, center)