Tooltip

Non-interactive hint shown on focus or pointer interaction.

Overview

  • Keep essential instructions in visible text. Do not put interactive content in a tooltip.

Aliases

hint

When to use

  • 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.

When not to use

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

Structural parts

pointer and focus target

trigger

The control that reveals the tooltip.

advisory hint surface

surface

Compact non-interactive floating shell.

Public interface

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—Runs when the tooltip opens or closes.
themeThemeContract—Sets the theme used to resolve component styles.
Events
NamePayloadDescription
openchange{ open: boolean }Fires when an overlay-style component opens or closes through user interaction.
Slots
NameDescription
defaultTrigger content.

Variants, sizes, and states

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

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 reveals the tooltip, as does holding the pointer over the trigger.

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 that the control has an accessible name.
  • Verify that keyboard focus is visible in every state and size.
  • Identify disabled, selected, and error states with text or symbols as well as color.

Tokens and CSS variables

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

  • Use Popover when the content needs controls.

Examples

Starter

Compact hint

A short hint attached to one trigger.

<Tooltip content="Quality checks passed."><button type="button">Show hint</button></Tooltip>

Common patterns

Alternate placement

Use different placements when the surrounding layout calls for it.

<Tooltip placement="right" content="Side hint"><button type="button">Show hint</button></Tooltip>

Edge cases

Controlled visibility

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

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

Mathematical fixtures

Calculated fixtures; browser evidence is not collected. Layout estimates use declared text behavior and maximum token values.

tooltip-default

pass

  • Evidence: mathematical
  • Coverage: complete (3 / 3 declared kinds evaluated)
  • Declared: contrast, anchoredSurface, motion
  • Evaluated: contrast, anchoredSurface, motion
  • Contrast: 98.5 Lc
  • Surface: 240 × 72 px
  • Motion: 120 ms