Tooltip

A short label that appears beside its trigger on hover or on keyboard focus. Wraps @base-ui/react/tooltip and adds the one thing Base UI 1.6 does not emit: the `role="tooltip"` / `aria-describedby` pair.

overlayclient≥ 320pxuiv1.4.0

Tooltip — live renderprimitives-tooltip--default ↗

Rendered from the story the storybook (a11y) CI gate runs axe against — the preview can't show something that hasn't been verified.

Install

Two equivalent paths — the URL works in any shadcn-CLI setup; the alias works once you've registered @interlace in your components.json.

Via shadcn URL

npx shadcn@latest add https://ds.interlace.tools/r/tooltip.json

With the @interlace alias

npx shadcn@latest add @interlace/tooltip

Behavior

What this component does — the keyboard path, the measured colour, the text equivalent and the states it can be in. Every figure below is read out of the test or the source that enforces it by scripts/build-behavior-map.mjs, so nothing here can outlive the gate that keeps it true.

Keyboard path

apps/storybook/src/stories/primitives/Tooltip.stories.tsx ↗

2 steps, 1 key press — replayed on every PR by the play function of KeyboardFlow. Axe cannot press a key, so this — not the a11y scan — is what proves the component is operable without a mouse.

1Focus alone reveals the tooltip
2Escape dismisses it without moving focusEscape

Escape is locked, not merely exercised. This primitive is in KEYBOARD_DRIVEN + MUST_ASSERT_ESCAPE — deleting the dismissal assertion from the story fails overlay-nav-keyboard-lock, so the path above cannot quietly stop being tested.

Measured contrast

packages/ui/__tests__/theme-contract-lock.test.ts ↗

Every semantic colour pair this component's own source uses, measured against the shipped hexes in all 4 theme × scheme combinations. The tightest is primary on background at 8.39:1 (harbor · light), against a floor of 3:1.

Measured WCAG contrast ratios per token pair and theme
Pair	interlacelight	interlacedark	harborlight	harbordark	Floor
primary on backgroundprimary tint on the page surface	8.80:1	11.79:1	8.39:1	10.03:1	3.0:1SC 1.4.11
primary-foreground on primarycopy on a primary face	8.80:1	11.79:1	8.86:1	10.03:1	4.5:1SC 1.4.3
primary on cardprimary tint inside a card	8.80:1	10.92:1	8.86:1	9.10:1	3.0:1SC 1.4.11

Text pairs are held to 4.5:1 (WCAG 2.2 SC 1.4.3); borders, rings and chart axes to 3:1 (SC 1.4.11 non-text). Bold is the worst cell in the row — the one a brand fork has to keep an eye on.

Runtime contract

packages/ui/vitest.config.ts ↗

Where it renders, how narrow it survives, and whether its lines are inside the coverage gate — three answers a consumer needs before the paste, not after the bug.

Render boundary: 'use client'
Hydrates. It brings JavaScript to any route that imports it — put the boundary here, not at the page.
Minimum viewport: MIN_VIEWPORT = 320
Declared, not assumed. Below 320 CSS px the preflight contract draws a dev-mode outline — how to switch it on.
Coverage gate: not in the gate
The 100% gate currently covers src/charts/**/*.{ts,tsx} and src/lib/**/*.{ts,tsx} and src/primitives/{button-variants,data-state-model,meter-scale,skeleton-variants}.ts and src/primitives/{alert,aspect-ratio,avatar,badge,box,breadcrumb,button,callout,card,checkbox,code-editor,container,data-state,focus-ring,grade-badge,grid,input,label,meter,pagination,published-date,reading-time,section,section-boundary,separator,skip-link,stack,stat-strip,tag,textarea,typography,visually-hidden}.tsx and src/patterns/lint-playground.tsx. This file is outside it — the glob widens in phase 7.2.

History

This component is at v1.4.0, first shipped in @interlace/ui 1.0.0. The version is stamped as a banner into the file the install writes, so the copy in your tree says which one you have — compare it with the number above before deciding whether to re-run the install.

@interlace/ui 1.1.01 entry

Changedpatch
Six defects found by upgrading a real consumer, plus five found by reading the components closely enough to document them. **Meteors' glow never painted.** It read var(--color-meteor-glow) while its cssVars declare --meteor-glow; --color-* is the Tailwind @theme namespace and only cssVars.theme populates it, so the whole box-shadow was invalid at computed-value time. **This was broken only for registry consumers** — our own docs site hand-declares the --color- form. **ArticleCard cropped 28% off every cover.** h-44 is 176px; at a ~302px tile that is a 1.72:1 box against a 2.381:1 image. Now aspect-[1000/420] — the ratio the card already declared on its <img>. It also gains a renderImage slot, because every Next.js consumer was re-patching the same line to use next/image and the design system cannot depend on it. **BorderBeam and StarsBackground had no aria-hidden at all** — six purely decorative nodes a screen reader walked. **CloudParticles defaulted bodyColor to currentColor**, painting volumetric clouds in the inherited text colour. **NumberTicker gains notation**, because six-figure metrics overflow a tile at 320px. Also: SheetCompose and DialogCompose each mounted a second backdrop, so a composed dialog dimmed the page twice as much as the hand-composed tree the docs show; Accordion dropped className on the animated Panel; Tooltip accepted delay and discarded it; PopoverAnchor was a second trigger. **useReducedMotion was one frame late.** The canonical useState(false) plus effect returns false on the first render, so every gated component painted one frame of exactly the motion the user turned off. useSyncExternalStore reads during render and closes that on client renders; on hydration the server cannot know the preference, which is what the stylesheet reset is for. Badge drops 'use client' — verified with a real server-component build.
Components

@interlace/ui 1.0.01 entry

Addedminor
The component floor reaches every tier: form, overlay, navigation and display primitives were modelled to the portable 26-rule floor with skeletons, locked breakpoints, and AA contrast measured per composite rather than eyeballed.
Components

Import

6 named exports — pull the parts you need.

Public API

import { MIN_VIEWPORT, Tooltip, TooltipCompose, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip';

Anatomy

Extracted from the primitive's JSDoc header. The source is the only documentation that can't drift.

Tooltip                          (TooltipProvider → context → Tooltip.Root)
    ├─ TooltipTrigger              (Tooltip.Trigger — carries aria-describedby)
    └─ TooltipContent              (Portal → Positioner → Popup — id, role=tooltip)
         └─ Tooltip.Arrow

API reference

Parsed from the type declarations in the source — the same file the install writes into your tree, so this table can't drift from the component you get.

TooltipProps

Also accepts every prop of Base UI's <Tooltip.Root> — behaviour we compose rather than reimplement.

Prop	Type	Description
delay	number	How long to wait before opening, in ms. Base UI puts `delay` on the PROVIDER, not on `Tooltip.Root` — and because this component mounts its own provider (see the header), the provider a call site could otherwise reach is not the one that governs this tooltip. So the prop is declared here and handed to the provider this file owns. Default 0, matching `TooltipProvider`.
closeDelay	number	How long to wait before closing, in ms. Same routing as `delay`.

TooltipComposeProps

Prop	Type	Description
trigger*	React.ReactNode	—
label*	React.ReactNode	Tooltip text — typically a short label or shortcut hint.
side	React.ComponentProps<typeof TooltipContent>['side']	Floating-UI side.
delay	number	Delay before showing (ms). Defaults to 0, the `TooltipProvider` default.
className	string	—

Accessibility

Every story for this component is rendered headlessly and checked with axe-core (wcag2aa, wcag22aa, best-practice, ACT) on every PR. That gate has no continue-on-error, so what ships has zero known violations.

What follows is what static analysis can see. Axe cannot press a key and never sees an overlay open, so the operable-without-a-mouse claim lives in Behavior instead, where the keyboard path is replayed step by step.

Focus + keyboard behaviour: Owned by @base-ui/react/tooltip — focus trapping, dismissal and typeahead come from the headless primitive, not from us.
Focus ring (WCAG 2.2 SC 2.4.13): Not focusable — no focus indicator required.
Reduced motion: No animation to gate.
ARIA in the source: role="tooltip"
aria-describedby

Examples

2 more states from the same story file.

keyboard flowprimitives-tooltip--keyboard-flow ↗

reduced motionprimitives-tooltip--reduced-motion ↗

R-rule compliance

Every primitive in @interlace/ui models to the portable 26-rule floor enforced by the componentApi ESLint preset. The cells below pin exactly where each rule applies in this file.

Rule	Concept	Where
R4	Extends Base UI part props	`React.ComponentProps<typeof BaseTooltip.*>`
R6	data-slot per part	tooltip / -provider / -trigger / -content
R7	cn + ...rest	`cn('bg-primary …', className)` + `{...props}` on the popup
R10	Composition seam	`Compose` for trigger+label; the parts for anything richer
R12	Reuse over wrap	Base UI owns timing, positioning and dismissal
R14	Declares min viewport	`data-min-viewport` on the popup + exported const
R19	Tokens only	`bg-primary`, `text-primary-foreground`, `fill-primary`
R25	Client component	Required — `React.useId` + Base UI client hooks
R26	A11y this file adds	`id` + `role="tooltip"` on the popup, `aria-describedby` on the trigger

Minimum viewport

This primitive declares MIN_VIEWPORT = 320 CSS px (DESIGN_PRINCIPLES #14). When mounted in a container narrower than this, the preflight contract draws a dev-mode outline so the regression is visible during local development.

Opt-in to the dev-mode warning

<body data-interlace-dev>...</body>

Add the data-interlace-dev attribute to the body in development builds only — preflight then outlines any primitive whose container is below its declared data-min-viewport.

Dependencies

Base UI primitive: @base-ui/react/tooltip
Lucide icons: none
NPM dependencies: @base-ui/react
Registry dependencies: @interlace/theme
@interlace/cn

Source

The full implementation — components/ui/tooltip.tsx once installed.

232 lines · TypeScript

github ↗

'use client';

import * as React from 'react';

// @interlace/tooltip v1.4.0 — Interlace design system.
// Docs, props and live preview: https://ds.interlace.tools/c/tooltip
// What changed since: https://ds.interlace.tools/c/tooltip#history
// Generated banner — keep it, the upgrade diff reads this version.

/**
 * @interlace/ui — Tooltip
 *
 * A short label that appears beside its trigger on hover or on keyboard focus.
 * Wraps @base-ui/react/tooltip and adds the one thing Base UI 1.6 does not
 * emit: the `role="tooltip"` / `aria-describedby` pair.
 *
 * Base UI owns the open/close timing, the positioning and Escape-to-dismiss.
 *
 * That wiring is the reason this file is more than a class list. Without it a
 * tooltip is, to a screen reader, simply not there: the trigger announces its

…212 more lines…

Registry JSON

The raw registry record — what the shadcn CLI fetches.

/r/tooltip.json