esc
  • WorkflowsPages
  • Case studiesPages
  • Machine Learning FoundationsLearn
  • AI EngineeringLearn
  • AI Guardrails & Red TeamingLearn
  • UI/UXLearn
  • Design SystemsLearn
  • Production System DesignLearn
  • Book a callContact
  • Download ResumeContact
Let’s talk

I’ll build the agent for it.

Tooltip: Short Hover and Focus Hints With Clear Rules for Every Icon

A tooltip is a small, temporary label. Here is how a design system sets its text, placement, timing, and accessibility rules.

In short

A tooltip is a small, temporary label, and a design system sets its text, placement, timing and accessibility rules.

13 min readFree

What you will learn

This lesson explains the tooltip, a common small part in a design system. You will learn what a tooltip is, when it is the right tool, which parts it has, how it should behave, and the accessibility basics every tooltip needs. The lesson ends with a worked example and a short quiz. Read the key words first.

Key words

Tooltip
A small, temporary label or hint that appears when a user points at, or moves keyboard focus onto, an element. It gives short extra information.
Trigger
The element that causes the tooltip to show, such as a button or an icon.
Hover
Moving a mouse or other pointer over an element without clicking it.
Focus
The spot on the screen that receives keyboard input right now. Pressing the Tab key moves focus from one element to the next.
Icon-only button
A button that shows a picture but no written words, so the picture must explain itself.
Supplementary
Extra. It adds to the screen but is not needed to finish a task.
Placement
Where the tooltip sits next to its trigger, such as above, below, left, or right.
Flipping
Moving the tooltip to the other side of the trigger when there is no room on the first side.
Escape key
The keyboard key marked Esc, often used to close a pop-up.
Screen reader
Software that reads the screen out loud for people who cannot see it well.
role=tooltip
A label that tells assistive software, such as a screen reader, that a box is a tooltip.
aria-describedby
A link between the trigger and the tooltip, so the screen reader reads the tooltip text when the trigger is reached.

What is a tooltip?

A tooltip is a small box of text. It appears next to an element and names it or explains it in a few words. Material Design, the design guidance from Google, calls these plain tooltips and describes them as brief labels that identify an element.

A design system treats the tooltip as a reusable component, one shared piece that product teams copy into their screens instead of building again. The component has set rules for what the text may contain, where the box sits, how long it waits before it shows, and how it reacts to mouse, keyboard, and touch. Without those rules, one team's tooltip might be a full paragraph and another's might vanish after a second.

Tip

Think of a tooltip as a tiny label that appears on demand. If someone could not finish the task without reading it, it does not belong in a tooltip.

When should you use a tooltip?

Tooltips are best for short, supporting text. Material's plain tooltips are the main use: they label UI elements that have no visible text, such as icon-only buttons. Here are three common uses a design system can allow.

  • Name an icon-only button

    A picture alone, like a trash can or a pencil, can mean more than one thing. A short tooltip tells the user what the button does before they click it.

  • Add a short hint

    A brief hint can explain an unusual icon or setting. Keep it to one idea.

  • Tell apart two similar things

    When two icons look alike, a tooltip can show which one does what. Material gives this as a use, for example when a tooltip distinguishes actions with related icons.

The opposite case matters just as much. A tooltip should not repeat text the user can already see. If a button already says Save, a tooltip reading Save adds nothing.

Tip

Ask one question before adding a tooltip: if the user never sees it, can they still finish the task? If the answer is no, the text belongs on the screen, not in a tooltip.

Tooltips are also easy to overuse. If every element on a page has one, users learn to ignore them. A good design system sets rules on which elements get a tooltip, so the same kind of element always behaves the same way.

Quick check

A teammate proposes a settings gear icon with a tooltip that says: Changing this setting will delete your saved data. Read the full message here. The team's rule is that tooltips hold short, supporting hints only. What is the best next step?

What should never go in a tooltip?

Three kinds of content do not belong in a tooltip. Each one breaks the way tooltips work.

  • Essential information

    If the user needs a fact to finish the task, put it on the screen.

  • Links

    A tooltip disappears when the pointer leaves, so a link inside it is hard to reach. This design system bans links in tooltips, so the rule is simple.

  • Interactive content

    Buttons, form fields, and other controls do not belong in a plain tooltip. The text is read-only. Users read it but cannot act on it.

Tip

Write the content rule into the design system: plain tooltips hold text only, with no links, no buttons, and no form fields. Writing it down stops teams from slowly adding one more link.

What are the parts of a tooltip?

A plain tooltip has a small set of parts. A design system names each part so designers and builders use the same words.

  • Trigger

    The element the user points at or focuses on, such as an icon button. The trigger is not part of the tooltip, but its rules control when the tooltip shows.

  • Text container

    The box that holds the words. The container has a set width limit, so long text wraps inside it.

  • Arrow

    A small pointer on the edge of the box that points at the trigger. It tells the user which element the tooltip belongs to.

Tip

When you write a spec, list every part by name and say what each one does. A part nobody named is a part each team will build its own way.

How should a tooltip act?

A behavior spec describes what happens and when. It covers placement, timing, dismissal, and touch. Each rule is written once and followed by every team.

Placement and flipping near screen edges

Placement is where the tooltip sits. A dp is a size unit that scales with the screen. Pick one default side and one gap, and write both into the spec.

Flipping means the tooltip changes side when the first side has no room. A button at the top edge of a screen has no space above it, so the tooltip moves below. The tooltip must stay fully on screen, and it should not cover important content. Keep it near the trigger and away from other controls.

Tip

Test a flip on purpose. Put your icon in each corner of a test screen and check that the tooltip stays fully on screen and still points at the right button.

Show and hide timing

Timing controls how fast a tooltip appears and disappears. A tooltip usually appears after a short delay, not the instant the pointer touches the trigger. The delay stops the screen from flashing each time the mouse crosses an icon. The design system should write one number and reuse it for every icon.

Hiding needs care too. A tooltip should close when the pointer leaves both the trigger and the tooltip, or when focus moves away. It should not vanish on a fixed timer while the user is still on it. Only one tooltip should be open at a time.

Tip

Write three timing rules: show after a short delay, hide when the pointer and focus both leave, and never close an open tooltip on a timer.

Dismissal with the Escape key

Dismissal means closing the tooltip without moving the pointer or focus. The standard keyboard way is the Escape key.

A keyboard user who presses Escape should see the tooltip go away, and focus should still be on the same button. The spec should say so in plain words, because screen reader users depend on that behavior too.

The hover-only problem on touch screens

Hover does not exist on most phones and tablets. A finger taps, and it does not rest over an icon. A tooltip that opens only on hover is therefore invisible to a touch user. Many implementations only trigger on mouse hover, which hides the text from keyboard and screen reader users too.

A design system should decide what touch users get. One common answer is that a tap on the trigger shows the tooltip. Another is to avoid relying on a tooltip for touch at all, and to place the important words on the screen. The accessibility guidance warns against depending on a tooltip for touch access.

Tip

Ask: how would a phone user learn what this icon does? If the only answer is by hovering, the design is not finished.

Quick check

A settings gear button on a phone app has a tooltip that opens only on hover. A tester says phone users never see the word Settings. What is the best fix from the design system's point of view?

Accessibility basics for the component

Accessibility means the component works for people who use a keyboard, a screen reader, or a different pointer. A tooltip that only works with a mouse fails many users. These four basics belong in every tooltip spec.

Open on keyboard focus, not only hover

Every tooltip that opens on hover must also open when its trigger gets keyboard focus. A keyboard user tabs from one button to the next, so the tooltip should follow focus the same way it follows the mouse.

Stay visible while the pointer is over it

A user who moves the pointer toward a tooltip should not lose it on the way. This is the reason for the short hide delay in the timing section.

The text stays static. Staying visible does not turn the box into a menu or a place to click. It means the user can read it without racing the mouse.

Link the tooltip to its trigger for screen readers

A screen reader user does not see the tooltip on the screen. The software needs a link. A tooltip that is not linked may never be read aloud.

The tooltip needs an identifier, a unique name in the page, and the trigger must point to that identifier.

  • Role on the tooltip box

    The box that holds the words gets the tooltip role, so assistive software knows what it is.

  • Reference on the trigger

    The trigger points to the tooltip with aria-describedby, so the tooltip describes the trigger.

  • No role on the trigger

    The button itself does not get the tooltip role.

Tip

The tooltip text often becomes the description a screen reader reads for the button. If the button has no visible words, make the tooltip name the action well, such as Archive, not Click here.

Contrast and readable text

The tooltip box must be easy to read. Check the exact pair of colors the tooltip uses, because tooltips often use slightly different values than the main product colors.

Worked example: an icon-only Archive button

This example follows one icon-only button through a design system's tooltip rules. The button is an Archive button, which shows a picture and no written label. Hovering over it or tabbing to it shows a tooltip reading Archive. The exact numbers are the team's choices, so they are left as named settings.

  1. 1

    Check that the button needs a tooltip

    The Archive button has no visible words. A plain tooltip is the right tool, because this is exactly the case Material describes for icon-only buttons.

  2. 2

    Write the text

    The text reads Archive. It is one word, specific, and names the action. It does not repeat other text on the screen.

  3. 3

    Set the placement

    The spec says the tooltip sits below the button with a fixed gap, for example the 4dp gap from Material's guidance. If the button is near the top edge with no room below, the tooltip flips above it.

  4. 4

    Set the timing

    The spec sets one short show delay for all icon buttons. It hides when the pointer and focus both leave. An open tooltip never closes on a timer.

  5. 5

    Set the input rules

    The tooltip opens on hover and on keyboard focus. Escape closes it, and focus stays on the Archive button. On a touch screen, a tap on the button shows the tooltip, so touch users are not left guessing.

  6. 6

    Link it for screen readers

    The tooltip box gets the tooltip role, and the Archive button points to it with aria-describedby. A screen reader then announces Archive when the button is reached.

  7. 7

    Write the rule once

    The team saves these steps as one rule in the design system. Every icon-only button then gets the same delay, the same side, and the same behavior, without each designer deciding again.

Tip

When you study a real product, check each step. Hover, tab to the button, press Escape, and try a phone if you can. Note what you see, then compare it with the rule your system should have.

A short checklist for a tooltip spec

  • Use

    Short, supporting text for icon-only buttons and similar elements, never essential facts.

  • Content

    Text only. No links, no buttons, no form fields.

  • Placement

    A default side, a fixed gap, and a flip rule near screen edges.

  • Timing

    One show delay, a hide rule, and no timer-based closing while open.

  • Input

    Opens on hover and keyboard focus, closes on Escape, and has a touch rule.

  • Accessibility

    Tooltip role, a unique identifier, and aria-describedby on the trigger.

Use this list as a starting point when you write or review a tooltip rule. Each line should become a sentence in the design system's written guidance, so teams can apply the same rule without asking.

Quick check

A designer builds a tooltip that opens when the mouse hovers over a button. A keyboard user tabs to the same button and sees nothing. Which rule did the designer miss?

Sources

How is this lesson?

Last updated on 17 November 2026

Learn with me

Every lesson is free. I add new ones as I learn. Have a question, or want help with your own work? Book a short call.