Tooltip

Problem Context

• A toolbar, icon button, compact status marker, data chip, or abbreviated field label needs a little extra explanation.
• The user should not have to click, open a menu, enter a panel, or leave the current task to read the description.
• The content is supplemental and short enough to read while focus remains on the trigger.
• The implementation can support focus and hover triggering, Escape dismissal, pointer movement, zoom, clipping, and assistive technology description relationships.

Selection Rules

• Choose tooltip when the target already has a usable name and needs only a short supplemental description on focus or hover.
• Use popover when the layer needs interactive controls, links, choices, a heading, or user-managed open and close behavior.
• Use inline message when the information is important, required, validation-related, or must stay visible while the user acts.
• Use visible text labels when the action would otherwise be ambiguous before activation.
• Use disclosure details when users need to intentionally open longer optional explanation inside the page flow.
• Use disabled-button explanation patterns when a blocked action needs a reachable reason and next step.
• Do not use a tooltip for instructions users must remember after focus leaves the trigger.
• Do not use tooltip role for a more-info icon that opens a separate explanation; that job belongs to disclosure, popover, or inline help.

Required States

• Resting trigger state with a visible or accessible name that works without the tooltip.
• Keyboard focus state where the tooltip appears and focus remains on the trigger.
• Pointer hover state where the tooltip appears after a brief delay and remains while pointer is over the trigger or tooltip area.
• Escape dismissed state where the tooltip hides without moving focus from the trigger.
• Blur or pointer-out dismissed state where the tooltip hides cleanly.
• Placement collision state where the tooltip shifts or flips without covering the trigger or important content.
• Long-label or zoom state where tooltip text wraps without clipping or overlapping nearby controls.
• Disabled or unavailable target state where the explanation remains reachable by keyboard and touch.

Interaction Contract

• The owning element keeps focus while the tooltip is visible.
• The tooltip is associated with the owning element as a description, not as a replacement label.
• The tooltip appears for keyboard focus and pointer hover, not hover alone.
• Escape hides the tooltip and leaves focus on the owning element.
• Blur, pointer out, or moving to another described control hides the old tooltip.
• The tooltip itself contains no focusable elements and does not require Tab navigation.
• The tooltip does not block pointer access to the trigger or nearby task controls.
• Opening and closing the tooltip does not apply a value, submit a command, change route, or alter task state.

Implementation Checklist

• Give the trigger its own accessible name before adding tooltip text.
• Connect descriptive tooltip text to the trigger with aria-describedby when using ARIA tooltip semantics.
• Show the tooltip on focus and hover, and hide it on blur, pointer out, Escape, and trigger removal.
• Keep tooltip copy short, text-only, and supplemental.
• Do not place links, inputs, buttons, menus, or other focusable controls inside the tooltip.
• Position the tooltip close to the trigger while avoiding clipping, viewport edges, and important content.
• Provide a keyboard and touch-reachable alternative when the target is disabled or cannot receive focus.
• Test keyboard, pointer, touch, screen readers, high zoom, forced colors, reduced motion, and dense toolbars.

Common Generated-UI Mistakes

• Using hover-only tooltip text as the only label for an icon button.
• Putting required instructions, validation fixes, or legal terms in a tooltip that disappears during the task.
• Adding buttons, links, or form fields inside a tooltip.
• Triggering a tooltip only with a mouse pointer and not with keyboard focus.
• Letting Escape close the tooltip and also move focus away from the trigger.
• Attaching a tooltip to a disabled native control that keyboard users cannot focus.
• Using long paragraphs that clip, cover nearby controls, or require scrolling inside the tooltip.

Critique Questions

• Does the target already have a usable name without the tooltip?
• Is the tooltip content supplemental and short enough to read while focus stays on the trigger?
• Would a popover, inline message, details disclosure, or visible label better match the information?
• Can keyboard, pointer, and touch users reveal the same information?
• What happens on Escape, blur, pointer out, zoom, collision, and disabled state?
• Is any required instruction hidden in this temporary description?