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.
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.
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.
<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.
<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.
<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.
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.
<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.
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
Attribute
On
Values
Default
Description
popovertarget
.forma-tooltip__trigger
id of the surface
—
Required. Opens and closes the hint on click, tap, Enter and Space; the non-hover path.
interestfor
.forma-tooltip__trigger
id 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__surface
auto (empty)
auto
Makes the surface a top-layer popover that light-dismisses on outside press or Escape.
type
.forma-tooltip__trigger
button
—
Keeps the trigger from submitting a surrounding form.
aria-hidden
the visible "?" glyph
true
—
Hides the glyph so the visually hidden text is the trigger's whole name.
data-forma-motion-weight
.forma-tooltip
light | standard | heavy
light
Presentation-only perceived mass for the hint's entry and exit.
CSS hooks (derived from dist/all.css)
Hook
Kind
Values or default
Description
.forma-tooltip
Block 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__surface
Element 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__trigger
Element 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-easing
Custom property
—
Perceptual curve shared by fade-in and fade-out; no spatial travel.
Keyboard interaction
Keys
Result
Tab / Shift+Tab
Moves focus to the trigger. Where interest invokers are supported, keyboard focus can also show the hint after the browser's delay.
Enter / Space
Toggles the hint (popovertarget).
Escape
Closes the open hint.
Events
Event
Description
beforetoggle / toggle
Native 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
State
How it is expressed
Presentation
Hidden
surface not :popover-open
Only the trigger is visible.
Open
:popover-open
The hint appears next to the trigger (anchor placement) or at the viewport's top-start corner (fallback), fully opaque.
Flipped
position-try-fallbacks
Where supported, the hint moves below or to the other side when there is not enough room.
Trigger focus
:focus-visible on the trigger
Shared 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.
Checkout
42% 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.
Checkout
42% 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.
Checkout
42% 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.