Chapter 38: Tooltip

Core Idea

A short informational popup shown on hover or keyboard focus — unlike HoverCard, it's fully keyboard-accessible and meant for brief hint text, not rich content.

Key Concepts

• Anatomy: Provider (app-level, controls global delay behavior) → Root → Trigger, Portal → Content (+ Arrow).
• Opens on focus or hover: both interaction modes trigger it, unlike HoverCard which is hover-only and screen-reader-excluded.
• [data-state]: "closed" | "delayed-open" | "instant-open" — distinguishes a delayed hover-open from an instant one (e.g. re-triggering shortly after a previous tooltip closed).
• Provider's skipDelayDuration: shortens the open delay when moving quickly between multiple tooltip triggers, same intent as NavigationMenu's equivalent prop.
• Closes on Escape or trigger activation: e.g. clicking the trigger button dismisses its own tooltip.

Key Takeaways

1. Use Tooltip (not HoverCard) for short hint text on interactive controls — it's the one overlay in this pair that keyboard/screen-reader users can actually reach.
2. Wrap your app once in a single Provider to get consistent delay timing across every tooltip, rather than configuring delayDuration per-instance.
3. Keep Content to brief text — for anything richer (images, multiple paragraphs, interactive elements), use Popover or HoverCard instead.

Connects To

• Hover Card: the sighted-only, richer-content sibling of this primitive.
• Popover: the fully-interactive alternative when tooltip content needs to contain more than static text.