Popover

A non-modal anchored surface for rich content, actions and form controls.

When to use

Use a Popover when content needs more space or interaction than a Tooltip, but does not need the command keyboard model of a Menu. A callout or flyout may use this surface when it opens from a trigger. For a blocking task, use a Modal.

Informational callout

This static preview shows a labelled region with a heading and explanatory copy. Its visible panel has no interaction script.

Actions and rich content

Use ordinary links and buttons with their native keyboard behavior. Do not give them menu item roles.

Form controls

The panel can contain labelled native fields and explanatory text. Keep task completion in the application that owns the form.

Interactive

Click a trigger to open its Popover. Try keyboard activation, Escape, clicking outside, and the nested details Popover. The Showcase uses Floating UI to place each panel at its trigger, flip or shift it near viewport edges, and update it on scroll or resize. The second trigger prefers a top placement; data-popover-placement also accepts right, left, and -start or -end alignment.

HTML
<div class="popover" data-popover>
	<button class="btn popover-trigger" type="button" data-popover-trigger>Display options</button>
	<div
		class="popover-panel"
		role="region"
		popover="manual"
		hidden
		tabindex="-1"
		data-popover-panel
		data-popover-placement="bottom-start">
		<div class="popover-content">
			<h3 class="popover-title">Display options</h3>
			<label><input type="checkbox" /> Show archived records</label>
			<button type="button" data-popover-close>Apply options</button>
		</div>
		<div class="popover-arrow" aria-hidden="true"></div>
	</div>
</div>

Behavior and accessibility

  • The Showcase script adds aria-controls, aria-expanded, a region label and a popovertarget relationship. Mark the panel as a region when its content merits a landmark. The panel is non-modal and never traps focus.
  • Keyboard activation moves focus to the first usable control, or to an informational panel. Pointer activation leaves focus where it is. Escape closes the most recently opened panel and returns focus to its trigger. Outside pointer or focus movement dismisses an open panel without moving focus.
  • Each Popover has its own state. Closing a parent also closes its nested panels. The Showcase closes open panels before Astro swaps pages.
  • Native popover="manual" provides top-layer rendering when available. The hidden fallback stays in normal document stacking and can be clipped by an ancestor. Applications must provide the dismissal and positioning script; the published package contains styles only.

CSS variables

Override these base defaults on the listed selector after the library styles. Variants and states may replace them; global tokens follow the active theme.

TokenDefaultPurposeScope / state
--popover-width18remPreferred width..popover
--popover-max-width24remMaximum width..popover
--popover-max-height24remMaximum height..popover
--popover-available-widthcalc(100vw - 1rem)Runtime width limit updated by the Showcase positioner..popover-panel (runtime)
--popover-available-heightcalc(100vh - 1rem)Runtime height limit updated by the Showcase positioner..popover-panel (runtime)
--popover-paddingvar(--spacer-3)Inner spacing..popover
--popover-gapvar(--spacer-2)Space between child elements..popover
--popover-bg-colorvar(--bg-surface)Background color..popover
--popover-colorvar(--text-color)Text and icon color..popover
--popover-border-colorvar(--border-color)Border color..popover
--popover-border-widthvar(--border-width)Border thickness..popover
--popover-border-radiusvar(--border-radius)Corner radius..popover
--popover-box-shadowvar(--shadow-lg)Outer shadow..popover
--popover-arrow-size0.625remWidth and height of the rotated arrow square..popover
--popover-z-indexvar(--z-index-tooltip)Stacking order..popover