Tooltips

Contextual help text that appears on hover or focus, providing additional information without cluttering the interface. Designed with trauma-informed principles to be helpful, not overwhelming.

8 positioning options

ARIA tooltip semantics

Keyboard & touch support

Standard Tooltips

Simple text tooltips that appear on hover or focus, providing helpful context without overwhelming the user.

Top

Bottom

Left

Right

Aligned Tooltips

Tooltips can be aligned to the start or end of the trigger element for better positioning control.

Top Start

Top End

Bottom Start

Bottom End

Rich Tooltips

Tooltips with formatted content, icons, and multiple lines for more complex information.

With Icon

Multi-line Content

Interactive Tooltips

Tooltips with clickable content or actions. Use sparingly and only when necessary.

Accessibility & Usage Guidelines

Key Accessibility Features

ARIA role="tooltip" on tooltip element for screen reader announcements
aria-describedby attribute linking trigger to tooltip content (ID reference)
Keyboard navigation: Tab to focus trigger, Esc to dismiss tooltip
Focus indicators: Visible focus states on all interactive elements
Color contrast: WCAG 2.2 Level AA compliant (dark tooltip bg ensures 4.5:1 minimum)
Reduced motion support: Transitions respect prefers-reduced-motion
Touch support: Tooltips can be triggered on mobile devices (click to show)
Hover delay: Alpine.js transitions provide smooth show/hide (200ms enter, 150ms leave)

ARIA Tooltip Pattern

<!-- Trigger element -->
<button 
    type="button"
    aria-describedby="tooltip-id"
    @mouseenter="show = true"
    @mouseleave="show = false"
    @focus="show = true"
    @blur="show = false"
>
    Trigger element
</button>

<!-- Tooltip element -->
<div 
    x-show="show"
    id="tooltip-id"
    role="tooltip"
    class="..."
>
    Tooltip content here
</div>

Usage Guidelines

When to use:
- Providing supplemental information that clarifies an element's purpose
- Explaining abbreviations or technical terms
- Showing keyboard shortcuts or additional context
- Displaying helpful tips for form fields
When NOT to use:
- For critical information that users must see (use inline text instead)
- For error messages (use alerts or inline validation)
- For complex interactive content (consider popovers or modals)
- On mobile-first designs where hover isn't reliable (use click triggers)
Best practices:
- Keep tooltip text concise (1-2 sentences maximum for standard tooltips)
- Use whitespace-nowrap for single-line tooltips to prevent wrapping
- Position tooltips to avoid covering important content
- Ensure tooltips are dismissible (Esc key, click outside)
- Use consistent positioning throughout your interface
- Test on touch devices to ensure tooltips are accessible
- Avoid nested tooltips (tooltip within tooltip)

Trauma-Informed Design Principles

Non-intrusive: Tooltips appear gently without covering critical content
User control: Easy to dismiss with Esc key or by moving focus away
Predictable timing: Consistent show/hide delays reduce cognitive load
Clear communication: Tooltip content is supportive and helpful, never judgmental
Respectful design: Reduced motion support ensures comfortable experience for all users

Alpine.js Implementation

<div x-data="{ show: false }" @keydown.escape.window="show = false">
    <button 
        @mouseenter="show = true"
        @mouseleave="show = false"
        @focus="show = true"
        @blur="show = false"
    >
        Trigger
    </button>
    
    <div 
        x-show="show"
        x-transition:enter="transition ease-out duration-200"
        x-transition:enter-start="opacity-0 transform scale-95"
        x-transition:enter-end="opacity-100 transform scale-100"
        x-transition:leave="transition ease-in duration-150"
        x-transition:leave-start="opacity-100 transform scale-100"
        x-transition:leave-end="opacity-0 transform scale-95"
        role="tooltip"
    >
        Tooltip content
    </div>
</div>