Tooltip

A floating label that appears on hover or focus.

Default

Translucent black glass with a backdrop blur, so content underneath stays readable. Falls back to solid neutral-950 without backdrop-filter. Plain labels clamp at two lines.

Support agent answers inbound calls on +1 415 555 0132 and hands off to a person when a caller asks for one.

import {
  Button,
  CopyIcon,
  Tooltip,
  TooltipPopup,
  TooltipTrigger,
} from "@smallest-inc/ui";

export default function TooltipDefault() {
  return (
    <div className="relative flex min-h-24 w-full items-end justify-center">
      <p className="pointer-events-none absolute inset-x-0 top-0 max-w-sm text-sm leading-6 text-fg-secondary">
        Support agent answers inbound calls on +1 415 555 0132 and hands off to a person when a caller asks for one.
      </p>
      <Tooltip defaultOpen>
        <TooltipTrigger render={<Button variant="secondary" iconOnly aria-label="Copy agent ID" />}>
          <CopyIcon />
        </TooltipTrigger>
        <TooltipPopup>Copy agent ID</TooltipPopup>
      </Tooltip>
    </div>
  );
}

Side

Top is the default. Near an edge the tooltip flips to the opposite side; this example turns flipping off so each one opens where its label says.

import { Button, Tooltip, TooltipPopup, TooltipTrigger } from "@smallest-inc/ui";

const sides = [
  { side: "top", label: "Top", className: "col-start-2 row-start-1" },
  { side: "left", label: "Left", className: "col-start-1 row-start-2" },
  { side: "right", label: "Right", className: "col-start-3 row-start-2" },
  { side: "bottom", label: "Bottom", className: "col-start-2 row-start-3" },
] as const;

export default function TooltipSide() {
  return (
    <div className="mx-auto grid grid-cols-3 grid-rows-3 place-items-center gap-3 py-8">
      {sides.map(({ side, label, className }) => (
        <Tooltip key={side}>
          <TooltipTrigger className={className} render={<Button variant="secondary" />}>
            {label}
          </TooltipTrigger>
          <TooltipPopup side={side} collisionAvoidance={{ side: "none" }}>
            Opens on the {side}
          </TooltipPopup>
        </Tooltip>
      ))}
    </div>
  );
}

Title and description

TooltipHeader stacks a one-line TooltipTitle over a TooltipDescription. A description that would wrap past two lines is left out rather than truncated.

import {
  Button,
  Tooltip,
  TooltipDescription,
  TooltipHeader,
  TooltipPopup,
  TooltipTitle,
  TooltipTrigger,
} from "@smallest-inc/ui";

export default function TooltipTitleExample() {
  return (
    <div className="mx-auto flex min-h-28 items-end">
      <Tooltip defaultOpen>
        <TooltipTrigger closeDelay={150} render={<Button variant="secondary" />}>
          Call recording
        </TooltipTrigger>
        <TooltipPopup>
          <TooltipHeader>
            <TooltipTitle>Call recording</TooltipTitle>
            <TooltipDescription>Save the next conversation for your team.</TooltipDescription>
          </TooltipHeader>
        </TooltipPopup>
      </Tooltip>
    </div>
  );
}

Action

Add one TooltipAction for a single next step. Give the trigger a closeDelay so the pointer can reach the button.

import {
  Button,
  Tooltip,
  TooltipAction,
  TooltipDescription,
  TooltipHeader,
  TooltipPopup,
  TooltipTitle,
  TooltipTrigger,
  toast,
} from "@smallest-inc/ui";

export default function TooltipActionExample() {
  return (
    <div className="mx-auto flex min-h-40 items-end">
      <Tooltip defaultOpen>
        <TooltipTrigger closeDelay={150} render={<Button variant="secondary" />}>
          Recording off
        </TooltipTrigger>
        <TooltipPopup>
          <TooltipHeader>
            <TooltipTitle>Turn on call recording</TooltipTitle>
            <TooltipDescription>Save the next conversation for your team.</TooltipDescription>
          </TooltipHeader>
          <TooltipAction onClick={() => toast.dark("Call recording is on")}>Turn on</TooltipAction>
        </TooltipPopup>
      </Tooltip>
    </div>
  );
}

Documentation callout

A Circle Info button beside a label that opens a short explanation. View docs opens href in a new tab.

Call recording

import { DocumentationCallout } from "@smallest-inc/ui";

export default function TooltipDocumentationCallout() {
  return (
    <div className="mx-auto flex min-h-40 items-end gap-1.5">
      <span className="text-sm font-medium text-fg">Call recording</span>
      <DocumentationCallout
        defaultOpen
        href="/changelog"
        label="About call recording"
        title="Call recording"
        description="Save the next conversation for your team."
      />
    </div>
  );
}

Grouped

Wrap adjacent triggers in TooltipProvider so, once one tooltip is open, the next opens instantly.

import {
  BoldIcon,
  ItalicIcon,
  Toggle,
  Tooltip,
  TooltipPopup,
  TooltipProvider,
  TooltipTrigger,
  UnderlineIcon,
} from "@smallest-inc/ui";

export default function TooltipGrouped() {
  return (
    <TooltipProvider>
      <div className="flex items-center gap-1">
        <Tooltip>
          <TooltipTrigger render={<Toggle variant="secondary" aria-label="Bold" />}>
            <BoldIcon />
          </TooltipTrigger>
          <TooltipPopup>Bold</TooltipPopup>
        </Tooltip>
        <Tooltip>
          <TooltipTrigger render={<Toggle variant="secondary" aria-label="Italic" />}>
            <ItalicIcon />
          </TooltipTrigger>
          <TooltipPopup>Italic</TooltipPopup>
        </Tooltip>
        <Tooltip>
          <TooltipTrigger render={<Toggle variant="secondary" aria-label="Underline" />}>
            <UnderlineIcon />
          </TooltipTrigger>
          <TooltipPopup>Underline</TooltipPopup>
        </Tooltip>
      </div>
    </TooltipProvider>
  );
}

Animated

Detached triggers share one popup through TooltipCreateHandle. Pass adaptive on TooltipPopup so its position, size and copy morph between hints.

import { useState } from "react";
import {
  BoldIcon,
  ItalicIcon,
  Toggle,
  Tooltip,
  TooltipCreateHandle,
  TooltipPopup,
  TooltipProvider,
  TooltipTrigger,
  UnderlineIcon,
} from "@smallest-inc/ui";

const hints = [
  { label: "Bold", hint: "Make text bold", icon: BoldIcon },
  { label: "Italic", hint: "Apply italic formatting to text", icon: ItalicIcon },
  { label: "Underline", hint: "Underline text", icon: UnderlineIcon },
];

export default function TooltipAnimated() {
  const [handle] = useState(() => TooltipCreateHandle<string>());

  return (
    <TooltipProvider>
      <div className="relative flex items-center gap-1">
        {hints.map(({ label, hint, icon: Icon }) => (
          <TooltipTrigger
            key={label}
            // Bridge the 4px gap so the pointer never leaves a trigger between hints.
            className="after:absolute after:left-full after:h-full after:w-1"
            handle={handle}
            payload={hint}
            render={<Toggle variant="secondary" aria-label={label} />}
          >
            <Icon />
          </TooltipTrigger>
        ))}
      </div>
      <Tooltip handle={handle}>
        {({ payload }) => <TooltipPopup adaptive>{payload != null ? <span>{payload}</span> : null}</TooltipPopup>}
      </Tooltip>
    </TooltipProvider>
  );
}

Best practices

Use for a short, supplemental label on an icon-only control or an unfamiliar term: “Copy agent ID”.
Do not put required instructions, validation or the only label for a control in a Tooltip; icon-only triggers still need an aria-label.

Tooltip is translucent black glass only: no arrow, no light surface. Top is the default side and it flips near edges.
Wrap adjacent triggers (toolbars) in TooltipProvider so, once one is open, the next opens instantly.
Use TooltipCreateHandle with detached triggers and adaptive on TooltipPopup when one popup should morph between several hints.
Give triggers with a TooltipAction a closeDelay (150ms) so the pointer can reach the button.

Plain labels clamp at two lines; keep them to a few words with no ending period.
A TooltipTitle is one line. A TooltipDescription shows only when it fits in two lines; longer copy is left out, not truncated.
Use one TooltipAction for a single next step. Put longer or multi-action content in Hover Card or Popover.
Use DocumentationCallout (Circle Info trigger) next to a label for a short explanation with a View docs link. It captures documentation_callout_clicked with source pagename/adjacent-heading.

PreviousToggle NextBreakdown Chart

Tooltip

Default

Side

Title and description

Action

Documentation callout

Grouped

Animated

Best practices

When to use

Behavior

Content

Tooltip

Default

Side

Title and description

Action

Documentation callout

How PostHog tracking works

Grouped

Animated

Best practices

When to use

Behavior

Content