Tooltip Component

Design a tooltip component that displays contextual information on hover/focus.

R - Requirements

Key Questions:

• Trigger? (hover, focus, both)
• Delay? (immediate, 200ms, 500ms)
• Position? (top, bottom, left, right, auto)
• Max width? (yes, prevent overflow)
• Arrow indicator? (yes/no)

Common Answers:

• Hover + focus triggers
• 200ms delay (prevent accidental triggers)
• Auto-position (flip if no space)
• Max width (300-400px)
• Arrow indicator

A - Architecture

Tooltip Display Flow:

Tooltip Architecture:

Architecture Decisions:

• Portal rendering (render outside DOM hierarchy) - Prevents overflow issues
• Position calculation (viewport-aware, auto-flip) - Always visible, never cut off
• Delay system (show/hide delays) - Prevent accidental triggers, smooth UX
• Accessibility (keyboard focus, screen readers) - aria-describedby, keyboard support

Relevant Content:

• Focus Management - Focus tooltip

D - Data Model

State Management:

• Tooltip visibility (visible, hidden, showing, hiding)
• Position (top, bottom, left, right)
• Delay timer (show/hide delays)
• Target element (element that triggered)

Persistence:

• None (tooltips are ephemeral)

I - Interface

Features:

• Tooltip container (positioned, with arrow)
• Tooltip content (text, rich content)
• Arrow indicator (points to trigger)
• Position system (auto-flip based on viewport)

Accessibility:

• ARIA tooltip pattern
• role="tooltip" on tooltip
• aria-describedby on trigger (link to tooltip)
• Keyboard focus (show on focus, hide on blur)
• Screen reader support (announce on focus)

Relevant Content:

• ARIA Live Regions - Screen reader support
• Accessible Animations - Motion preferences

O - Optimizations

Performance:

• Lazy render (only render when visible)
• Position calculation (debounce resize/scroll)
• Animation performance (fade in/out, GPU accelerated)

UX:

• Smooth animations (fade in/out)
• Auto-positioning (flip if no space)
• Delay system (prevent accidental triggers)

Relevant Content:

• Animation Performance - Smooth fade
• Composite Layers - GPU acceleration

Implementation Checklist

• Portal rendering (document.body)
• Hover trigger (show on hover)
• Focus trigger (show on focus)
• Delay system (200ms show, 100ms hide)
• Position calculation (top, bottom, left, right, auto)
• Auto-flip (if no space in preferred position)
• Arrow indicator (points to trigger)
• Max width (300-400px, prevent overflow)
• ARIA attributes (role="tooltip", aria-describedby)
• Keyboard support (show on focus, hide on blur)
• Smooth animations (fade in/out)

Common Pitfalls

❌ No delay → Tooltips appear on accidental hover
✅ 200ms show delay, 100ms hide delay

❌ Fixed position → Tooltip cut off at viewport edge
✅ Auto-position, flip if no space

❌ No keyboard support → Not accessible
✅ Show on focus, hide on blur, aria-describedby

❌ Janky animations → Poor UX
✅ Use opacity, GPU acceleration, 60fps