Overlays and disclosure

Popover

<forma-popover>

Top-layer supplemental content built on the Popover API, opened by a native button with no script.

Authoring tag
<forma-popover>
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 and min(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.

Canonical

Minimal popover

Rendered from the canonical pattern file.

Live demo. 2 native actions work here and are verified by an outcome test.

Options

This surface is controlled entirely by declarative HTML.

HTML · Minimal popover Raw HTML for HTML · Minimal popover
<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

Scenario

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
HTML · Keyboard shortcuts panel that stays open Raw HTML for HTML · Keyboard shortcuts panel that stays open
<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.

Scenario

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

  1. 30 Sep 14:02 — Priority changed from Medium to High by Dana.
  2. 30 Sep 11:47 — Assigned to Sam by Dana.
  3. 29 Sep 17:20 — Due date set to 4 October.
  4. 29 Sep 16:05 — Label “billing” added.
  5. 29 Sep 09:31 — Description edited by Priya.
  6. 28 Sep 18:12 — Attachment “invoice-q3.pdf” added.
  7. 28 Sep 15:40 — Status changed from New to Open.
  8. 28 Sep 15:39 — Created by Priya from email.
HTML · Long change history that scrolls Raw HTML for HTML · Long change history that scrolls
<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.

Mobile example

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.

Viewport width

Frames narrower than the selected width show the component at the width available.

What changes at narrow widths

  • At 44rem and below the surface is at most 100vw - 1rem wide and 100dvh - 1rem tall, 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.
HTML · Field help on a phone Raw HTML for HTML · Field help on a phone
<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.

Baseline

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.

Viewport width

Frames narrower than the selected width show the component at the width available.

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.

Native and ARIA attributes
AttributeOnValuesDefaultDescription
popoverthe surfaceauto (empty) | manualautoMakes the element a popover. auto light-dismisses and closes other auto popovers; manual stays open until explicitly hidden.
popovertargetbuttonid of the popover—Connects an invoker button to the popover.
popovertargetactionbuttontoggle | show | hidetoggleWhat the button does to the popover. Use hide on an in-popover Close button.
aria-labelledbythe surfaceid of a heading inside—Names the popover content from its heading.
data-forma-motion-weightthe surfacelight | standard | heavylightPresentation-only perceived mass for entry and exit.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-popoverBlock 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.
Keyboard interaction
KeysResult
Enter / Space on the invokerToggles the popover. Focus stays on the invoker.
TabFrom the invoker, moves into the open popover's focusable content next, then back to the page after it (native popover focus order).
EscapeCloses an auto popover and returns focus to the invoker if focus was inside. Does nothing for popover="manual".
Events
EventDescription
beforetoggleNative event before the popover opens or closes; cancelable when opening.
toggleNative 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

Popover states
StateHow it is expressedPresentation
Hiddennot :popover-openNot displayed. While closing, it fades in place before display and top-layer removal.
Open:popover-openDisplayed in the top layer, fully opaque, at rest.
Scrollingcontent taller than max-block-sizeThe surface scrolls internally; the page does not.
Manualpopover="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 and min(80dvh, 100dvh - 2rem) tall.
  • At 44rem and below: at most 100vw - 1rem wide and 100dvh - 1rem tall.
  • 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-weight does not affect these perceptual fades. The native :popover-open state is authoritative and is never delayed.
  • Under prefers-reduced-motion: reduce the 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:

lightpresentation only
Options

This surface is controlled entirely by declarative HTML.

standardpresentation only
Options

This surface is controlled entirely by declarative HTML.

heavypresentation only
Options

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.