This surface is controlled entirely by declarative HTML.
Popover
<forma-popover>
Top-layer supplemental content built on the Popover API, opened by a native button with no script.
- Authoring tag
<forma-popover>- Category
- Overlays and disclosure
- Behavior owner
- Native HTML
- Canonical source
patterns/popover.html
Purpose
A popover shows supplemental content above the page without blocking it: extra detail, a short explanation, a small set of controls. It is an element with the popover attribute and class="forma-popover", opened and closed by buttons with popovertarget. The browser owns the top layer, open state (:popover-open), light dismiss (outside click and Escape for popover="auto"), and keyboard order from the invoker into the popover. Forma provides the bordered, shadowed surface, viewport-bounded size with internal scrolling, and light perceived-weight entry and exit. Forma does not position the popover next to its invoker: without application anchor positioning it opens at the block-start, inline-start corner of the viewport.
Use when
- The user asks for more detail or a few extra controls and should be able to keep working with the page.
- Content is too long or too interactive for a Tooltip / contextual hint but does not need a modal decision.
- A reference panel (shortcuts, legend, field help) should stay available until explicitly closed (
popover="manual").
Avoid when
- The user must decide before continuing: use Dialog.
- The content is a list of actions: use Action menu.
- The hint is one short sentence attached to a small help button: use Tooltip / contextual hint.
- The content is essential to complete the task: show it in the page, for example with Disclosure or Callout.
Behavior to know
- Opacity fades in and out over the shared fast duration (120ms by default), gently starting, accelerating through the middle, then settling. CSS-only; reduced motion is immediate.
- Non-modal: the page stays interactive;
popover="auto"closes on outside click or Escape,popover="manual"closes only when told to. - At most
min(30rem, 100vw - 2rem)wide andmin(80dvh, 100dvh - 2rem)tall; longer content scrolls inside with contained overscroll. - Placement is not managed by Forma: the surface sits at the viewport's block-start, inline-start corner unless the application positions it.
- Stationary fades in both directions: position and size stay unchanged until fully transparent.
Basic example
The smallest correct markup: the canonical pattern from patterns/popover.html inside its public tag. Copy this first, then adapt labels, names and state.
Minimal popover
Rendered from the canonical pattern file.
Live demo. 2 native actions work here and are verified by an outcome test.
This surface is controlled entirely by declarative HTML.
<forma-popover class="forma-component-tag">
<button type="button" popovertarget="example-popover">Show options</button>
<div class="forma-popover" id="example-popover" popover data-forma-motion-weight="light">
<strong>Options</strong>
<p>This surface is controlled entirely by declarative HTML.</p>
<button type="button" popovertarget="example-popover" popovertargetaction="hide">Close</button>
</div>
</forma-popover>
Click or tap the code once to select all of it, then copy.
Examples
Keyboard shortcuts panel that stays open
A reference the user keeps open while working. popover="manual" disables light dismiss, so clicking the page or pressing Escape does not close it; the Close button and the invoker (which toggles) do. The popover is named by its heading through aria-labelledby.
Live demo. 2 native actions work here and are verified by an outcome test.
Keyboard shortcuts
- N
- New work item
- /
- Focus search
- G then B
- Go to board
<forma-popover class="forma-component-tag">
<button type="button" popovertarget="popover-manual-reference-panel">Keyboard shortcuts</button>
<div class="forma-popover" id="popover-manual-reference-panel" popover="manual" aria-labelledby="popover-manual-reference-panel-title">
<h2 id="popover-manual-reference-panel-title">Keyboard shortcuts</h2>
<dl class="forma-key-value-list">
<div><dt><kbd>N</kbd></dt><dd>New work item</dd></div>
<div><dt><kbd>/</kbd></dt><dd>Focus search</dd></div>
<div><dt><kbd>G</kbd> then <kbd>B</kbd></dt><dd>Go to board</dd></div>
</dl>
<button type="button" popovertarget="popover-manual-reference-panel" popovertargetaction="hide">Close shortcuts</button>
</div>
</forma-popover>
Click or tap the code once to select all of it, then copy.
Long change history that scrolls
An auto popover with more content than fits. The surface stops at min(80dvh, 100dvh - 2rem) and scrolls internally without scrolling the page. data-forma-motion-weight="standard" gives the larger surface a slightly slower settle than the light default.
Live demo. 2 native actions work here and are verified by an outcome test.
Change history
- 30 Sep 14:02 — Priority changed from Medium to High by Dana.
- 30 Sep 11:47 — Assigned to Sam by Dana.
- 29 Sep 17:20 — Due date set to 4 October.
- 29 Sep 16:05 — Label “billing” added.
- 29 Sep 09:31 — Description edited by Priya.
- 28 Sep 18:12 — Attachment “invoice-q3.pdf” added.
- 28 Sep 15:40 — Status changed from New to Open.
- 28 Sep 15:39 — Created by Priya from email.
<forma-popover class="forma-component-tag">
<button type="button" popovertarget="popover-long-change-history">Change history (12)</button>
<div class="forma-popover" id="popover-long-change-history" popover data-forma-motion-weight="standard" aria-labelledby="popover-long-change-history-title">
<h2 id="popover-long-change-history-title">Change history</h2>
<ol>
<li>30 Sep 14:02 — Priority changed from Medium to High by Dana.</li>
<li>30 Sep 11:47 — Assigned to Sam by Dana.</li>
<li>29 Sep 17:20 — Due date set to 4 October.</li>
<li>29 Sep 16:05 — Label “billing” added.</li>
<li>29 Sep 09:31 — Description edited by Priya.</li>
<li>28 Sep 18:12 — Attachment “invoice-q3.pdf” added.</li>
<li>28 Sep 15:40 — Status changed from New to Open.</li>
<li>28 Sep 15:39 — Created by Priya from email.</li>
</ol>
<button type="button" popovertarget="popover-long-change-history" popovertargetaction="hide">Close history</button>
</div>
</forma-popover>
Click or tap the code once to select all of it, then copy.
Mobile
Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.
Field help on a phone
A help popover beside a form field at phone width. The surface is bounded to the viewport minus a small margin and wraps its text.
Live demo. 2 native actions work here and are verified by an outcome test.
What changes at narrow widths
- At 44rem and below the surface is at most
100vw - 1remwide and100dvh - 1remtall, so it never causes horizontal scrolling at 320px. - Content that does not fit scrolls inside the popover with contained overscroll; the page behind does not scroll.
- Tapping outside or pressing the Close button dismisses an auto popover; there is no hover path to depend on.
- The surface still opens at the viewport's top-start corner rather than beside the field; on phones this keeps it fully visible, but the application should position it if proximity matters.
<forma-popover class="forma-component-tag">
<div class="forma-field">
<label class="forma-field__label" for="popover-mobile-field-help-iban">IBAN</label>
<input id="popover-mobile-field-help-iban" name="iban" type="text" autocomplete="off" aria-describedby="popover-mobile-field-help-hint">
<p class="forma-field__description" id="popover-mobile-field-help-hint">Up to 34 letters and numbers, starting with a country code.</p>
<button type="button" popovertarget="popover-mobile-field-help">Where do I find my IBAN?</button>
</div>
<div class="forma-popover" id="popover-mobile-field-help" popover aria-labelledby="popover-mobile-field-help-title">
<h2 id="popover-mobile-field-help-title">Finding your IBAN</h2>
<p>It is printed on your bank statement and shown in your banking app under account details. It starts with two letters for the country, for example DE or NL.</p>
<button type="button" popovertarget="popover-mobile-field-help" popovertargetaction="hide">Close help</button>
</div>
</forma-popover>
Click or tap the code once to select all of it, then copy.
Mobile · 320px
The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.
Live demo. 2 native actions work here and are verified by an outcome test.
API and configuration
Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.
| Attribute | On | Values | Default | Description |
|---|---|---|---|---|
popover | the surface | auto (empty) | manual | auto | Makes the element a popover. auto light-dismisses and closes other auto popovers; manual stays open until explicitly hidden. |
popovertarget | button | id of the popover | — | Connects an invoker button to the popover. |
popovertargetaction | button | toggle | show | hide | toggle | What the button does to the popover. Use hide on an in-popover Close button. |
aria-labelledby | the surface | id of a heading inside | — | Names the popover content from its heading. |
data-forma-motion-weight | the surface | light | standard | heavy | light | Presentation-only perceived mass for entry and exit. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-popover | Block class | — | The popover surface: border, primary surface, shadow, 1rem padding, viewport-bounded size, internal scrolling with contained overscroll, and the entry/exit transition. Sets margin: 0 and no anchor, so it sits at the viewport's block-start, inline-start corner. |
[data-forma-motion-weight] | Attribute hook | "heavy", "light", "standard" | Presentation-only perceived mass: light (default for popovers), standard or heavy. |
| Keys | Result |
|---|---|
| Enter / Space on the invoker | Toggles the popover. Focus stays on the invoker. |
| Tab | From the invoker, moves into the open popover's focusable content next, then back to the page after it (native popover focus order). |
| Escape | Closes an auto popover and returns focus to the invoker if focus was inside. Does nothing for popover="manual". |
| Event | Description |
|---|---|
beforetoggle | Native event before the popover opens or closes; cancelable when opening. |
toggle | Native event after the popover opened or closed. |
Form behavior
The popover does not participate in forms itself. Controls inside it belong to their form as usual, but an auto popover can be light-dismissed while the user is typing, so avoid unsaved input in auto popovers.
States
| State | How it is expressed | Presentation |
|---|---|---|
| Hidden | not :popover-open | Not displayed. While closing, it fades in place before display and top-layer removal. |
| Open | :popover-open | Displayed in the top layer, fully opaque, at rest. |
| Scrolling | content taller than max-block-size | The surface scrolls internally; the page does not. |
| Manual | popover="manual" | No light dismiss; closes only via popovertarget buttons (or script). |
Accessibility
Forma provides
- Builds on the native Popover API, so open state, light dismiss, Escape and invoker-to-popover focus order come from the browser.
- Keeps the surface inside the dynamic viewport with contained internal scrolling.
- Keeps a visible border in forced-colors mode and makes transitions effectively instant under reduced motion.
Your application supplies
- Give the invoker a label that says what opens, and name the popover with a heading and aria-labelledby.
- Include a visible close button for touch and switch users, especially for manual popovers.
- Position the popover near its invoker (for example with CSS anchor positioning) when proximity matters; Forma does not.
- Do not put required information or the only path to an action in a popover.
- If the popover should behave as a dialog or menu for assistive technology, supply that role and behavior in application code.
Responsive behavior
- Above 44rem: at most
min(30rem, 100vw - 2rem)wide andmin(80dvh, 100dvh - 2rem)tall. - At 44rem and below: at most
100vw - 1remwide and100dvh - 1remtall. - Text wraps; content beyond the height limit scrolls inside with contained overscroll.
- No collision handling or placement fallback is provided for
.forma-popover.
Motion
- Entry and exit: opacity alone follows the shared 120ms slow-fast-slow curve, at unchanged position and size.
- Exit cleanup: display and top-layer placement are retained until opacity is zero where overlay retention is supported; otherwise native dismissal is immediate.
data-forma-motion-weightdoes not affect these perceptual fades. The native:popover-openstate is authoritative and is never delayed.- Under
prefers-reduced-motion: reducethe stationary fade reaches its endpoint effectively immediately.
Motion weights
Forma motion is physics-derived: perceived mass changes how a surface accelerates and settles, never what state it is in. Compare the three presentation weights of the same markup:
This surface is controlled entirely by declarative HTML.
This surface is controlled entirely by declarative HTML.
Usage guidance
Do
- Keep popover content short and supplemental, with a heading when it holds more than a sentence.
- Use
popover="manual"for reference panels users keep open while working.
Avoid
- Opening popovers on hover only.
- Nesting dialogs inside popovers.
- Relying on the default placement for content that must appear beside its trigger on wide screens.
Verification specimens
Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.