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.
Display options
Choose which records appear in your view.
Archived records
Archived records stay available, but are hidden from the default view.
About visibility
Your display options affect this view only.
<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 apopovertargetrelationship. 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. Thehiddenfallback 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.
| Token | Default | Purpose | Scope / state |
|---|---|---|---|
--popover-width | 18rem | Preferred width. | .popover |
--popover-max-width | 24rem | Maximum width. | .popover |
--popover-max-height | 24rem | Maximum height. | .popover |
--popover-available-width | calc(100vw - 1rem) | Runtime width limit updated by the Showcase positioner. | .popover-panel (runtime) |
--popover-available-height | calc(100vh - 1rem) | Runtime height limit updated by the Showcase positioner. | .popover-panel (runtime) |
--popover-padding | var(--spacer-3) | Inner spacing. | .popover |
--popover-gap | var(--spacer-2) | Space between child elements. | .popover |
--popover-bg-color | var(--bg-surface) | Background color. | .popover |
--popover-color | var(--text-color) | Text and icon color. | .popover |
--popover-border-color | var(--border-color) | Border color. | .popover |
--popover-border-width | var(--border-width) | Border thickness. | .popover |
--popover-border-radius | var(--border-radius) | Corner radius. | .popover |
--popover-box-shadow | var(--shadow-lg) | Outer shadow. | .popover |
--popover-arrow-size | 0.625rem | Width and height of the rotated arrow square. | .popover |
--popover-z-index | var(--z-index-tooltip) | Stacking order. | .popover |