Monogem

Component · Containers & Overlays

Overview

A short, supplementary label that appears next to a trigger on hover or keyboard focus — a clarification, never a requirement. Its hover and focus behavior, delay, and placement are specified below.

Anatomy

Trigger (any element) → Tooltip surface (single line or short wrapped phrase of text).

Trigger — any element that reveals the tooltip on hover or keyboard focus.
Surface — a single line or short wrapped phrase of text.

No icon, no title/body split, no action row — Tooltip is text-only.

Live Example

Naming an icon-only button

Clarifying a visible label

Monthly active users

Placement below

Code Example

tooltip-showcase.tsx

"use client";

import { Info, Settings } from "lucide-react";

import { Button } from "@/components/ui/button";
import { Tooltip } from "@/components/ui/tooltip";

/**
 * Live Tooltip example — hover a trigger and the tooltip appears after a brief
 * delay; focus it from the keyboard (Tab) and it appears immediately;
 * `mouseleave`, `blur`, or `Escape` dismiss it. Each icon-only trigger carries
 * its own `aria-label` — the tooltip is supplementary, never the control's
 * accessible name.
 *
 * The tooltip surface is text-only and `pointer-events-none`: it never holds a
 * link, button, or field (that boundary is what separates it from Popover).
 */
export function TooltipShowcase() {
  return (
    <div className="flex flex-col gap-8">
      <section className="flex flex-col gap-3">
        <h3 className="text-sm font-medium leading-snug text-muted-foreground">
          Naming an icon-only button
        </h3>
        <div className="flex items-center gap-3">
          <Tooltip content="Settings">
            <Button size="icon" variant="ghost" aria-label="Settings">
              <Settings />
            </Button>
          </Tooltip>
          <Tooltip content="Opens in a new tab">
            <Button size="icon" variant="outline" aria-label="Documentation">
              <Info />
            </Button>
          </Tooltip>
        </div>
      </section>

      <section className="flex flex-col gap-3">
        <h3 className="text-sm font-medium leading-snug text-muted-foreground">
          Clarifying a visible label
        </h3>
        <div className="flex items-center gap-2 text-sm leading-normal">
          <span>Monthly active users</span>
          <Tooltip content="Distinct accounts with at least one session in the last 30 days.">
            <button
              type="button"
              aria-label="What counts as a monthly active user?"
              className="inline-flex size-5 items-center justify-center rounded-full text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
            >
              <Info className="size-4 [stroke-width:var(--icon-stroke-width)]" />
            </button>
          </Tooltip>
        </div>
      </section>

      <section className="flex flex-col gap-3">
        <h3 className="text-sm font-medium leading-snug text-muted-foreground">
          Placement below
        </h3>
        <Tooltip content="Anchored below the trigger" side="bottom">
          <Button variant="outline">Hover or focus me</Button>
        </Tooltip>
      </section>
    </div>
  );
}

States

State	Look
Hidden	Not rendered (or `display: none` equivalent) — not just visually transparent
Visible	`--popover` fill, `--popover-foreground` text, `--shadow-md`

Tooltip has no hover/focus/disabled states of its own — those apply to the trigger, not the tooltip surface itself.

Usage Guidance

Purpose and when to use it

Use Tooltip for short supplementary information only — naming an icon-only button, expanding an abbreviation, adding a one-line clarification to a label that's already visible and understandable without it. A Tooltip should never be the only place essential information lives.

When not to use it

Essential instructions. If a user cannot complete a task without reading the tooltip's content, that content belongs in visible text (a Label, helper text, or the surrounding copy), not hidden behind a hover. Touch devices have no hover state at all, so hover-only content is invisible to a meaningful share of users by default.
Interactive content. A tooltip never contains a button, a link, or any focusable element — the moment content needs to be clicked, it's a Popover, not a Tooltip.
Long content. See Content length below.

Trigger relationship

The trigger is typically an icon-only Button or another compact control whose purpose isn't obvious from its visible content alone. The Tooltip is associated with its trigger, not freestanding — it only ever appears anchored to one element and disappears when that element loses hover/focus.

Delay and dismissal as implementation concerns

The exact hover delay (commonly somewhere in the 300–700ms range) and the precise dismissal trigger (mouse leave, blur, Escape) are implementation-time decisions, not design tokens — there's nothing on the Scale that represents a duration. The design contract this page sets is the outcome: a brief delay before appearing on hover, no delay on keyboard focus, and dismissal on mouse-leave, blur, or Escape.

Placement

Default placement is above the trigger, centered. When the trigger is near a viewport edge, the tooltip should prefer flipping to the opposite side (below) before shifting sideways — the same collision-avoidance intent Popover documents. The actual collision math (measuring available space and choosing a fallback) runs at render time against the real viewport; this page specifies the preferred order, not the algorithm.

Content length

One short phrase, ideally under about 60 characters, single line where possible. If content needs to wrap, it should wrap to at most two short lines — a paragraph belongs in a Popover or inline help text, not a Tooltip.

	Tooltip	Popover
Content	Plain text only	Any content, including interactive controls
Trigger	Hover or keyboard focus	Click/press (typically)
Dismissal	Automatic — mouse leaves, focus moves away	Explicit — click outside, `Escape`, or a close action
Purpose	Label/clarify something already visible	Surface additional content or actions on demand

Tokens

Tooltip uses existing Monogem semantic tokens to stay consistent with the design system; it introduces no component-specific styling values.

Token	Where used
`--popover` / `--popover-foreground`	Surface fill + text — Color already names "Menus, tooltips" for this pair
`--shadow-md`	Elevation — Shadows names "Dropdowns, popovers, hover"
`--radius-md`	Corner radius — a tighter radius than a full Popover's `--radius-lg`, matching Tooltip's smaller, caption-like footprint
`--scale-1-5`	Padding-y — same value Scale already names for "Tag and badge padding"
`--scale-2`	Padding-x
`--scale-1-5`	Gap between trigger and tooltip surface
Caption text recipe	Tooltip text (`text-xs leading-snug`) — the same recipe Input's helper/error text uses

Do / Don’t

Do

Keep content to one short phrase.
Pair every icon-only trigger with both a Tooltip (visible label) and aria-label (accessible name) — see Accessibility.
Let the tooltip disappear automatically; never require a click to dismiss it.

Don’t

Put a button, link, or form control inside a Tooltip.
Use a Tooltip as the only source of instructions needed to complete a task.
Show a Tooltip on tap-and-hold as a substitute for solving the no-hover touch case properly.

Accessibility

The trigger carries its own accessible name independent of the tooltip — most often via aria-label on an icon-only Button — because a tooltip's visibility is not guaranteed to every assistive technology and must never be the sole source of a control's name.
The tooltip surface is associated to its trigger via aria-describedby, referencing the tooltip's id.
Escape dismisses an open tooltip without moving focus away from the trigger.
Tooltip content is never announced as an interruption (no live region) — it's descriptive text tied to the trigger's own accessible description, not a notification.

Hover and keyboard-focus expectations

Trigger event	Expected behavior
Mouse hover	Tooltip appears after a short delay (see Delay and dismissal)
Keyboard focus (`:focus-visible`)	Tooltip appears without a hover-style delay — a keyboard user has already made a deliberate action to land there
Touch	No native hover exists — see When not to use it; a touch-only path to the same information (e.g. a tap revealing the tooltip, or the information being visible another way) is required, though no single technique is mandated. The Version 1 Tooltip opens on hover and keyboard focus and has no dedicated touch fallback, so never let it be the only place essential information lives

Related Components / Patterns

Popover — richer, triggered supplemental content.

Tooltip