Skip to content
SkillCodex
Menu

Tooltip

Tooltip

A short, noninteractive hint that appears when a control receives pointer hover or keyboard focus.

Try the component
Context, sources and actions
Sources and revision
Updated
Version
v1.0.26 · r2
Sources
5 sources
Status
Published
Read the sources

You may have searched for: a little label when I hover the icontext that explains a button on focusa tiny hint beside the question mark

All phrasings
Save and share

Recognize

Small contextual surfaces

Try it

Do you need a short explanation, interactive contextual content, or an action list?

Tooltip

Shared trial context

A project workspace must reveal brief help, supporting details, or a short action list from a compact control without leaving the current task.

Tooltip

Mission

Tooltip

Reveal the icon's name with pointer and keyboard, then dismiss it with Escape.

Export report

report-july.pdf

Visible touch label: Export report

Live result

The hint is hidden. Focus can remain on Export report.

Step 1 of 3

Try

Try the component. Your live result appears just above. Move on at your own pace.

Behavior and edge case
What to observe
The hint appears beside the focused export button and leaves the button operable.
Edge case
On touch, the icon still has a visible accessible label path and no information depends only on hover.

What this example shows

Choose Tooltip only when the content is brief and contains no interactive element; use Popover for controls or richer content.

Use the Pack — Tooltip

Which fits your need?

Tooltip

Explaining an unfamiliar icon

Popover

Showing a compact explanation with a link

Which component will you use here?
Read the full PackVerify the result
Difference and sources

Choose Tooltip only when the content is brief and contains no interactive element; use Popover for controls or richer content.

Read the sources

    Parts of the specimen

    Select a numbered marker on the schematic, or use the list below, to see its role. The schematic shows the concept's representative state.

    Trigger

    The control that opens or reveals the surface.

    Position in the atlas

    Relationship map

    Locate the chapter, neighboring concepts, and the next useful decision.

    • Chapter

      Small contextual surfaces

      Tooltip belongs to this comparison group.

    • Do not confuse

      Popover

      Choose Tooltip if a few words clarify an unfamiliar icon and losing them on mobile is acceptable. Choose Popover if the content includes a link, a control, or more than a sentence or two.

      Compare this pair
    • Do not confuse

      Dropdown menu

      Choose Tooltip if a short text merely explains an icon or control and nothing can be clicked inside it. Choose Dropdown menu if the user must pick an action such as Edit, Duplicate, or Archive.

      Compare this pair
    • Next step

      Compare the concepts in the chapter before choosing an implementation.

      Open the chapter

    In your own words

    Understand

    What people describe

    Documented aliases: hint, hover tip, help bubble

    • a little label when I hover the icon
    • text that explains a button on focus
    • a tiny hint beside the question mark
    • show the icon meaning without clicking
    • help text that disappears when I leave
    • a name for an unlabeled toolbar icon

    Choose

    Use it when

    • Explaining an unfamiliar icon
    • Expanding a short truncated label

    Avoid it when

    • The information is essential to completing the task
    • The content needs links, buttons, or form controls

    Compare

    Compare similar concepts

    Unlike Tooltip, a Popover can contain interactive content; unlike Dropdown menu, it is not limited to a list of actions.

    Popover

    Use Dropdown menu for commands such as Edit or Archive, not for choosing a form value like Select and not for arbitrary rich content like Popover.

    Dropdown menu

    Platform equivalents

    The same interaction can have a different name or contract on each platform. Check the mapping before choosing an API.

    • HTML

      No direct primitive

      No direct primitive

      HTML has no robust tooltip element; the title attribute is not an equivalent keyboard and touch contract.

      Verified

    • WAI-ARIA APG

      Partial

      role="tooltip"

      WAI-ARIA APG 2026-09

      The work-in-progress pattern defines semantics and dismissal, but authors still implement timing, pointer continuity, and placement.

      Verified Official documentation

    • Radix UI

      Direct

      Tooltip.Root

      @radix-ui/react-tooltip 1.2.x

      The primitive coordinates trigger, delay, portal, content, Escape dismissal, hover, and focus.

      Verified Official documentation

    • shadcn/ui

      Direct

      Tooltip

      shadcn/ui docs 2026-09-03

      The Tooltip recipe wraps the Radix tooltip primitive and provider.

      Verified Official documentation

    • Material UI

      Direct

      Tooltip

      Material UI v9.4.0

      Tooltip anchors descriptive content to a child and supports focus, hover, touch, placement, and delay options.

      Verified Official documentation

    • SwiftUI

      Partial

      .help(_:)

      SwiftUI documentation 2026-09

      Help text maps to hover help on supported Apple platforms, but it is not a uniform iOS tooltip interaction.

      Verified Official documentation

    • Jetpack Compose

      Direct

      TooltipBox + PlainTooltip

      Android Developers 2026-08

      TooltipBox anchors a plain or rich tooltip and handles hover, long press, position, and state.

      Verified Official documentation

    • Flutter

      Direct

      Tooltip

      Flutter API docs 2026-09

      Tooltip provides the Material label surface and platform input triggers around its child.

      Verified Official documentation

    Impact profile

    Measured implementation costs and operating constraints for this SkillCodex specimen. A missing evaluation is never treated as free.

    Rendering
    Client
    Lazy weight
    22 kB-gzip
    Measured ·
    Environment
    macOS 26.6.2; Node 24.19.0; pnpm 10.34.5; Next.js 16.3.0 Turbopack; Chromium 140
    Method
    Sum of gzip -9 bytes for the lazy files of module 50349 in .next/server/app/(en)/term/[slug]/page/react-loadable-manifest.json after pnpm build:local at c9f1299.
    Low-end devices
    Fine
    Measured ·
    Environment
    macOS 26.6.2; Node 24.19.0; pnpm 10.34.5; Next.js 16.3.0 Turbopack; Chromium 140
    Method
    Loaded the 390 x 844 term route in isolated Chromium with 6x CPU throttling and reduced motion, then exercised the first state change; failures are recorded as non-blocking warnings.
    CPU / GPU
    Radix positions a small DOM overlay from pointer and focus events; no canvas or WebGL path is present.
    Measured ·
    Environment
    macOS 26.6.2; Node 24.19.0; pnpm 10.34.5; Next.js 16.3.0 Turbopack; Chromium 140
    Method
    Static source inspection of the target lab module plus an interaction on the isolated Chromium verification route; checked DOM/React work and absence of canvas or WebGL.
    Reduced motion
    The global reduced-motion contract collapses animation and transition durations; the same states and controls remain available.
    Measured ·
    Environment
    macOS 26.6.2; Node 24.19.0; pnpm 10.34.5; Next.js 16.3.0 Turbopack; Chromium 140
    Method
    Inspected src/app/globals.css prefers-reduced-motion rules and repeated the target interaction with reducedMotion=reduce in Chromium.
    Static fallback
    Without JavaScript, the term route stays on its localized Loading fallback; the profile and initial specimen are not revealed.
    Measured ·
    Environment
    macOS 26.6.2; Node 24.19.0; pnpm 10.34.5; Next.js 16.3.0 Turbopack; Chromium 140
    Method
    Loaded all ten prerendered routes from a local next start build in Chromium with JavaScript disabled; each HTTP 200 remained on the localized Loading fallback, so the profile and specimen were not revealed.
    Server rendering
    Hydrates
    Measured ·
    Environment
    macOS 26.6.2; Node 24.19.0; pnpm 10.34.5; Next.js 16.3.0 Turbopack; Chromium 140
    Method
    Inspected the prerendered route response, then loaded the same route with JavaScript enabled and exercised the hydrated client specimen.
    Maintenance
    Stable
    Dependencies

    Good fit

    • Brief supplemental labels or hints for controls that already work alone.

    Avoid when

    • Interactive content, required instructions or touch-only discovery.

    Verification checklist

    Try these actions in the lab, then check the same behaviours in your agent’s result. Adapt the example names to your interface.

    1. 1. Do this

      Hover over the icon, then reach that same icon with Tab.

      Expected result

      The same short explanation appears for pointer and keyboard use; focus stays on the icon.

    2. 2. Do this

      Press Escape while the explanation is visible, then continue with Tab.

      Expected result

      The explanation closes without activating the icon, and no button or link inside the tooltip enters the tab order.

    3. 3. Do this

      Use the same control on a touch screen without hovering.

      Expected result

      The control’s purpose remains understandable; essential instructions are available without the tooltip.

    Full contract
    1. 1The same hint is available on hover and keyboard focus
    2. 2The tooltip contains no interactive control
    3. 3Escape closes it without moving focus
    4. 4Touch users are not denied essential information

    Understand → Recognize → Choose → Compare

    Pack for your agent

    Pre-written instructions to paste into your agent. Copying executes nothing.

    Implement correctly

    Build Tooltip without breaking its behavior

    # Implement Tooltip in your agent

## Objective
Implement Tooltip for this verified behavior: A short, noninteractive hint that appears when a control receives pointer hover or keyboard focus.

## Prerequisites
- Inspect the repository, design system, and existing tests first.
- Preserve unrelated changes and keep the file scope bounded.
- Confirm that Tooltip matches the need before writing code.

## Required behavior
- Pointer hover or keyboard focus reveals the information after a short delay.
- Escape closes the tooltip without moving focus away from its trigger.

## States to cover
- Tooltip hidden
- Tooltip visible

## Accessibility
- ARIA role: tooltip
- The primary control or named region for Tooltip has a stable accessible name from visible text or an explicit programmatic label.
- Focus remains on the trigger; the tooltip itself never enters the tab order.
- It closes on Escape and after both focus and pointer leave the trigger and surface.
- The trigger references the tooltip description so assistive technology can read it without moving focus.
- Tab focuses the trigger
- Escape dismisses the visible tooltip

## When not to use
- The information is essential to completing the task
- The content needs links, buttons, or form controls

## Acceptance criteria
- The same hint is available on hover and keyboard focus
- The tooltip contains no interactive control
- Escape closes it without moving focus
- Touch users are not denied essential information

## Guardrails
- Show the proposed changes before any external action.
- Do not publish, send, delete, pay for, or change remote state without explicit authorization.
- Preserve unrelated changes and stop if the scope becomes ambiguous.

## Output format
- Outcome or verdict.
- Files or actions involved.
- Checks run and observable evidence.
- Remaining blockers or limitations.
    • @radix-ui/react-tooltip
    • Requires · Access to the repository, design system, and tests
    Why it works
    • The need is tied to canonical behavior before any technical choice.
    • States, accessibility, and non-goals prevent a merely visual implementation.
    • Acceptance criteria and the output format make verification observable.

    Try next

    Verify Tooltip on a real journey

    # Verify Tooltip after implementation

## Objective
Audit the Tooltip implementation against its behavior, states, and accessibility requirements without changing it automatically.

## Checks
- Replay the smallest representative journey.
- Check keyboard behavior, focus, accessible name, and announcements.
- Tie each gap to a specific acceptance criterion.

## Guardrails
- Show the proposed changes before any external action.
- Do not publish, send, delete, pay for, or change remote state without explicit authorization.
- Preserve unrelated changes and stop if the scope becomes ambiguous.

## Output format
- Outcome or verdict.
- Files or actions involved.
- Checks run and observable evidence.
- Remaining blockers or limitations.

    sha256:2e81d1acb696f4cb278197b5ae3be6f3efcc66b97288e6b4e3be68a4856f80cc

    Diagnose a problem

    Find and fix the Tooltip defect

    # Debug Tooltip in your agent

## Observed symptom
[DESCRIBE THE SYMPTOM HERE]

## Observable checks
- Reproduce the issue with the smallest relevant journey.
- Compare behavior with the documented states and transitions for Tooltip.
- Verify keyboard behavior, focus, accessible name, and announcements.

## Possible causes
- The chosen primitive does not match the expected behavior.
- A state, transition, or focus return is missing.
- A neighboring component captures an event or hides an accessible signal.

## Bounded corrections
- Fix the reproduced cause without recreating neighboring components.
- Preserve the public contract and add a focused regression test.
- Do not install dependencies or change remote state without authorization.

## Final verification
- The same hint is available on hover and keyboard focus
- The tooltip contains no interactive control
- Escape closes it without moving focus
- Touch users are not denied essential information

## Guardrails
- Show the proposed changes before any external action.
- Do not publish, send, delete, pay for, or change remote state without explicit authorization.
- Preserve unrelated changes and stop if the scope becomes ambiguous.

## Output format
- Outcome or verdict.
- Files or actions involved.
- Checks run and observable evidence.
- Remaining blockers or limitations.
    • @radix-ui/react-tooltip
    • Requires · Access to the repository, design system, and tests
    Why it works
    • The explicit symptom prevents starting from an assumed fix.
    • Checks separate behavior, accessibility, and neighboring interference.
    • The fix stays bounded and must produce regression evidence.

    Try next

    Lock in the Tooltip fix

    # Prevent the Tooltip regression

## Objective
Turn the reproduced cause into a focused regression test and compare Tooltip with neighboring concepts before widening the fix.

## Checks
- Prove that the test fails before the fix.
- Prove that it passes after the bounded fix.
- Verify that no neighboring component changed behavior.

## Guardrails
- Show the proposed changes before any external action.
- Do not publish, send, delete, pay for, or change remote state without explicit authorization.
- Preserve unrelated changes and stop if the scope becomes ambiguous.

## Output format
- Outcome or verdict.
- Files or actions involved.
- Checks run and observable evidence.
- Remaining blockers or limitations.

    sha256:c47c8247a4d9aa6c9bed7a41f14c5ae3bf9b6ae97e51eb1108a7ab22c4f884e7

    Full entry, saving and provenance

    Pre-written instruction by SkillCodex — your request is neither sent nor used to adapt this text; no content is generated, and copying executes nothing.

    Pack digest: sha256:2d6e46af171b871df9e5f16ddb3b8c561185fcfd693e3319fa3d70f85480bbe0

    In code

    TechnologyPrimitiveVersionCaveat
    @radix-ui/react-tooltip

    Tooltip.Root

    		@radix-ui/react-tooltip@1.2.12Radix supplies the primitive; content, timing, touch fallback, and final accessibility testing remain product responsibilities.

    Technical details

    Behaviors

    • Reveal on focus or hover

      Pointer hover or keyboard focus reveals the information after a short delay.

    • Dismiss tooltip with Escape

      Escape closes the tooltip without moving focus away from its trigger.

    States

    • Tooltip hidden

      Tooltip hidden

    • Tooltip visible

      Tooltip visible

    State transitions

    • Tooltip hidden → Tooltip visible

      Pointer hover or keyboard focus reaches the trigger.

    • Tooltip visible → Tooltip hidden

      Both pointer and focus leave the trigger and tooltip surface, or Escape dismisses the hint.

    Test scenarios

    Context
    A compact analytics toolbar includes an unfamiliar export icon.
    Mission
    Reveal the icon's name with pointer and keyboard, then dismiss it with Escape.
    Primary state
    The hint appears beside the focused export button and leaves the button operable.
    Edge case
    On touch, the icon still has a visible accessible label path and no information depends only on hover.

    Visual signals

    • Small floating text surface
    • Visually anchored to one control
    • No form controls inside

    Behavioral signals

    • Opens from hover and focus
    • Closes when hover or focus leaves
    • Never requires a click to read

    Accessibility

    Role
    tooltip
    Accessible name
    The primary control or named region for Tooltip has a stable accessible name from visible text or an explicit programmatic label.
    Focus
    Focus remains on the trigger; the tooltip itself never enters the tab order.
    Dismissal
    It closes on Escape and after both focus and pointer leave the trigger and surface.
    Scroll
    Page scrolling stays available. The floating surface remains anchored to its trigger or closes when that trigger leaves the viewport.
    Announcement
    The trigger references the tooltip description so assistive technology can read it without moving focus.
    Keyboard
    • Tab focuses the trigger
    • Escape dismisses the visible tooltip

    Bindings

    Open the HTML, ARIA, Radix, and shadcn matrix

    • Tooltip.Root

      implementationKind
      radix
      nativeElement
      Not applicable
      ariaPattern
      tooltip
      radixPrimitive
      Tooltip
      shadcnRecipe
      Tooltip
      runtimeDependency
      @radix-ui/react-tooltip@1.2.12
      packageName
      @radix-ui/react-tooltip
      exportName
      Tooltip.Root
      exactVersion
      1.2.12
      status
      verified
      sourceId
      source-ui-radix-tooltip
      deprecationStatus
      active
      replacement
      Not applicable
      validFrom
      Not applicable
      validUntil
      Not applicable

      Equivalence caveat: Radix supplies the primitive; content, timing, touch fallback, and final accessibility testing remain product responsibilities.

      Verify binding source

    Sources

    • WAI-ARIA APG: Tooltip Pattern
      sourceId
      source-ui-aria-tooltip
      kind
      documentation
      canonicalUrl
      https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/
      publisher
      W3C WAI
      sourceRevision
      http-last-modified:2026-07-09T07:07:36Z
      consultedAt
      2026-07-19
      license
      Not stated
      contentDigest
      sha256:28c008aec8fa19be8f285665c3947ac8c9f2604a07d4265c152ffa706cc92461
      status
      verified

      Claim covered: Tooltip: informative work-in-progress APG guidance for tooltip role, trigger description, focus retention, pointer continuity, and Escape dismissal.

    • Radix Primitives: Tooltip
      sourceId
      source-ui-radix-tooltip
      kind
      documentation
      canonicalUrl
      https://www.radix-ui.com/primitives/docs/components/tooltip
      publisher
      Radix Primitives
      sourceRevision
      http-etag:W/"1f572f9b054bd892ec8e5278b0f51784"
      consultedAt
      2026-07-19
      license
      Not stated
      contentDigest
      sha256:9903397fd5843b9540c50b93b3a2b676de6a51dafe5251383aa1761987d996c7
      status
      verified

      Claim covered: Tooltip: documented parts, state APIs, interaction behavior, and implementation limits for Radix Tooltip.

    • WAI-ARIA 1.2: Roles Model
      sourceId
      source-ui-wai-aria-roles
      kind
      standard
      canonicalUrl
      https://www.w3.org/TR/wai-aria-1.2/#roles
      publisher
      W3C WAI
      sourceRevision
      W3C-REC-wai-aria-1.2-20230606
      consultedAt
      2026-07-19
      license
      Not stated
      contentDigest
      sha256:c0fea16fc747779569ab754d2d25bca3e2b7e8a673b8ef5362aeb9ebc73a4849
      status
      verified

      Claim covered: Tooltip: normative ARIA role definitions and constraints for the stated accessible role.

    • WCAG 2.2: Focus Appearance
      sourceId
      source-ui-wcag-understanding-focus-appearance
      kind
      documentation
      canonicalUrl
      https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance.html
      publisher
      W3C WAI
      sourceRevision
      http-last-modified:2026-07-02T10:07:49Z
      consultedAt
      2026-07-19
      license
      Not stated
      contentDigest
      sha256:fdcf316a1f0e3cc758eda9618322d132862124ff0a3f3b1a3acbf20daf804ff0
      status
      verified

      Claim covered: Tooltip: informative WCAG guidance for evaluating visible keyboard focus appearance.

    • Radix Primitives: Popover
      sourceId
      source-ui-radix-popover
      kind
      documentation
      canonicalUrl
      https://www.radix-ui.com/primitives/docs/components/popover
      publisher
      Radix Primitives
      sourceRevision
      http-etag:W/"336d513dc97145e18c472483daaa33ec"
      consultedAt
      2026-07-19
      license
      Not stated
      contentDigest
      sha256:b1da962392e2eef1748cf3038190d63d3a3ac94b2267bfb5e38414c773620964
      status
      verified

      Claim covered: Tooltip: documented parts, state APIs, interaction behavior, and implementation limits for Radix Popover.