JM Family Design System

Tooltip

Tooltips provide brief supplemental clarification for focused controls or compact UI. They should never be the only place users can find required information.

Guidance for adoption

Start here before choosing examples or props. These notes explain where Tooltip helps, where another pattern is better, and what should stay true in product work.

When to use

  • Clarifying icon-only controls
  • Explaining compact metadata
  • Supplemental hints
  • Truncated labels

When not to use

  • Required instructions
  • Error messages
  • Long explanations
  • Touch-only workflows

Accessibility expectations

  • Connect tooltip content with aria-describedby when it supplements a focusable control.
  • Show tooltips on keyboard focus as well as pointer hover.
  • Do not put interactive controls inside a tooltip.
  • Ensure the trigger has an accessible name without depending on the tooltip.

Content guidance

  • Keep tooltip text brief and supplemental; it should clarify rather than teach the workflow.
  • Make sure the trigger already has a useful visible label or accessible name without the tooltip.
  • Put required instructions, validation errors, and recovery steps directly in the interface instead.
  • For touch-heavy flows, provide the same information as visible helper text or another persistent pattern.

Implementation notes

  • Generate a stable id and connect the tooltip to its trigger with aria-describedby.
  • Show and hide tooltip content on pointer hover and keyboard focus; the component does not provide trigger logic.
  • Support Escape dismissal and overflow-aware placement in the consumer when needed.
  • Do not put buttons, links, or other interactive content inside a tooltip.

Import

import { Tooltip } from '@/components/ui/Tooltip';

Renders a positioned bubble. Pair an id here with aria-describedby on the trigger element.

Usage patterns

Tooltips work best as a small assist for dense interfaces. If the user needs the information to continue, put it directly in the layout.

Icon control
Search design system

Clarifies a compact control that already has an accessible name.

Compact metadata
Risk scoreHighCalculated from contract value and vendor history.

Adds optional context for a dense label or status value.

Truncated text
JM Family Enterprise Procurement Agreement...JM Family Enterprise Procurement Agreement 2026

Reveals text that is visually shortened, without replacing the source content.

Avoid required info

Format guidance belongs here, not only behind the icon.

Required instructions and errors must be visible in the interface.

Placement

Placement should keep the tooltip close to its trigger without covering the thing users are trying to inspect.

Top
Top tooltip
Right
Right tooltip
Bottom
Bottom tooltip
Left
Left tooltip

Anatomy

A tooltip needs a named trigger, short supplemental copy, and a programmatic relationship that assistive technology can understand.

Open settings
  1. Focusable trigger
  2. Accessible trigger name
  3. Short tooltip text
  4. aria-describedby link
  5. Keyboard behavior
  6. Non-interactive content

Props

The component accepts every native HTMLSpanElement attribute on top of the design system props below.

PropTypeDefaultDescription
placement'top' | 'bottom' | 'left' | 'right''top'Which side of the trigger the bubble appears on. Choose to avoid covering the inspected element.

Usage rules

Use tooltips for supplemental help

A tooltip should clarify a compact control or value after the visible UI already makes sense.

Do not hide required information

Labels, instructions, validation errors, and recovery steps need to be visible without hover.

Support focus and hover

Keyboard users should get the same clarification pointer users get.

Do not put actions inside tooltips

If the content needs buttons, links, fields, or rich formatting, use a popover, dialog, or panel.

Known limitations

What Tooltip does not do yet, and what consumers need to compose themselves.

  • No trigger logic, portal, or collision detection. The component is a styled span with directional placement relative to its parent; show/hide on hover and focus, escape-to-dismiss, and overflow-aware flipping must be implemented by the consumer.
  • No id-to-trigger wiring. Consumers must manually link the tooltip to its trigger via aria-describedby; the component does not generate or thread an id.

Agent guidance

Agents should generate tooltips only for optional clarification. Required content should be visible as labels, helper text, errors, or normal body copy.

Generation rules

  • Use tooltips only for supplemental clarification.
  • Do not hide required labels, instructions, or errors inside a tooltip.
  • Keep tooltip text short and plain.
  • Provide visible text when the user needs the information to complete a task.
  • Generate a stable id in the consumer and pass it to both the tooltip element and the trigger as aria-describedby. The component does not thread an id automatically.
  • Show the tooltip on pointer hover and on keyboard focus, and hide it on Escape. The component is a styled span; the trigger logic must be implemented in product code.
  • Do not put interactive controls such as Button or Link inside a tooltip; the content disappears when focus moves and users cannot reach it on touch devices.
  • Skip the tooltip on touch-only flows. Surface the same content as visible helper text or an info Alert so mobile users see it without hover.

Baseline example

import { Tooltip } from '@/components/ui/Tooltip';

<button type="button" aria-label="Filter results" aria-describedby="filter-tip">
  <Search aria-hidden="true" />
</button>
<Tooltip id="filter-tip" placement="top">
  Filter results
</Tooltip>
If generated UI needs a tooltip to explain a label, agents should improve the label or add visible helper text before adding the tooltip.

Decision standard

Tooltips clarify. They do not teach, validate, warn, or replace visible information users need to complete the task.