Tooltip copy: the hover hint and the onboarding step

Tooltip copy is the short text inside a hint that points at one element in your product. How you write it depends on which job the tooltip is doing, and there are two of them.

The usual advice is to keep it short. That is true, and it is not enough. A hint the user opened and a hint that opened itself get read in different moods, so they need different sentences.

You have two kinds of tooltip, not one

Sort every tooltip in your app into one of these:

• The hover hint. The user asked for it. It explains a control that is already on screen, and it lives in the product forever.
• The onboarding step. The product started it. It moves a new user through one action, once, and then it is done.
• The hotspot. A quiet dot that pulses until someone clicks it. An onboarding step that waits to be invited.

Same small box. Different reasons for being there. Copy that ignores the reason comes out too wordy for the first job and too vague for the second.

A hover hint holds one fact the label cannot

A hover hint explains. It answers "what is this" for someone who is in the middle of doing something else, so it gets one sentence and no more.

The Nielsen Norman Group's tooltip guidelines are strict about what belongs inside one. No obvious or redundant text. And nothing that is "vital to task completion". If the user cannot finish the job without reading your hint, that is not a hint. That is the interface, hiding.

Three questions sort the good ones from the noise:

• Does it repeat the label? "Settings - your settings." Cut it.
• Does it change what someone decides? "Archived boards stay searchable." Keep it.
• Could they act without it? If not, the sentence belongs on the screen, not in a hover.

Write the consequence, not the mechanism. "Sets who can see the file" beats "toggles visibility permissions" every time, and it is shorter.

An onboarding step is one instruction

Now flip the job. This tooltip appeared on its own, in front of a user who has been in your product for ninety seconds. It is not explaining a control. It is asking for an action.

So start with the verb. Name the button using the exact words printed on it, capitals and all. Then say what happens after the click, because that is the part the user cannot see yet.

{
  "type": "tooltip",
  "anchor": "Invite button, top right",
  "trigger": "auto, first session",
  "body": "Click Invite to add a teammate. They get an email link and land in this project.",
  "dismissable": true
}

Three words carry most of the weight there: Invite, because it matches the button; email, because it warns them what leaves the product; this project, because it tells them where the teammate ends up.

Cut the greeting. "Welcome to Projects! Let's get you set up." is two lines of nothing in a box that has room for one line of something.

A hint the user opened can explain. A hint that opened itself has to ask.

How long is too long

Appcues suggests keeping tooltip copy under 150 characters, which is a reasonable ceiling. The real limit is tighter and it is not about characters.

The reader has to hold your sentence in their head while their eyes move back to the element. Two clauses is the practical maximum. One is better. If you need a third, you are writing documentation, and documentation belongs somewhere a person can come back to.

There is an accessibility floor here too. WCAG 1.4.13 says content shown on hover or focus must be dismissable, hoverable, and persistent: a user must be able to close it, move the pointer onto it, and keep it open until they are done. A tip that vanishes when the mouse crosses a gap fails all three. So never let a hover be the only place a piece of copy exists.

When the tooltip means the label is wrong

Here is the test that saves the most work. If the hint has to explain what a control does, the control is misnamed. Rename it and delete the hint.

Tooltips are easy to add, which is exactly why they collect on top of interface problems. A field called "Reference" with a hint explaining that it means invoice number is a field that should be called "Invoice number".

And notice that the onboarding step breaks the Nielsen Norman rule on purpose. It does carry information the user needs to finish the task. That is fine, as long as it is temporary and the product still works once it stops appearing. If a step has to run forever, it stopped being onboarding a while ago and became a missing label.

Read it in the box, not in the doc

Copy that reads well in a spreadsheet can still fail on screen. The line wraps in a place you did not expect. The tip covers the button it is talking about. The sentence is fine, but it sits two inches from the element and the eye has to travel.

So write the draft anywhere you like, then look at it anchored to the real element, in the real layout, at the width your users get. Fix what you see there. This is the same reason empty state copy has to be read on the blank screen rather than in a document, and the reason a checklist item reads differently in a launcher than in a list.

The rule of thumb

Ask which job the tooltip has. If the user opened it, write one fact the label cannot hold. If the product opened it, write one instruction and say what happens next. Then read it out loud, and cut any word you would not say to a person sitting beside you.

In Onbixo, tooltips and hints support hover, click, and always-on hotspot triggers, they stay dismissed once a user closes them, and each one reports how many people saw it and acted on it, so you can tell a hint that helps from a hint that is just in the way. OnbiAI will shorten a line for you when it runs long. Start free.