# Tooltip

> Use when implementing provide additional context on hover or focus.

- Skill: `thedaviddias/tooltip` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add thedaviddias/tooltip`
- Raw SKILL.md: https://api.skillmd.com/api/skills/thedaviddias/tooltip/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: thedaviddias (https://skillmd.com/u/thedaviddias)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/thedaviddias/tooltip

---


# Tooltip

Provide additional context on hover or focus

## What it solves

A **tooltip** is a small popup that provides additional contextual information when a user hovers over, focuses on, or interacts with an element. It helps clarify elements with **icons, buttons, or text snippets** that may not be self-explanatory.
There are **two types of tooltips**:
- **Simple Tooltips** – Short text descriptions that appear on hover or focus, providing a brief explanation.
- **Rich Tooltips** – Enhanced tooltips that may contain **formatted text, icons, images, or interactive elements**.
Tooltips should be used to enhance understanding without overwhelming the user interface.

## When to use

Use a tooltip when you need to provide **additional context or explanations** without taking up extra space in the UI.
**Common use cases include:**
**Simple Tooltips**
- **Clarifying icons or abbreviations** (e.g., a settings cog, currency symbols).
- **Providing additional information** about form fields or table headers.
- **Showing helper text** for complex actions (e.g., "This action is permanent").
- **Explaining disabled elements** when a user cannot interact with them.
- **Providing keyboard shortcuts** when hovering over action buttons.
**Rich Tooltips**
- **Providing in-depth explanations** beyond a brief description.

## When to avoid

- **For critical information** users must read, such as error messages.
- **For content that should remain visible**, like persistent hints or descriptions.
- **When users need to interact** with the tooltip itself.
- **If the tooltip is the only means** of conveying information (accessibility issue).
- **For mobile-first interactions** where hover-based behavior isn't intuitive.

## Implementation workflow

1. Confirm the pattern matches the problem and constraints before copying the example.
2. Start from the anatomy and examples in `references/pattern.md`, then choose the smallest viable variation.
3. Apply accessibility, performance, and interaction guardrails before layering visual polish.
4. Use the testing guidance to verify behavior across keyboard, screen reader, responsive, and failure scenarios.

## Accessibility guardrails

### Keyboard Interaction Pattern
The following table outlines the standard keyboard interactions for tooltip components. These interactions ensure that users can access and dismiss tooltips effectively using only a keyboard.
| Key         | Action                                                                                           |
| ----------- | ------------------------------------------------------------------------------------------------ |
| Tab         | Moves focus to the element that triggers the tooltip. The tooltip should appear on focus.        |
| Shift + Tab | Moves focus to the previous interactive element. The tooltip should close when focus moves away. |
| Escape      | Dismisses the tooltip manually (if dismissible).                                                 |
| Enter/Space | Activates the tooltip (for tooltips that require explicit activation).                           |
> **Note**: Tooltips should appear when an element **receives focus** (for keyboard users) and **disappear when focus moves away**. If a tooltip is **interactive** (contains links or buttons), it must be dismissible via the `Escape` key.

## Performance guardrails

### Performance Metrics
**Target Metrics:**
- **Show Delay**: 300-500ms to prevent accidental triggers
- **Animation Duration**: < 200ms for smooth perception
- **DOM Impact**: Single tooltip instance reused across triggers
- **Memory Usage**: < 1KB per tooltip instance
- **Event Listeners**: Use event delegation for multiple tooltips
**Optimization Strategies:**
- **Single Instance Pattern**: Reuse one tooltip element for all triggers
- **Event Delegation**: Attach listeners to parent container, not individual elements

## Common mistakes

### Tooltips That Disappear Too Fast
**The Problem:**
Users might not have enough time to read the tooltip before it disappears.

**How to Fix It?**
Ensure tooltips remain visible **for at least 3–5 seconds** or stay open on hover.

### Not Accessible via Keyboard
**The Problem:**
Many tooltips rely only on hover, making them inaccessible to keyboard users.

**How to Fix It?**
Ensure tooltips can be triggered **via focus (`Tab` key)**. For screen readers, pair `aria-describedby` on the trigger element with `role="tooltip"` on the tooltip container.

### Blocking Important Content
**The Problem:**
Tooltips that cover input fields or buttons create confusion and may block clicks or taps.

**How to Fix It?**
Position tooltips **away from interactive elements** and use arrow indicators to point from the trigger to the tooltip.

## Related patterns

- https://uxpatterns.dev/patterns/content-management/modal
- https://uxpatterns.dev/patterns/content-management/popover
- https://uxpatterns.dev/patterns/forms/selection-input

---

For full implementation detail, examples, and testing notes, see `references/pattern.md`.

Pattern page: https://uxpatterns.dev/patterns/content-management/tooltip