Tooltips: small hints, not hidden instructions

A tooltip is supplementary information. If someone must read it to complete a task, the text probably belongs directly on the page. Tooltips disappear, do not always exist on touch devices, and can interrupt reading when overused.

This updated guide revisits the old Simpletip jQuery topic without distributing an unverified plugin download.

Decide whether a tooltip is appropriate

Use a hint for a short explanation of an unfamiliar icon or term. Put form instructions and validation messages beside their fields. Do not place links, buttons, or a long paragraph inside a tooltip; those need a different interaction, such as a disclosure or popover.

For a form field, visible help can be associated with aria-describedby:

<label for="project-name">Project name</label>
<input id="project-name" aria-describedby="project-help">
<p id="project-help">Use the name shown in the source repository.</p>

This pattern needs no hover behavior and remains available on touch screens.

If you build a tooltip

Follow the WAI tooltip pattern. Make it available on keyboard focus as well as pointer hover, let Escape dismiss it, and connect the trigger to the description. Do not move focus into the tooltip.

Position it so it does not cover the trigger or important neighboring content. Keep it visible long enough to read and allow the pointer to move over it without instantly dismissing it. Test at the viewport edge and with enlarged text.

Maintain old implementations cautiously

Inventory the jQuery and tooltip-plugin versions, check whether the widget inserts HTML from untrusted strings, and remove old listeners during replacement. Preserve the meaning of each hint while simplifying the machinery that displays it.