Overlays and disclosure

Tooltip / contextual hint

<forma-tooltip>

Supplemental hint on a native button: opens by click, tap or keyboard (popovertarget) and, where supported, on hover or focus (interestfor); light motion with a static reduced-motion substitute.

Authoring tag
<forma-tooltip>
Behavior owner
Native HTML
Canonical source
patterns/tooltip.html

Purpose

A contextual hint explains a term, value or field in one or two sentences without taking space on the page. It is a small native button (forma-tooltip__trigger, usually showing "?" with a visually hidden name) inside an forma-tooltip wrapper, and a popover surface (forma-tooltip__surface). popovertarget opens the hint on click, tap, Enter or Space, so no path depends on hover; Escape or an outside press closes it. Where the browser supports interest invokers, interestfor on the same button also opens it on hover or keyboard focus, and the browser owns the delay and hover travel. Where anchor positioning is supported, the hint is placed next to its button with flip fallbacks that keep it in the viewport. The hint is supplemental: required information and essential actions never live only in it.

Use when

  • A label, column heading or value uses a term some users will not know (error budget, retention period).
  • The explanation is short, plain text and the page is complete without it.
  • A definition applies in several places and repeating it inline would add noise.

Avoid when

  • The information is needed to complete the task, such as a format requirement: put it in visible help text (forma-field__description) instead.
  • The content has links, controls or more than a couple of sentences: use Popover.
  • You want to name an icon-only button: give the button a real accessible name (see Visually hidden); a hint is not a label.
  • The message reports a result or error: use Validation message, Alert or Toast.

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.
  • The trigger is a 44 by 44px round native button, so the hint is reachable by keyboard, touch and switch access.
  • The surface is at most min(20rem, 100vw - 2rem) wide and wraps long words; inverse colors distinguish it from the page.
  • Anchor placement above the button (flipping below or to the other side when there is no room) where supported. Without anchor positioning the surface has margin: 0, so it opens at the block-start, inline-start corner of the viewport, readable but away from its button.
  • Stationary fades in both directions: position and size stay unchanged until fully transparent.

Basic example

The smallest correct markup: the canonical pattern from patterns/tooltip.html inside its public tag. Copy this first, then adapt labels, names and state.

Canonical

Minimal tooltip / contextual hint

Rendered from the canonical pattern file.

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

Retention period: 90 days Events older than the retention period are deleted automatically. Export them first if you need a longer record.

Times use the service region's local time zone.

Required. Changes are scheduled, never applied immediately.

Service Error budget Share of allowed unavailability left in the current 30-day window.
Checkout42% remaining
HTML · Minimal tooltip / contextual hint Raw HTML for HTML · Minimal tooltip / contextual hint
<forma-tooltip class="forma-component-tag">
<div class="forma-stack">
  <p class="forma-tooltip-context">
    Retention period: 90 days
    <span class="forma-tooltip">
      <button class="forma-tooltip__trigger" type="button" popovertarget="tooltip-retention" interestfor="tooltip-retention">
        <span aria-hidden="true">?</span>
        <span class="forma-visually-hidden">About the retention period</span>
      </button>
      <span class="forma-tooltip__surface" id="tooltip-retention" popover>Events older than the retention period are deleted automatically. Export them first if you need a longer record.</span>
    </span>
  </p>

  <div class="forma-field">
    <div class="forma-cluster">
      <label class="forma-field__label" for="tooltip-window">Maintenance window</label>
      <span class="forma-tooltip">
        <button class="forma-tooltip__trigger" type="button" popovertarget="tooltip-window-hint" interestfor="tooltip-window-hint">
          <span aria-hidden="true">?</span>
          <span class="forma-visually-hidden">How maintenance windows are applied</span>
        </button>
        <span class="forma-tooltip__surface" id="tooltip-window-hint" popover>Times use the service region's local time zone.</span>
      </span>
    </div>
    <p class="forma-field__description" id="tooltip-window-description">Required. Changes are scheduled, never applied immediately.</p>
    <input id="tooltip-window" name="window" type="text" aria-describedby="tooltip-window-description" placeholder="Sun 02:00–04:00">
  </div>

  <table>
    <thead>
      <tr>
        <th scope="col">Service</th>
        <th scope="col">
          Error budget
          <span class="forma-tooltip">
            <button class="forma-tooltip__trigger" type="button" popovertarget="tooltip-budget" interestfor="tooltip-budget">
              <span aria-hidden="true">?</span>
              <span class="forma-visually-hidden">About error budget</span>
            </button>
            <span class="forma-tooltip__surface" id="tooltip-budget" popover>Share of allowed unavailability left in the current 30-day window.</span>
          </span>
        </th>
      </tr>
    </thead>
    <tbody>
      <tr><td>Checkout</td><td>42% remaining</td></tr>
    </tbody>
  </table>
</div>
</forma-tooltip>

Click or tap the code once to select all of it, then copy.

Examples

Scenario

Metric definition in a summary

Two terms in a Key-value list each carry a hint. The trigger's hidden text names what the hint is about, so a screen-reader user can tell the two buttons apart. Values stay visible on the page; only the definitions are in hints.

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

Apdex A 0 to 1 score of how many requests met the response-time target. 1 means every request was fast enough.
0.94
p95 latency 95% of requests completed faster than this time.
320 ms
HTML · Metric definition in a summary Raw HTML for HTML · Metric definition in a summary
<forma-tooltip class="forma-component-tag">
  <dl class="forma-key-value-list">
    <div>
      <dt>
        Apdex
        <span class="forma-tooltip">
          <button class="forma-tooltip__trigger" type="button" popovertarget="tooltip-metric-definition-apdex" interestfor="tooltip-metric-definition-apdex"><span aria-hidden="true">?</span><span class="forma-visually-hidden">What is Apdex?</span></button>
          <span class="forma-tooltip__surface" id="tooltip-metric-definition-apdex" popover>A 0 to 1 score of how many requests met the response-time target. 1 means every request was fast enough.</span>
        </span>
      </dt>
      <dd>0.94</dd>
    </div>
    <div>
      <dt>
        p95 latency
        <span class="forma-tooltip">
          <button class="forma-tooltip__trigger" type="button" popovertarget="tooltip-metric-definition-p95" interestfor="tooltip-metric-definition-p95"><span aria-hidden="true">?</span><span class="forma-visually-hidden">What is p95 latency?</span></button>
          <span class="forma-tooltip__surface" id="tooltip-metric-definition-p95" popover>95% of requests completed faster than this time.</span>
        </span>
      </dt>
      <dd>320 ms</dd>
    </div>
  </dl>
</forma-tooltip>

Click or tap the code once to select all of it, then copy.

Scenario

Long translated hint

A longer hint in Spanish with data-forma-motion-weight="standard" on the wrapper, giving a slightly slower settle than the light default. The surface stops at 20rem and wraps, and long compound words break rather than overflow.

Live demo. 1 native action works here and is verified by an outcome test.

Periodo de conservación: 90 días Los eventos más antiguos que el periodo de conservación se eliminan automáticamente cada noche. Si necesita un registro más largo, expórtelos antes desde la página de auditoría.

HTML · Long translated hint Raw HTML for HTML · Long translated hint
<forma-tooltip class="forma-component-tag">
  <p lang="es">
    Periodo de conservación: 90 días
    <span class="forma-tooltip" data-forma-motion-weight="standard">
      <button class="forma-tooltip__trigger" type="button" popovertarget="tooltip-long-hint-standard-weight" interestfor="tooltip-long-hint-standard-weight"><span aria-hidden="true">?</span><span class="forma-visually-hidden">Acerca del periodo de conservación</span></button>
      <span class="forma-tooltip__surface" id="tooltip-long-hint-standard-weight" popover>Los eventos más antiguos que el periodo de conservación se eliminan automáticamente cada noche. Si necesita un registro más largo, expórtelos antes desde la página de auditoría.</span>
    </span>
  </p>
</forma-tooltip>

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

Hint at the edge of a phone screen

A hint whose button sits at the far inline end of a row at phone width. The placement fallbacks move the surface to the side with more room so it stays on screen.

Live demo. 1 native action works here and is 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

  • The trigger stays a 44 by 44px tap target at every width; tapping it opens the hint (popovertarget), and tapping elsewhere closes it. Hover is never required.
  • Where anchor positioning is supported, the hint prefers the area above the button extending toward the inline end, and falls back to the inline start or below, choosing the area with the most room; its width is limited to that area so it cannot overflow the viewport.
  • Without anchor positioning the hint opens at the top-start corner of the viewport; max-inline-size: min(20rem, 100vw - 2rem) keeps it inside at 320px.
  • Long text wraps (overflow-wrap: anywhere); rotating the phone only changes which fallback area is chosen.
HTML · Hint at the edge of a phone screen Raw HTML for HTML · Hint at the edge of a phone screen
<forma-tooltip class="forma-component-tag">
  <div class="forma-cluster">
    <span>Two-step sign-in: Required</span>
    <span class="forma-tooltip">
      <button class="forma-tooltip__trigger" type="button" popovertarget="tooltip-mobile-edge-hint" interestfor="tooltip-mobile-edge-hint"><span aria-hidden="true">?</span><span class="forma-visually-hidden">Why two-step sign-in is required</span></button>
      <span class="forma-tooltip__surface" id="tooltip-mobile-edge-hint" popover>Your organization requires a second step for every account with administrator access.</span>
    </span>
  </div>
</forma-tooltip>

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. 3 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
popovertarget.forma-tooltip__triggerid of the surface—Required. Opens and closes the hint on click, tap, Enter and Space; the non-hover path.
interestfor.forma-tooltip__triggerid of the surface—Optional enhancement. Where interest invokers are supported, hover or focus also opens the hint, with browser-owned delays. Ignored elsewhere.
popover.forma-tooltip__surfaceauto (empty)autoMakes the surface a top-layer popover that light-dismisses on outside press or Escape.
type.forma-tooltip__triggerbutton—Keeps the trigger from submitting a surrounding form.
aria-hiddenthe visible "?" glyphtrue—Hides the glyph so the visually hidden text is the trigger's whole name.
data-forma-motion-weight.forma-tooltiplight | standard | heavylightPresentation-only perceived mass for the hint's entry and exit.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-tooltipBlock class—Inline-flex wrapper that aligns the trigger with surrounding text and scopes the hint's motion (it reduces the motion distance to a small origin-related displacement).
.forma-tooltip__surfaceElement class—The popover hint: inverse surface, small text, max-content width up to 20rem, word wrapping, anchor placement with flip fallbacks where supported, and the entry/exit transition.
.forma-tooltip__triggerElement class—Round native button, at least 44 by 44px, monospace glyph, no padding.
[data-forma-motion-weight]Attribute hook"heavy", "light", "standard"On .forma-tooltip. Presentation-only perceived mass: light (default for hints), standard or heavy.
--forma-motion-fade-easingCustom property—Perceptual curve shared by fade-in and fade-out; no spatial travel.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves focus to the trigger. Where interest invokers are supported, keyboard focus can also show the hint after the browser's delay.
Enter / SpaceToggles the hint (popovertarget).
EscapeCloses the open hint.
Events
EventDescription
beforetoggle / toggleNative popover events on the surface when the hint opens or closes, whichever invoker opened it.

Form behavior

No form participation. The trigger is type="button" so it never submits.

States

Tooltip / contextual hint states
StateHow it is expressedPresentation
Hiddensurface not :popover-openOnly the trigger is visible.
Open:popover-openThe hint appears next to the trigger (anchor placement) or at the viewport's top-start corner (fallback), fully opaque.
Flippedposition-try-fallbacksWhere supported, the hint moves below or to the other side when there is not enough room.
Trigger focus:focus-visible on the triggerShared two-tone focus ring on the round button.

Accessibility

Forma provides

  • Provides a click, tap and keyboard path (popovertarget) so the hint never depends on hover.
  • Keeps the trigger a native button with a 44 by 44px target.
  • Keeps the surface within the viewport with placement fallbacks and a width limit.
  • Uses Canvas/CanvasText with a visible border in forced-colors mode, and removes displacement under reduced motion.

Your application supplies

  • Give every trigger a unique, specific accessible name with forma-visually-hidden text.
  • Keep required information and actions out of hints; show them on the page.
  • Keep hint text short, plain and free of links or controls.
  • Decide any additional focus, timeout or accessible-description policy in application/Limen code.

Responsive behavior

  • The surface is max-content wide up to min(20rem, 100vw - 2rem) and wraps text anywhere.
  • With anchor positioning, position-try-order: most-inline-size picks the area with the most room and the hint never grows beyond that area.
  • Without anchor positioning, the hint sits at the viewport's block-start, inline-start corner (the surface resets the popover's auto margins).
  • The trigger stays 44 by 44px at every width and aligns with surrounding text through vertical-align: middle.

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 on .forma-tooltip changes perceived mass; light is the default.
  • 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

Retention period: 90 days Events older than the retention period are deleted automatically. Export them first if you need a longer record.

Times use the service region's local time zone.

Required. Changes are scheduled, never applied immediately.

Service Error budget Share of allowed unavailability left in the current 30-day window.
Checkout42% remaining
standardpresentation only

Retention period: 90 days Events older than the retention period are deleted automatically. Export them first if you need a longer record.

Times use the service region's local time zone.

Required. Changes are scheduled, never applied immediately.

Service Error budget Share of allowed unavailability left in the current 30-day window.
Checkout42% remaining
heavypresentation only

Retention period: 90 days Events older than the retention period are deleted automatically. Export them first if you need a longer record.

Times use the service region's local time zone.

Required. Changes are scheduled, never applied immediately.

Service Error budget Share of allowed unavailability left in the current 30-day window.
Checkout42% remaining

Usage guidance

Do

  • Write hints as a single definition or clarification in one or two sentences.
  • Place the trigger right after the term it explains.

Avoid

  • Putting hints on every label; if most users need it, show it as help text.
  • Using a hint as the only name of an icon button.
  • Hiding validation rules or error details in a hint.

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.