Tooltip

Overview

Tooltips are short, transient. They appear on hover or focus, they carry text only, they never replace a click target. Reach for one when an icon needs a name, a date wants a longer format, or a truncated label deserves to be readable on demand. If the content is essential to the task, write it into the page instead — a tooltip is supplementary.

Variants

Two color treatments. Default is light (white surface, hairline border) — best on dark or busy contexts. Inverse is charcoal — the everyday choice on the light surfaces most of the product lives on.

Placements

Top, right, bottom, left. The arrow tracks to the trigger; the component auto-flips to the opposite side if the preferred placement would overflow the viewport.

Compositions

Three composition shapes. Single-line is the default; a label + description pair handles the “Settled · 16 Jan, 19:27” look from the Figma matrix; arrowless pills slot into dense rows where neighbouring cells shouldn't see a triangle.

Anatomy

Four named parts. Only the surface is required — every other piece is opt-in.

Behavior

• 01Hover delay, focus instant. delayMsdefaults to 400 ms — long enough to skip accidental hovers. Focus opens the tooltip immediately so keyboard users don't wait.
• 02Auto-flip at the viewport edge. The component measures itself, the trigger, and the viewport. If the preferred placement overflows, it tries the opposite. No third-party positioning library — just getBoundingClientRect and a small computation.
• 03Closes on Escape, scroll, resize. Escape always closes. Scroll and resize close so the tooltip never hangs in a stale position. The user re-hovers to bring it back.
• 04Pointer events pass through. The tooltip sets pointer-events: none— the cursor moves over it without triggering a hover-leave on the trigger.
• 05Portal rendering. The tooltip mounts into document.body so it can't be clipped by an ancestor's overflow: hidden. SSR-safe — only mounts after the client hydrates.

Accessibility

• role="tooltip". The tooltip surface carries the role; the trigger gets aria-describedby pointing at it while open. Screen readers announce the tooltip text after the trigger's name.
• Keyboard parity. The trigger fires onFocus, not just onMouseEnter — Tab into a tooltipped control and the content shows immediately.
• Not for required information.A tooltip is supplementary. If the user can't complete the task without reading it, write it into the page — keyboard users on Windows High Contrast, screen-reader users with hovers off, and any user on a touch device may never see it.
• Don't place interactive content inside. The tooltip is pointer-events: none — buttons or links inside can't be clicked. For interactive content, reach for Popover.

Code

import { Tooltip } from "@flatpay-dk/ui";

// Default — single-line content, top placement
<Tooltip content="Settled at end of day">
  <Button>Pay out</Button>
</Tooltip>

// Inverse (charcoal) — the everyday default
<Tooltip content="Cancel the run" variant="inverse">
  <IconButton aria-label="Cancel"><CrossIcon /></IconButton>
</Tooltip>

// Title + description (Figma "Label / 16 Jan, 19:27" pattern)
<Tooltip label="Settled" description="16 Jan, 19:27 · final">
  <span className="border-b border-dashed">settled</span>
</Tooltip>

// Placement override
<Tooltip content="More info" placement="right">
  <InfoIcon />
</Tooltip>

// No arrow — for dense rows
<Tooltip content="Run prototype locally" showArrow={false}>
  <Button size="sm">Run</Button>
</Tooltip>

// Custom delay
<Tooltip content="Quick reveal" delayMs={120}>
  …
</Tooltip>

// Disabled — never opens
<Tooltip content="…" disabled={!showHints}>
  <Button>…</Button>
</Tooltip>

Best practices

Props

Related