Basel Standard / Docs

Tooltip

Brief supporting label for icon controls, shortcuts, and compact metadata where the main surface should stay terse.

Tooltips work best as brief supporting labels.

Tooltip reveals one short line of supporting context from an explicit trigger. It is useful when the surface must stay compact but the control still needs a label, shortcut hint, or brief explanation.

Installation

Install

Purchase access, then open /account/install to issue a registry token.

Usage

import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/tooltip"

<TooltipProvider>
  <Tooltip>
    <TooltipTrigger asChild>
      <Button variant="outline">Review shortcut</Button>
    </TooltipTrigger>
    <TooltipContent>Press G then R to open the review queue.</TooltipContent>
  </Tooltip>
</TooltipProvider>

Why This Primitive Exists

Use it when the user needs a short supporting label without opening a richer overlay.
Prefer it for icon buttons, abbreviations, keyboard shortcuts, and compact status hints.
Avoid it for required instructions, validation, or any content the user must reliably read on touch devices without an alternate path.

Examples

Basic Supporting Label

The default case is one trigger and one concise line of text.

Tooltips work best as brief supporting labels.

<Tooltip>
  <TooltipTrigger asChild>
    <Button variant="outline">Review shortcut</Button>
  </TooltipTrigger>
  <TooltipContent>Press G then R to open the review queue.</TooltipContent>
</Tooltip>

Metadata And Icon Controls

Tooltips help compact controls stay legible without forcing persistent labels into dense toolbars.

<Tooltip>
  <TooltipTrigger asChild>
    <Button variant="outline" size="icon" aria-label="Access policy">
      <ShieldCheck className="size-4" />
    </Button>
  </TooltipTrigger>
  <TooltipContent>Visible to the release office only.</TooltipContent>
</Tooltip>

In Context

In dense product rows, a tooltip should clarify one label or one status token. The core record still needs to stay understandable without hovering.

Archive row

Use a tooltip to clarify a label, not to hide the record itself.

Dense product surfaces often need one short line of supporting context while keeping the main row readable.

Issue 08 / release brief

Waiting on subscriber copy before publish.

Blocked

<Tooltip>
  <TooltipTrigger asChild>
    <button type="button" aria-label="Blocked reason">
      <CircleAlert className="size-4" />
    </button>
  </TooltipTrigger>
  <TooltipContent>Subscriber copy is still pending legal approval.</TooltipContent>
</Tooltip>

Guidance

Keep The Content Brief

Aim for one sentence or less.
Use the tooltip to clarify a label, not to deliver a second interface.
If the content needs links, actions, or several lines of structure, move to HoverCard, Popover, or Dialog.

Use Explicit Triggers

Pair the tooltip with a visible button, icon, badge, or label the user can already identify.
Use asChild so the trigger can remain the real button or link element.
Give icon-only triggers an aria-label even when a tooltip is present.

Do Not Hide Critical Information

Required instructions belong inline.
Validation belongs next to the field or in a blocking surface.
On touch-first flows, provide another way to reach the same information.

API Reference

Exports

Export	Renders	Notes
`TooltipProvider`	`TooltipPrimitive.Provider`	Sets shared delay behavior for descendant tooltips.
`Tooltip`	`TooltipPrimitive.Root`	Root state container.
`TooltipTrigger`	`TooltipPrimitive.Trigger`	Interactive trigger element, commonly used with `asChild`.
`TooltipContent`	`TooltipPrimitive.Content` inside a portal	Styled tooltip surface with shared Swiss typography.

`TooltipProvider`

Prop	Type	Default	Notes
`delayDuration`	`number`	`150`	Delay before the tooltip opens.
`skipDelayDuration`	Radix provider prop	Radix default	Controls how quickly subsequent tooltips open.

`TooltipContent`

Prop	Type	Default	Notes
`sideOffset`	`number`	`8`	Space between the trigger and the tooltip.
`className`	`string`	`undefined`	Extends the shared tooltip styling.
`side`, `align`, `avoidCollisions`	Radix content props	Radix defaults	Positioning controls remain available.

The wrapper keeps Radix positioning and accessibility behavior intact while applying the repo's compact uppercase tooltip styling.

Previous: Toggle Group Next: Product Card Editorial