Tooltip
A short description of a control shown on hover and focus; role tooltip linked by aria-describedby, a 1px overlay border on the raised surface, no arrow.
stable · light DOM · 4.0.0. Light DOM retains static content, native semantics, label relationships and host composition without duplicating controls.
Live variants
default
<j3w1-tooltip id="example-tooltip-default"><div class="tooltip">
<button class="tooltip-trigger" type="button" aria-describedby="example-tooltip-default-tt-reload">Reload</button>
<div class="tooltip-popup" role="tooltip" id="example-tooltip-default-tt-reload">Reload the window and keep the layout.</div>
</div></j3w1-tooltip>with-shortcut
<j3w1-tooltip id="example-tooltip-with-shortcut"><div class="tooltip">
<button class="tooltip-trigger" type="button" aria-describedby="example-tooltip-with-shortcut-tt-split">Split</button>
<div class="tooltip-popup" role="tooltip" id="example-tooltip-with-shortcut-tt-split">Split the focused container horizontally <kbd class="tooltip-shortcut">Mod+h</kbd></div>
</div></j3w1-tooltip>Install and register
Use the exact version. If npm publication is pending, install the release tarball from the installation guide.
npm install --save-exact @j3w1/ui@4.0.0import '@j3w1/ui/tokens.css';
import '@j3w1/ui/styles/tooltip.css';
import '@j3w1/ui/register/tooltip';Insert the maintained markup above after loading these imports. Its native children provide accessible names and form behavior; the empty custom tag alone does not create a control.
Copy the complete implementation
npx --package=@j3w1/ui@4.0.0 j3w1-ui copy tooltip --out ./vendor/j3w1/tooltipThe CLI verifies every file before writing and refuses overwrites. Serve the output over HTTP and open index.html. Keep its modules, CSS, tokens and licence notices together.
Public API
attributes
| Name | Type / signature | Meaning |
|---|---|---|
disabled | CustomEvent | Disable the native controls owned by this instance. |
loading | CustomEvent | Mark the primary control busy and prevent duplicate activation. |
properties
| Name | Type / signature | Meaning |
|---|---|---|
disabled | boolean | Delegates disabled state to native children. |
name | string | Native control name; application form keys remain explicit. |
open | boolean | Current tooltip visibility. Read only. |
methods
| Name | Type / signature | Meaning |
|---|---|---|
refresh | (): void | Reconnect behavior after replacing native child structure. |
focus | (options?: FocusOptions): void | Focus the first usable native control. |
show | (): void | Show the description unless dismissed in this hover/focus session. |
hide | (): void | Hide and cancel pending timers. |
events
| Name | Type / signature | Meaning |
|---|
Dependencies and verification
Registered components: none. Style dependencies: none.
Package presence establishes an available implementation. Actual passes depend on the tested artifact and environment. Read specification execution evidence; read packed-consumer evidence; inspect the complete state matrix.
Full implementation manifest, API and token dependency closure
Canonical specification
Tooltip tooltip
A short description of a control shown on hover and focus; role tooltip linked by aria-describedby, a 1px overlay border on the raised surface, no arrow.
Report an issue with this component
Tokens
Focus a role to inspect its values; follow its link for persistent usage and source details.
| Part | Role | Value | Use |
|---|---|---|---|
popup.bg | color.surface.raisedapproveduse | #140b0b | D-041 surface.raised: color.primitive.modern.raised. |
popup.border | color.border.overlayapproveduse | #c81a1a | D-041 owner correction: red control and floating-frame borders, distinct from rose text. |
popup.text | color.text.defaultapproveduse | #e99499 | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
shortcut.text | color.text.brightapproveduse | #ffa2a7 | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
shortcut.border | color.border.controlapproveduse | #c81a1a | D-041 owner correction: red control and floating-frame borders, distinct from rose text. |
trigger.text | color.action.tertiary.textapproveduse | #e99499 | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
trigger.bg-hover | color.action.tertiary.hover-bgobserveduse | #1c0a09 | Ghost and icon button hover. |
trigger.ring | color.interaction.focus.ringobserveduse | #e53935 | 1px dashed focus ring on controls and rows. |
popup.z | z.popoverobserveduse | 10 |
State matrix
Every declared state and combination, statically rendered; the default cell is live. Sizes: compact, comfortable (switch with the density control above).
| State | Description | With shortcut |
|---|---|---|
default | Reload the window and keep the layout.
| Split the focused container horizontally Mod+h
|
hover | ||
focus-visible | ||
open | ||
closed |
Purpose
Describes a control without being its name: what an icon button does, its shortcut, why it is disabled. Anything needed to use the control belongs in the control or its label; anything interactive is a popover.
Anatomy
Parts as listed in the anatomy; no arrow, shadow or radius.
States
| State | Visual | Non-colour channel |
|---|---|---|
| default | trigger at rest; popup shown for the demonstration | aria-describedby on the trigger |
| hover | trigger background → color.action.tertiary.hover-bg; popup after 300 ms; it hides 300 ms after the pointer leaves trigger and popup | cursor: pointer; the popup |
| focus-visible | 1px dashed color.interaction.focus.ring at −2px on the trigger; popup at once | the ring; the popup |
| open | popup visible, 1px color.border.overlay on color.surface.raised | popup in the accessibility tree |
| closed | popup absent; trigger unchanged | hidden; the description is still read from the DOM |
The popup has no hover, pressed or focus state; it is not interactive.
Keyboard
As in the key table. Escape does nothing else, so a dialog behind the trigger stays open. The popup never receives focus and contains nothing focusable.
Accessibility
The popup stays open while the pointer is over the trigger or the popup (WCAG 1.4.13: hoverable, dismissible, persistent). The trigger has its own accessible name; the tooltip never supplies it. Touch has no hover: offer the description by long-press or inline. Text meets 4.5:1; the popup border and the shortcut border 3:1.
Portability
A bordered box of text; placement is the host’s positioning primitive. A toolkit with a native tooltip uses it with the border and background tokens and records any radius it cannot remove.
Non-examples
A rounded bubble with an arrow. A shadow, or a fade longer than 150 ms. The
tooltip as an icon button’s only accessible name. A link or button inside.
Opening on focus but not hover, or on hover with no delay. A title
attribute. Following the pointer.
Contrast report
10 declared pairs measured on resolved sRGB values with the WCAG 2.x formula; 0 waived (decorative only), 0 failing. A pass is a design target for the named role, not an application-wide conformance claim.
| Pair | State | Kind | Foreground | Background | Ratio | Min | Result |
|---|---|---|---|---|---|---|---|
| tooltip default text | default | text | color.text.default #e99499 | color.surface.raised #140b0b | 8.46 | 4.5 | pass |
| tooltip default border | default | ui | color.border.overlay #c81a1a | color.surface.raised #140b0b | 3.34 | 3 | pass |
| tooltip hover text | hover | text | color.action.tertiary.text #e99499 | color.action.tertiary.hover-bg #1c0a09 | 8.35 | 4.5 | pass |
| tooltip focus-visible text | focus-visible | text | color.action.tertiary.text #e99499 | color.surface.canvas #000000 | 9.16 | 4.5 | pass |
| tooltip focus-visible outline | focus-visible | ui | color.interaction.focus.ring #e53935 | color.surface.canvas #000000 | 4.97 | 3 | pass |
| tooltip open text | open | text | color.text.default #e99499 | color.surface.raised #140b0b | 8.46 | 4.5 | pass |
| tooltip open border | open | ui | color.border.overlay #c81a1a | color.surface.raised #140b0b | 3.34 | 3 | pass |
| shortcut on the tooltip | — | text | color.text.bright #ffa2a7 | color.surface.raised #140b0b | 10.14 | 4.5 | pass |
| shortcut key border on the tooltip | — | ui | color.border.control #c81a1a | color.surface.raised #140b0b | 3.34 | 3 | pass |
| trigger text on the canvas | — | text | color.action.tertiary.text #e99499 | color.surface.canvas #000000 | 9.16 | 4.5 | pass |
Keys
| Key | Action |
|---|---|
| Tab | Focusing the trigger shows the tooltip; leaving it hides the tooltip. |
| Escape | Hides the tooltip without moving focus; the trigger's own Escape behaviour is not triggered. |
| Enter / Space | Act on the trigger as usual; the tooltip hides on activation. |
For agents
Component JSON ·Implementation brief ·Build a task kit ·
Related: icon-button popover kbd toolbar menu
Stress fixtures: FX-LONG FX-320 FX-ZOOM-200 FX-I18N FX-RTL FX-RM FX-HC FX-OVERFLOW FX-STATE-MATRIX