Web UI Playbook

Tooltips

Edit this file

Tooltips give quick, helpful info when users hover or focus on elements—improving clarity without cluttering the interface.

Primary Purpose of Tooltips
Understanding when and why to use tooltips in your interface design.

Core Purpose

  • • Clarification: Explain unfamiliar icons or abbreviations
  • • Additional Context: Provide helpful details without cluttering UI
  • • Status Information: Show current state or values
  • • Guidance: Offer hints and tips for complex interactions

Tooltip vs Other Components

Use Tooltip When:
  • • Brief, supplementary information
  • • Clarifying icons or controls
  • • Non-critical contextual details
Use Popover When:
  • • Rich content with formatting
  • • Interactive elements inside
  • • Longer explanations

Tooltip Usage Scenarios

Get help and support
Icon Clarification: Explaining what an icon does when its meaning isn't immediately clear
Upgrade to premium to access settings
Disabled State Context: Explaining why an element is disabled and how to enable it
API Key: abc123...
Full key: abc123def456ghi789
Truncated Information: Showing full content when space is limited
When NOT to Use Tooltips
Important guidelines for avoiding tooltip overuse and misuse.

❌ Avoid Tooltips For:

  • • Essential information that users need to complete tasks
  • • Error messages or critical feedback
  • • Complex content that requires interaction or formatting
  • • Touch-only interfaces where hover doesn't exist
  • • Repetitive information that's already visible on screen
  • • Navigation or primary actions (use clear labels instead)

✅ Good Tooltip Practices:

  • • Keep content concise and scannable
  • • Use for progressive disclosure of secondary information
  • • Provide value beyond what's already visible
  • • Make the interface work without tooltips
  • • Ensure content is accessible via keyboard
  • • Use consistent timing and positioning
References & Further Reading
Comprehensive resources for tooltip component implementation and accessibility.
WAI-ARIA Authoring Practices - Tooltip Pattern
Adobe Spectrum - Tooltip Component
Atlassian Design System - Tooltip Examples
Blueprint.js - Tooltip Component
Uber Base Design - Tooltip Component
Vercel Geist Design System - Tooltip
Radix UI - Tooltip Primitive