Accessible Tooltips

Comprehensive guide to creating accessible tooltips with proper ARIA patterns and keyboard support.

1.3.11.4.132.1.1

Why It Matters

1Magnification Users

Users who zoom in often need to pan the screen. If the tooltip disappears when the mouse pointer moves (e.g., to scroll), they can't read the content.

2Cognitive Load

Tooltips that vanish instantly require precise mouse movements. This is frustrating and sometimes impossible for users with tremors or motor impairments.

WCAG Requirements

1.4.13Content on Hover or Focus

Tooltip must be dismissible
Tooltip must be hoverable
Tooltip must be persistent

2.1.1Keyboard

Tooltip must be keyboard accessible
Focus should trigger tooltip

1.3.1Info and Relationships

Tooltip must be associated with trigger
Use aria-describedby to link tooltip

ARIA Tooltip

Use role="tooltip" on the tooltip element. Associate it with the trigger using aria-describedby on the trigger pointing to the tooltip's id. The tooltip should appear on both hover and focus. Use aria-live="polite" if the tooltip appears dynamically. Ensure the tooltip is keyboard accessible and doesn't block other content.

Interactive Example

Test the accessible aria tooltip implementation

Testing Guide

Keyboard Navigation

•Tab to trigger element - tooltip appears on focus
•Press Escape to dismiss tooltip (WCAG 1.4.13)
•Tab away to close tooltip

Screen Reader

•Tooltip content is announced via aria-describedby
•Content is available when needed
•Tooltip can be dismissed without losing focus

Code Implementation

Accessible aria tooltip implementation

Common Mistakes

1. Missing Hover Bridge

If the tooltip is slightly separated from the trigger, moving the mouse to the tooltip will close it.

Don't Do This

Tooltip closes instantly, making it impossible to hover over the content.

<button onMouseLeave={() => setShow(false)}>
  Trigger
</button>

Do This Instead

A small timeout allows users to traverse the gap between trigger and tooltip.

<button onMouseLeave={safeClose}>
  Trigger
</button>
// safeClose waits 300ms before closing

2. Using Title Attribute

The native `title` attribute is visually inconsistent and not keyboard accessible in many browsers.

Don't Do This

Title attribute often won't appear on focus and can't be styled.

<button title="More info">
  Help
</button>

Do This Instead

Custom tooltips give you full control over accessibility and styling.

<button aria-describedby="tip">
  Help
</button>
<div id="tip" role="tooltip">More info</div>

Best Practices

Accessibility Considerations

Key Points:

•Use aria-describedby to associate tooltip with trigger
•Tooltip should appear on both hover and focus
•Ensure tooltip doesn't block other interactive elements
•Keep tooltip text concise and helpful
•Use role='tooltip' for the tooltip element
•Ensure tooltip is keyboard accessible

Warnings:

⚠Don't use title attribute as primary tooltip method (not keyboard accessible)
⚠Avoid tooltips for critical information
⚠Don't make tooltips too large or complex

Additional Resources

Related WCAG Criteria

External Resources

ARIA Tooltip Pattern

Why It Matters

1Magnification Users

Users who zoom in often need to pan the screen. If the tooltip disappears when the mouse pointer moves (e.g., to scroll), they can't read the content.

2Cognitive Load

Tooltips that vanish instantly require precise mouse movements. This is frustrating and sometimes impossible for users with tremors or motor impairments.

ARIA Tooltip

Interactive Example

Test the accessible aria tooltip implementation

Testing Guide

Keyboard Navigation

•Tab to trigger element - tooltip appears on focus
•Press Escape to dismiss tooltip (WCAG 1.4.13)
•Tab away to close tooltip

Screen Reader

•Tooltip content is announced via aria-describedby
•Content is available when needed
•Tooltip can be dismissed without losing focus

Code Implementation

Accessible aria tooltip implementation

Common Mistakes

1. Missing Hover Bridge

If the tooltip is slightly separated from the trigger, moving the mouse to the tooltip will close it.

Don't Do This

Tooltip closes instantly, making it impossible to hover over the content.

<button onMouseLeave={() => setShow(false)}>
  Trigger
</button>

Do This Instead

A small timeout allows users to traverse the gap between trigger and tooltip.

<button onMouseLeave={safeClose}>
  Trigger
</button>
// safeClose waits 300ms before closing

2. Using Title Attribute

The native `title` attribute is visually inconsistent and not keyboard accessible in many browsers.

Don't Do This

Title attribute often won't appear on focus and can't be styled.

<button title="More info">
  Help
</button>

Do This Instead

Custom tooltips give you full control over accessibility and styling.

<button aria-describedby="tip">
  Help
</button>
<div id="tip" role="tooltip">More info</div>

Best Practices

Accessibility Considerations

Key Points:

•Use aria-describedby to associate tooltip with trigger
•Tooltip should appear on both hover and focus
•Ensure tooltip doesn't block other interactive elements
•Keep tooltip text concise and helpful
•Use role='tooltip' for the tooltip element
•Ensure tooltip is keyboard accessible

Warnings:

⚠Don't use title attribute as primary tooltip method (not keyboard accessible)
⚠Avoid tooltips for critical information
⚠Don't make tooltips too large or complex