Tooltip

Anatomy

import {Tooltip} from '@staffbase/spark';

<Tooltip.Root>
  <Tooltip.Trigger />
  <Tooltip.Content />
</Tooltip.Root>

Examples

Icon-only button label

Truncated link

• There are a few cases in which the tooltip must not provide either accessible name nor description. In this example, the full text can already be accessed by assistive technology and we only need to provide a visual alternative.
• When there is a large list of items on a page that make use of tooltips to display possibly non-essential information, the delay prop on the Trigger should be used to avoid the tooltip appearing immediately as the user scrolls through. This mimics the native title attribute.

Truncated text

Contextual information

• Contextual tooltips should only be used on focusable elements that have a visible label.
• In this example, the image and additional name are only helpful for sighted users, but should not be read by a screen reader. Therefore, the decorative image has the attribute alt="" and the text aria-hidden.
• If the contextual information is more extensive, it is expected there are alternative ways to access it. In this example, the tooltip displays a preview of a user profile and clicking the link would refer you to the full profile.

API reference

Root

Trigger

Content

When to use

• To name an icon-only control that has no visible text label, such as an icon-only Button.
• To reveal the full text of a truncated element, such as a shortened link or a long title.
• To add one short line of supplementary information to an interactive element, beyond what its visible label already says.

When not to use

• Don’t put links, buttons, or other interactive elements inside a tooltip — use Popover instead.
• Don’t use a tooltip for content that needs two or more lines of text — show the information directly on the page, or use Popover instead.
• Don’t use a tooltip for rich content with a complex layout — use Popover or a custom solution instead.
• Don’t use a tooltip to show a validation error — use the field’s error state with Field or a Banner instead.
• Don’t attach a tooltip to a non-interactive element such as static text or a Pill — it can’t receive focus, so keyboard and screen reader users never see the tooltip; use a focusable Button as the trigger instead.
• Don’t attach a tooltip to a disabled button — a disabled button can’t receive focus, so the tooltip is unreachable by keyboard; use visible helper text (for example in a Field) instead.
• Don’t use a tooltip to repeat information that is already visible next to the trigger — it adds no value and increases cognitive load; rely on the trigger’s visible label (for example on a Button) instead.

How to use

Structure

• Compose a tooltip from Tooltip.Root, Tooltip.Trigger, and Tooltip.Content.
• Pass the trigger as a single interactive element — typically an icon-only Button or a link.
• The tooltip opens when the trigger is hovered or focused and closes on leave, blur, or Escape — don’t open tooltips on click; use Popover instead.
• In dense lists, set a delay on Tooltip.Trigger so tooltips don’t appear immediately as the user scrolls.
• Keep tooltip content to plain text, optionally with icons — never interactive elements.

Variants

• Use variant="default" — a dark surface with light text — for most cases.
• Use variant="inverse" — a light, bordered surface — when the tooltip sits on a dark background where the default surface lacks contrast.

Placement

• Use the side prop to position the tooltip relative to its trigger: top (default), bottom, left, right, inline-start, or inline-end.
• Prefer the default top placement, and pick another side only when the tooltip would otherwise cover important content.
• Prefer inline-start and inline-end over left and right so the placement flips automatically in right-to-left languages.
• The tooltip repositions automatically when there isn’t enough space on the chosen side.

Accessibility

• Always set the is prop on Tooltip.Content: use label when the tooltip names the trigger, description when it adds supplementary detail, and visual-only when the same content is already exposed to assistive technology elsewhere, such as a truncated text.
• Only use focusable, interactive elements as triggers so keyboard and screen reader users can reach the tooltip.
• Don’t put information users need to complete a task only in a tooltip — hover isn’t available on touch devices.

Content & UX copy

• Write body text only — a tooltip has no title.
• Use sentence case.
• Don’t use ending punctuation unless the content is a complete sentence.
• Keep the content to a single short line of text.
• Bring new information — don’t restate the trigger’s visible label or re-explain a field label.