components / tooltip

Tooltip

Non-interactive floating hint surface with anchored containment and restrained motion.

Overview

What it is

This section explains the intent of the component before the implementation details.

  • Tooltip provides a small advisory hint for controls or compact UI where the label cannot carry all the context by itself.
  • It is intentionally non-interactive and lightweight.

Aliases

hint

Decision guide

How to choose it

Use these notes to decide quickly whether this is the right DK component for the job.

Decision guide

  • Choose Tooltip when the interaction should feel deliberate, documented, and reusable across product surfaces.
  • If the scenario is more specialized than the current Tooltip contract, prefer a simpler component or build a dedicated workflow on top of the lower-level DK primitives.

Do

  • Keep the Tooltip label, value, or status language direct enough to scan quickly.
  • Use the documented size and state recipes instead of inventing one-off variants in product code.

Do not

  • Do not hide the main purpose of Tooltip behind decorative copy or overloaded surface treatments.
  • Do not stretch Tooltip into a workflow it was not designed to handle just because the visuals are close.

Usage

When to use

Prefer these situations when choosing this component.

  • Use Tooltip for short hints, clarifications, or status details tied to one trigger.
  • Use it when the information is useful but not important enough to stay visible all the time.

Usage

When not to use

These patterns are better served by a different component or a simpler surface.

  • Do not use Tooltip for interactive content or multiple actions; use Popover.
  • Do not hide essential instructions behind a tooltip alone.

Anti-patterns

  • Using Tooltip as a generic layout container instead of a purpose-built interaction or content surface.
  • Forking the documented recipe in product code instead of extending the shared DK contract.

Migration notes

  • Migrate legacy tooltip usage by mapping existing variants and states onto the documented DK props before porting any custom styling.
  • Treat the docs examples as the reference contract for accessibility and event behavior during adoption.

Anatomy

Structural parts

The anatomy explains which pieces matter to the recipe and accessibility model.

hover/focus target

trigger

The control that reveals the tooltip.

advisory hint surface

surface

Compact non-interactive floating shell.

API

Public interface

The docs contract distinguishes props, DOM events, and slots so integration behavior is explicit.

Props

NameTypeDefaultDescription
contentstring—Tooltip text content.
openbooleanfalseControlled open state.
placement'top' | 'right' | 'bottom' | 'left''top'Preferred anchor placement.
delayMsnumber300Open delay before the tooltip appears.
disabledbooleanfalseDisables tooltip behavior.
onOpenChange(detail: { open: boolean }) => void—Callback fired when the tooltip opens or closes.
themeThemeContract—Overrides the compiled DK theme used to resolve tokens and recipes for this component.

Events

NamePayloadDescription
openchange{ open: boolean }Fires when an overlay-style component opens or closes through user interaction.

Slots

NameDescription
defaultTrigger content.

Recipes

Variants, sizes, and states

These notes summarize the intended recipe surface rather than exposing raw implementation detail first.

Variants

  • top/right/bottom/left: Placement chooses the preferred anchored direction.

Sizes

  • default: Tooltip uses one compact size tuned for hints.

States

  • closed: Tooltip hidden
  • open: Tooltip visible

Accessibility

Accessibility contract

This is the behavior the component promises to assistive tech and keyboard users today.

Semantics

  • Uses overlay semantics that reflect whether the surface is modal, contextual, or advisory.
  • Uses tooltip semantics for non-interactive advisory content.

Keyboard

  • Supports Escape dismissal when allowed.
  • Returns focus to the trigger after closing.
  • Focus should reveal the tooltip just as hover does.

Screen readers

  • Announces the overlay surface with its title, description, or tooltip content as available.

Caveats

  • Tooltips are not a substitute for persistent labels or instructions.

Checklist

  • Verify the visible label or title still produces a clear accessible name.
  • Verify focus remains obvious in every supported state and size.
  • Verify disabled, selected, and error states do not rely on color alone.

Implementation

Tokens and slot vars

This section shows the representative compiled slot variables that the runtime consumes for the selected design system.

root

--dk-motion-duration
120ms

surface

--dk-tooltip-surface-bg
#f2f5fb
--dk-tooltip-surface-fg
#16181c
--dk-tooltip-surface-border
#95989d
--dk-tooltip-surface-shadow
0 10px 15px rgba(0, 0, 0, 0.06), 0 4px 6px rgba(0, 0, 0, 0.04)
--dk-tooltip-surface-radius
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)
--dk-tooltip-surface-padding
0.75rem
--dk-tooltip-surface-max-width
240px
--dk-tooltip-offset
8px

content

--dk-tooltip-content-size
0.8125rem

Implementation notes

  • Tooltip is intentionally non-interactive. If the surface needs controls or longer prose, move up to Popover.

Implementation checklist

  • Use the public component API first and only drop to lower-level primitives when the component contract genuinely does not fit.
  • Keep theme overrides token-driven so proofs and recipes stay meaningful.
  • Verify the shipped examples and proof fixtures still represent the real product scenario you are implementing.

Examples

Copy-paste examples

Each example is intentionally practical, grouped by starter, common pattern, and edge-case coverage.

Examples
3
Depth
expanded

Starter

1 example

starter

Starter: compact hint

A short hint attached to one trigger.

Copy snippet

<Tooltip content="Quality checks passed."><button type="button">Hover the trigger</button></Tooltip>

Common patterns

1 example

common

Common: alternate placement

Use different placements when the surrounding layout calls for it.

Copy snippet

<Tooltip placement="right" content="Side hint"><button type="button">Hover the trigger</button></Tooltip>

Edge cases

1 example

edge

Edge: controlled visibility

Control tooltip visibility only when a workflow needs deterministic open state.

Copy snippet

<Tooltip open={isOpen} onOpenChange={(detail) => isOpen = detail.open} content="Checks passed."><button type="button">Hover the trigger</button></Tooltip>

Verification

Curated proof fixtures

Proofs stay visible in the docs so the system shows what it can guarantee, not just what it can render.

tooltip-default

pass

  • Contrast: 98.5 Lc
  • Surface: 240x72
  • Motion: 120ms