Placement
Four placements: top (default), bottom, left, right. The tooltip is positioned relative to its trigger using absolute coordinates on document.body, so it never clips inside overflow-hidden containers.
Usage examples
On a badge78% adoption ⓘ
On an icon button
On a disabled button
Behaviour
Triggermouseenter / mouseleave and focus / blur. No click required.DelayNone in v1. Enter delay (150–200ms) deferred to v2 to prevent flicker on fast cursors.DismissAutomatically on mouseleave or blur. Not dismissible by keyboard (Escape).PointerpointerEvents: none on the tooltip — it never intercepts hover and creates dead zones.Max width240px with word-wrap. Content beyond that wraps to a second line.z-index1200 — above modals (1000) and toasts (1100).Accessibility
role="tooltip"Applied to the tooltip element so screen readers announce it as supplemental info.aria-describedbySet on the trigger (pointing to the tooltip id) while the tooltip is visible.focus triggerTooltip appears on keyboard focus, not only on hover — required for WCAG 2.1 SC 1.4.13.Disabled buttonsWrap a disabled button in a <span> so it can receive hover/focus and show the tooltip.Usage guidance
DoUse for icon-only controls that have no visible label.DoUse to define jargon or metric abbreviations (e.g., "78% adoption" → explain what adoption means).DoKeep content to one or two short sentences. Tooltips are not docs.Don'tPut interactive elements (links, buttons) inside a tooltip — use a popover instead.Don'tUse a tooltip to communicate an error — use a field error or toast.Don'tTooltip a label that already describes itself. "Save button → saves your work" adds no value.Tokens used
neutral/900Tooltip background (#252525 — near-black)foundations/whiteTooltip textradius/mdCorner radius (8px)space/3Horizontal padding (12px)font/baseTypeface (Inter)size/xsFont size (14px)