Design a tooltip

Requirements: what a tooltip is, and what it is not

A tooltip is a small box of text that appears next to an element, called its trigger, when you point at the trigger with a mouse or move keyboard focus onto it. It goes away when you move away. In a mail app, the trash can icon shows "Delete". In a text editor, the bold button shows "Bold (Ctrl+B)".

It looks like the smallest component in a design system: a div that appears on mouseenter. That's exactly why interviewers ask it. A naive tooltip fails someone: keyboard users never see it, screen readers never hear it, phone users can't open it, and a scrolling panel cuts it off. A strong answer names those groups early and designs for each.

The definition that drives every later decision

The most useful thing to say in the first two minutes is a crisp definition. A tooltip is a short, non-interactive description of its trigger. Each word rules something out:

• Short: one line, maybe two, like "Archive" or "Last edited 3 minutes ago". A paragraph belongs on the page or in a help panel.
• Non-interactive: no links, buttons or inputs inside. A tooltip closes when focus leaves the trigger, so a keyboard user could never reach a link in it. Anything clickable belongs in a popover (a floating panel you can tab into) or a toggletip (a small info button that opens a bubble on click).
• Description of its trigger: it explains the thing it's attached to. It's not a place for promotions, onboarding tips, or errors, which belong next to the field, always visible.
• Supplementary: the page must work without it. Touch screens have no hover, and many users never wait for it. Essential information, like a price condition or a required format, can never live only in a tooltip.

Questions to ask

The middle column is what this guide assumes. The right column is why the answer matters.

Functional requirements

• Show on hover after a short delay, and on keyboard focus.
• Hide when the pointer leaves trigger and tooltip, when focus leaves, and on Escape.
• Let the pointer move onto the tooltip without it closing, so people using screen magnifiers can read it.
• Place it on a preferred side (top by default), flip when there's no room, and slide along the edge to stay on screen.
• Work as the name of an icon-only button or as extra description for a labelled one.
• Work on disabled buttons, which can't take focus and, in some browsers, don't fire mouse events.
• Offer a "show only when truncated" mode for text cut off with an ellipsis.

Non-functional requirements

• Accessible: WCAG 2.2 AA, including 1.4.13, for keyboard, screen reader, magnifier and touch users.
• Fast: opening stays well under a 16 ms frame on a mid-range laptop, and a table with 6,000 triggers must not add 6,000 sets of listeners, timers or positioning engines.
• Small: under about 5 KB gzipped, plus positioning code that many apps already ship for menus.
• Always visible: never clipped by overflow: hidden or stuck under a sticky header or modal.
• Predictable: the same delays everywhere, so the whole product feels consistent.

Out of scope, and why

• Rich popovers with links, buttons, images or forms: a different component with focus management. We only design the handoff.
• Onboarding tours ("New! Try filters"): dialogs with their own dismissal rules.
• Form validation messages: they must stay visible and be announced as errors.
• Native title attribute styling: we won't use title at all, for reasons in the next chapter.

What makes it hard, and why the title attribute isn't enough

Five things make a tooltip harder than it looks. Every later chapter answers one of them.

1. Four kinds of input. Mouse, keyboard, finger and screen reader each need the same text by a different path.
2. Time. Show too fast and bubbles flash as the mouse crosses a toolbar. Show too slow and people give up. Hide too fast and the bubble vanishes while you move onto it.
3. Space. The trigger can sit at a screen edge, in a scrolling panel, or in a cell with overflow: hidden, and the bubble must still find room.
4. Layers. The bubble must appear above cards, sticky headers, menus and modal dialogs, and z-index: 9999 doesn't always win.
5. Scale. A table with 2,000 rows and 3 icon buttons per row has 6,000 triggers. If each owns listeners and timers, the page slows down before anyone hovers.

The naive versions, and how they break

Most teams start with one of three shortcuts, and the interviewer wants to hear why each one fails.

The decisions ahead

Here's the order this guide takes, which also works in the interview: accessibility first, because it decides what the component is, then timing, positioning, rendering, scale and the API.

Accessibility first: the ARIA wiring and WCAG's hover rules

Accessibility comes first because it decides what the component is. A screen reader user hears the text on focus, a keyboard user needs a way to close the bubble, and a magnifier user at 400% has to move the mouse onto the bubble to read it. The ARIA patterns lesson covers roles and states in general; here we apply them.

Two jobs: a name or a description

Every interactive element has an accessible name (what it is, like "Delete") and may have an accessible description (extra detail, like "Moves the conversation to Trash"). A screen reader reads them in that order: "Delete, button, Moves the conversation to Trash". A tooltip does one of these jobs, and the component must know which:

• Label mode: the trigger is an icon-only button with no visible text. The tooltip text is its name. Without it, a screen reader says just "button".
• Description mode: the trigger already has a name (visible text or an aria-label), and the tooltip adds detail, like a keyboard shortcut.

Mixing them up causes real bugs. If an icon button has aria-label="Delete" and the tooltip "Delete" is also its description, the screen reader says "Delete, button, Delete". If the tooltip is the only text and it's wired as a description, the button has no name at all, and checkers like axe flag it.

What the APG tooltip pattern says

The WAI-ARIA Authoring Practices Guide (APG) describes a tooltip pattern: the bubble has role="tooltip", the trigger points to it with aria-describedby, focus stays on the trigger, and Escape closes the tooltip, which never receives focus itself. The APG marks this pattern as work in progress without task force consensus, and it has no official example yet. So treat it as a baseline, not a complete spec, and test with real screen readers (NVDA and JAWS on Windows, VoiceOver on macOS and iOS, TalkBack on Android).

One practical detail matters most: role="tooltip" on its own does very little, because screen readers mostly don't announce the role. What makes the text heard is the relationship: aria-describedby (or aria-labelledby) on the trigger, pointing at an element id. And that relationship has a timing problem.

<!-- Label mode: icon-only button, tooltip text is the name -->
<button type="button" aria-label="Delete">
  <svg aria-hidden="true">...</svg>
</button>

<!-- Description mode: visible name, tooltip adds detail -->
<button type="button" aria-describedby="tip-r3">Bold</button>
<span id="tip-r3" hidden>Ctrl+B</span>

<!-- The visible bubble, a visual copy only -->
<div class="tooltip" aria-hidden="true">Ctrl+B</div>

WCAG 1.4.13: dismissible, hoverable, persistent

WCAG 2.1 added success criterion 1.4.13 Content on Hover or Focus at level AA, and WCAG 2.2 keeps it. It covers content that appears on hover or focus, which is exactly what a tooltip is. It has three conditions, quoted below, and each one turns into code:

The criterion has exceptions, and none of them helps a toolbar tooltip. Dismissible doesn't apply when the content communicates an input error or doesn't obscure or replace other content. And the whole criterion skips content whose presentation the browser controls and the author doesn't modify, like the native title box.

The Escape rule has one sharp edge: inside a modal dialog, Escape also closes the dialog, and hiding a tooltip shouldn't throw away a half-filled form. So while a tooltip is open, its capture-phase keydown handler closes it and calls preventDefault() and stopPropagation(); the next Escape closes the dialog. Test this with your dialog component, because browsers have changed how a native dialog handles Escape over time.

When it opens and closes: delays, warm-up groups and the safe area

The naive tooltip opens on mouseenter and closes on mouseleave. Picture a toolbar of 10 icon buttons, each 40 px wide, and a user sweeping the mouse across it at 1,000 px per second on the way to the message list. The pointer spends 40 ms over each button, so 10 bubbles nobody wanted flash on and off in 0.4 seconds.

Then the user clicks Archive. The click focuses the button, a focus handler opens the tooltip, and the bubble covers the "Conversation archived" toast. And a bubble the user tries to move onto closes in the 8 px gap: three bugs, all about time.

Which events open it

• Pointer hover: listen to pointerenter and pointerleave, ignoring pointerType touch. Touch screens also fire compatibility mouse events after a tap, which is why mouseenter tooltips stick open on phones.
• Keyboard focus: listen to focus and blur, but open only if trigger.matches(":focus-visible"). Browsers match :focus-visible when focus came from the keyboard, and usually not when a mouse click focused a button, so this one check removes the "tooltip after click" bug. It also behaves well when a dialog returns focus: no tooltip after a mouse close, a tooltip after a keyboard close.
• Press: on pointerdown, close the tooltip and mark it dismissed, so the bubble doesn't cover the result.
• Escape: close and mark dismissed, as WCAG 1.4.13 requires.

"Dismissed" means: stay closed until the pointer leaves the trigger or focus moves away. Without it, the bubble reopens when the mouse moves 1 px after Escape.

The timers

The warm-up group

Desktop operating systems settled this long ago: the first tooltip waits, but once one is showing, the neighbouring button's tooltip shows at once, because the user is clearly reading tooltips. We call this a delay group: all tooltips under one provider share one piece of state, "is the group warm, and until when?" Radix's provider and Floating UI's FloatingDelayGroup ship the same idea.

1. Cold group: the pointer enters Archive, waits 500 ms, and "Archive" shows. The group is now warm.
2. The pointer moves to Spam. Archive closes at once and Spam opens with no delay or animation, like one bubble that moved.
3. The pointer leaves the toolbar. The last tooltip closes, and the group stays warm for 300 ms.
4. Back within 300 ms, the next tooltip opens instantly. After that the group is cold and the 500 ms delay returns.

Try the timers in the lab below. Each pointer path is a real situation: a quick sweep across a toolbar on the way elsewhere, reading two tooltips and coming back a moment later, and a slow move onto the bubble. Change one setting at a time and watch which bubbles open, and when.

Getting the pointer onto the bubble

WCAG's hoverable condition says the pointer must be able to reach the bubble. The bubble sits 8 px from the trigger so its arrow has room, and when it has shifted sideways to stay on screen, the pointer travels diagonally over empty page to reach it.

Putting it together: a state machine

Six flags (hovered, focused, open, dismissed, openTimer, closeTimer) give 64 combinations, most of them bugs. A state machine makes the allowed states explicit: each event moves the tooltip from one named state to another, and timers belong to states.

type State = "closed" | "opening" | "open" | "closing" | "dismissed";
type Event =
  | { type: "hover" | "focus"; warm: boolean }
  | { type: "leave" | "blur" | "openTimer" | "closeTimer" }
  | { type: "enterBubble" | "escape" | "press" };

function next(state: State, e: Event): State {
  switch (e.type) {
    case "hover":
      if (state === "dismissed") return state;
      if (state === "closing") return "open";
      return state === "open" || e.warm ? "open" : "opening";
    case "focus":
      return state === "dismissed" ? state : "open";
    case "openTimer":
      return state === "opening" ? "open" : state;
    case "leave":
    case "blur":
      if (state === "opening" || state === "dismissed") return "closed";
      return state === "open" ? "closing" : state;
    case "enterBubble":
      return state === "closing" ? "open" : state;
    case "closeTimer":
      return state === "closing" ? "closed" : state;
    default: // escape or press
      return "dismissed";
  }
}

Real code tracks hover and focus separately: if the pointer leaves while the trigger still has keyboard focus, the tooltip stays open. That's one more check in the leave and blur cases, left out above to keep it short.

Here's one hover from start to paint, including a step from chapter 7: the positioning code downloads on the first open, while the 500 ms timer runs, and may fail.

Where it goes: placement, flip, shift and the arrow

The naive position is one line, top: rect.top - height - 8, centered. It works mid-screen and fails at every edge, in every scrolling panel, and under any transform ancestor. The dropdown select guide covers the same placement rules; a tooltip adds an arrow and a hide step.

The vocabulary

• Placement: a side and an alignment, like top or bottom-start. top is our default, because it doesn't cover the content people read next.
• Offset: the gap between trigger and bubble, 8 px here, so the arrow fits.
• Flip: if the preferred side has no room, try the opposite side.
• Shift: slide the bubble along its side to stay inside the boundary, keeping 8 px of padding.
• Arrow: a small triangle pointing at the trigger's center. After a shift it moves to keep pointing at the trigger, clamped away from the rounded corners.
• Boundary: the area the bubble must fit in, usually the viewport, though clipping ancestors matter too.

A worked example in the top-right corner

The viewport is 1,280 by 720 px. The "Settings" icon button sits in the top-right corner: x from 1,240 to 1,272, y from 8 to 40. The bubble measures 180 by 32 px. Preferred placement: top, offset 8, padding 8.

1. Place: centered above means x = 1,256 - 90 = 1,166 and y = 8 - 8 - 32 = -32. The top 32 px are off screen.
2. Flip: below has 680 px of room, so flip to bottom: y = 40 + 8 = 48.
3. Shift: the right edge is at 1,166 + 180 = 1,346, but the limit is 1,280 - 8 = 1,272. Shift left by 74: x = 1,092.
4. Arrow: the trigger's center is 1,256 - 1,092 = 164 px from the bubble's left edge. The allowed range is 12 to 168 (keeping clear of the corners), so the arrow sits at 164, near the right end, pointing up at the gear.

Order matters. Flip has to run before shift, or shift slides a bubble that's about to move to the other side. The arrow runs after shift because it depends on the final x, and hide runs last. That's why positioning engines are built as a pipeline.

Scroll containers, clipping and transforms

Three page features break the naive math even in the middle of the screen:

• Clipping ancestors: a table cell, card or side panel with overflow: hidden or overflow: auto cuts off any child that sticks out, so a bubble rendered inside it gets sliced.
• Scrolling: when the panel scrolls, the trigger moves but the bubble doesn't unless placement re-runs. And once the trigger scrolls out of view, the bubble shouldn't float on alone over the header.
• Containing blocks: an ancestor with transform, filter, perspective, contain: paint or will-change: transform becomes the reference box for position: fixed children, so a "fixed" bubble inside an animated card is positioned and clipped by the card.

Clipping and containing blocks are fixed by rendering the bubble outside the trigger's subtree (chapter 6). Scrolling is fixed by re-running placement while open, on scroll of every scrolling ancestor, resize of the window, and a ResizeObserver on trigger and bubble. Attach these on open and remove them on close, so closed triggers cost nothing, and add a hide step for when the trigger leaves its clipping ancestor.

The lab below puts a trigger inside a side panel that scrolls and clips, like a comments panel. Render the bubble inline and move the trigger toward the panel's edge to see clipping, then switch to the top layer. Scroll until the trigger leaves the panel, with and without the hide step.

Choosing the engine

Which layer it renders in: portals, the top layer and popover="hint"

Positioning decides the coordinates; rendering decides which box they're inside and what paints on top. Get it wrong and a perfectly placed bubble is sliced by a table cell or hidden under a sticky header.

Why z-index: 9999 loses

z-index only compares elements inside the same stacking context, and any ancestor with position plus a z-index, an opacity below 1, a transform, or isolation: isolate starts a new one. So a bubble with z-index: 9999 inside a card with transform: translateZ(0) still paints below a sibling card's dropdown, because the whole card stacks as one unit. Raising numbers further starts a z-index war that nobody wins; the modal dialog guide tells the same story.

One layer is out of reach for z-index entirely: the top layer. A dialog opened with showModal(), a fullscreen element, and a shown popover render there, above the whole document, in the order they were added.

Which popover type: auto, manual or hint

The popover attribute has three values, and the choice matters for tooltips:

let popoverType: "hint" | "manual" | undefined;

function getPopoverType() {
  if (!popoverType) {
    const probe = document.createElement("div");
    probe.popover = "hint";
    popoverType = probe.popover === "hint" ? "hint" : "manual";
  }
  return popoverType;
}

export function showBubble(bubble: HTMLElement, text: string) {
  bubble.textContent = text;
  bubble.popover = getPopoverType();
  if (!bubble.matches(":popover-open")) bubble.showPopover();
}

What's coming: interest invokers

Interest invokers add an interestfor attribute: button interestfor="tip-3" shows that popover when the user shows "interest" by hovering, focusing, or long-pressing on touch, with delays set in CSS. The browser then owns the timing, the hover bridge and much of the accessibility wiring. Chromium shipped it in version 142 (late 2025); Firefox and Safari haven't yet, and details may change. Keep our API shaped so a later version can switch to it without teams changing their code.

Architecture: one shared tooltip, not 6,000

So far we've designed one tooltip. Now put it in the data table from the requirements: 2,000 rows with 3 icon buttons each (Edit, Duplicate, Delete), so 6,000 triggers. If each Tooltip is self-contained, each owns a state hook, 4 to 6 event listeners, two timers, a hidden popover element, and maybe a positioning subscription.

Rough cost: 6,000 components to render and hydrate, about 30,000 listeners, and 6,000 extra elements, all for a feature that shows one bubble at a time. On a mid-range phone that's easily tens of milliseconds of extra hydration work, which can delay the first interaction and hurt Interaction to Next Paint. The runtime performance lesson covers measuring it; here we design it away.

The parts and their jobs

The lazy positioner needs a failure plan. If its chunk fails to download (a flaky connection, a deploy that removed old files), the tooltip still opens: the bubble layer places it below the trigger, clamps it to the viewport, and leaves out the arrow. It retries the import on the next open, because a slightly worse position beats no text.

How data flows

A tooltip has no API of its own, but it still has data. The text usually comes from the translation bundle ("toolbar.delete": "Delete") and ends up in two places: the trigger's accessible markup in the server HTML, and the registry. At runtime, events flow the other way: input reaches the controller, which reads the registry, the positioner reads the layout, and the bubble paints.

The data model

type Placement = "top" | "bottom" | "left" | "right"
  | `${"top" | "bottom" | "left" | "right"}-${"start" | "end"}`;

type TooltipEntry = {
  id: string;               // from useId(), stable across server and client
  content: string;          // plain text only
  mode: "label" | "description";
  placement: Placement;     // preferred side; flip may change it
  openDelay?: number;       // overrides the group's 500 ms
  onlyWhenTruncated?: boolean;
};

type ControllerState = {
  status: "closed" | "opening" | "open" | "closing" | "dismissed";
  activeId: string | null;  // the one tooltip that may be open
  trigger: HTMLElement | null;
  openedBy: "pointer" | "focus" | null;
  warmUntil: number;        // performance.now() deadline for the group
};

type Registry = Map<string, TooltipEntry>;

The component API: small, hard to misuse

Product teams will use this component thousands of times, so the API should make the right thing short and the wrong thing hard. The component API design lesson covers the general rules; here are the tooltip-specific ones.

type TooltipProps = {
  content: string;                 // string, not ReactNode: no links inside
  mode?: "label" | "description";  // default "description"
  placement?: Placement;           // default "top"
  openDelay?: number;              // default from the provider, 500 ms
  onlyWhenTruncated?: boolean;     // for text cut off with an ellipsis
  disabled?: boolean;              // turn the tooltip off, not the trigger
  children: React.ReactElement;    // exactly one trigger
};

<TooltipProvider openDelay={500} closeDelay={100} warmWindow={300}>
  <Tooltip content="Delete" mode="label">
    <IconButton icon={TrashIcon} onClick={remove} />
  </Tooltip>
  <Tooltip content="Ctrl+B">
    <Button onClick={toggleBold}>Bold</Button>
  </Tooltip>
  <Tooltip content={file.name} onlyWhenTruncated>
    <span className="truncate">{file.name}</span>
  </Tooltip>
</TooltipProvider>

• content is a string. The type system enforces the definition from chapter 1: a team that needs a link gets a type error and finds the toggletip.
• mode is explicit. In development builds, if mode is "description" and the mounted trigger has no accessible name, the component logs a warning pointing at mode="label".
• No open prop by default. A controlled open invites onboarding tours built on tooltips. Tests use real events with fake timers instead (chapter 9).

Disabled triggers

A common request: "Show why the Publish button is disabled." A native disabled button breaks this twice. It can't receive focus, so keyboard users never see the tooltip, and browsers have historically not fired mouse events on disabled form controls, with differences between engines, so hover is unreliable too.

Tooltips for truncated text

File names and email subjects are often cut off with text-overflow: ellipsis. A tooltip with the full text helps, but only when the text is actually cut off; repeating "Budget.xlsx" over "Budget.xlsx" is noise.

• Check el.scrollWidth > el.clientWidth at open time, not at render time. Widths change when the window resizes or a panel opens, and checking on open means one measurement per hover, not 2,000 on page load.
• Screen readers already read the full text, since truncation is only visual, so this mode adds no aria-describedby and no hidden span.
• Keyboard users need to focus the text to see it. In a data table, cells are already focusable through the grid's roving focus, so the tooltip opens on cell focus.

Touch, motion, server rendering and tests

Touch screens have no hover

On a phone no pointer rests over a button: a finger arrives, taps, and leaves. So what does a touch user get instead?

Animation and reduced motion

• Fade in over about 100 ms with a 4 px slide, using only opacity and transform, which skip layout.
• No animation when switching inside a warm group, so it reads as one bubble following the pointer.
• Reduced motion: under @media (prefers-reduced-motion: reduce), drop the slide and keep a short fade or nothing (the visual accessibility lesson explains why).
• Entry and exit with popovers: animating to and from display: none needs @starting-style and transition-behavior: allow-discrete; browsers without them just skip the animation.
• Never let animation delay the content. The 500 ms open delay is already the wait; a 300 ms fade on top feels slow.

Server rendering and hydration

• Ids from useId(): React generates the same id on the server and the client, so aria-describedby matches the hidden span after hydration. Counters or Math.random() produce mismatches.
• Accessible text in the server HTML: aria-label and hidden spans render on the server, so screen readers get names and descriptions before JavaScript loads.
• No bubble on the server: the provider creates the bubble and attaches listeners in an effect, after hydration. Until then hovering does nothing, which is acceptable for supplementary content.
• Measure only on the client, on open, so render has nothing to mismatch.

Performance

Opening a tooltip costs a registry lookup, two getBoundingClientRect() calls and some arithmetic. While open, batch scroll updates to one per animation frame with requestAnimationFrame, read all rectangles before writing any style to avoid forced layouts, and write the position as a transform on a position: fixed bubble.

Testing with fake timers

Real timers make tests slow and flaky. Unit-test the state machine as a pure function (every event in every state), then test the component with fake timers, so the test controls the clock.

beforeEach(() => vi.useFakeTimers());
afterEach(() => vi.useRealTimers());

// The bubble layer sets data-open while the bubble is shown.
const bubble = () => screen.queryByText("Delete", { selector: ".tooltip[data-open]" });

test("hover waits 500 ms", async () => {
  const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime });
  render(<App />);
  await user.hover(screen.getByRole("button", { name: "Delete" }));
  act(() => vi.advanceTimersByTime(499));
  expect(bubble()).toBeNull();
  act(() => vi.advanceTimersByTime(1));
  expect(bubble()).toBeInTheDocument();
});

test("keyboard focus opens at once, Escape keeps focus", async () => {
  const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime });
  render(<App />);
  await user.tab(); // first stop is the Delete button
  expect(bubble()).toBeInTheDocument();
  await user.keyboard("{Escape}");
  expect(bubble()).toBeNull();
  expect(screen.getByRole("button", { name: "Delete" })).toHaveFocus();
});

• Wiring: assert computed names and descriptions, like jest-dom's expect(boldButton).toHaveAccessibleDescription("Ctrl+B").
• What jsdom can't do: it has no layout, so every rectangle is zero, and newer APIs like popovers may be missing. Test flip, shift and clipping in a real browser (Playwright, or Vitest's browser mode) with triggers at each edge and inside a scrolling panel.
• Accessibility checks: run axe on pages with icon buttons to catch missing names, and do a manual screen reader pass for both modes.
• Visual tests: screenshot each placement and the flipped and shifted cases to catch arrow regressions.

Running it in the interview

A tooltip question is usually 30 minutes, sometimes a warm-up before a bigger component. The trap is spending 20 minutes on positioning math; interviewers want breadth first (every kind of user), then depth on two or three decisions.

Draw three things, in this order: the wireframe (it anchors the vocabulary), the state machine (it shows you think in states, not handlers), and the architecture with one shared controller (it answers the scale question before it's asked). Say the rest out loud.

Follow-up questions to expect