# Tooltips

Tooltips are small text labels that appear when a user hovers over, focuses on or taps an interface element, explaining what it is or what it does. In user onboarding, tooltips also act as pop-up hints that point at a feature to draw a new user's attention to it.

## What are tooltips used for?

Tooltips explain an interface element in place, without sending the user to documentation. They do three jobs:

- **Labeling icons:** naming an icon-only button, such as a funnel icon that means "Filter."
- **Clarifying fields:** saying what a field expects ("Use the billing contact's email, not yours").
- **Pointing at features:** in onboarding, a hint that calls out something new or easy to miss.

The first two are part of interface design and usually show on hover or focus. The third is a guidance pattern: the tooltip appears on its own, often with a "Got it" button.

## How do you design good tooltips?

- **Keep them short.** One sentence. If it needs a paragraph, it belongs in help content.
- **Never hide essential information.** If users need it to complete the task, show it on the page.
- **Make them reachable without a mouse.** They should appear on keyboard focus too, and work on touch screens, where hover doesn't exist.
- **Follow the accessibility rules.** WCAG 2.1 success criterion 1.4.13, [Content on Hover or Focus](https://www.w3.org/WAI/WCAG21/Understanding/content-on-hover-or-focus.html) (Level AA), asks that a tooltip can be closed without moving the pointer or focus (usually with the Escape key), stays open while the pointer moves over it, and stays visible until the user moves away or closes it. Link the tooltip to its control with `aria-describedby` so screen readers announce it.

## How are tooltips used in onboarding?

Onboarding tooltips show up unprompted to direct attention. A common setup: a new user lands on a dashboard and three tooltips point, one after another, at the date picker, the export button and the share menu. Strung together, they become a product tour.

They work well for one thing at a time. A single tooltip on a new button the week it ships is useful. A sequence on first login rarely lands, because the user hasn't started a task that needs the date picker yet.

## What are the limits of tooltips, and what are the alternatives?

Tooltips explain where something is. They can't do the task, and they can't tell what the user is trying to achieve. They also break or drift when the interface changes, so each one needs upkeep.

Alternatives depend on the job. Clearer labels and better defaults remove the need for many tooltips. Empty states teach in context. Walkthroughs help with a full task. And when the user just wants the task done, a tooltip can only point to the step, while an in-product agent can do it with them. That is the approach Foldspace takes: the Product Agent does the step in the product, [with the signed-in user's own access](https://docs.foldspace.ai/privacy/llm-governance/).

## Learn more

- [Product Agent](/platform/product-agent)