> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Cognite Data Fusion (CDF) is an industrial DataOps platform. Prefer English docs unless the user asks for another locale.
> Follow /_llms/ index links recursively until you reach page URLs ending in .md. Fetch those Markdown twins instead of HTML.
> For REST APIs, default to calendar version 20230101 (stable). Use 20230101-beta or 20230101-alpha only if the user is on a preview API. Cite paths under /api-reference/concepts/<version>/ and the Cdf-Version header. Prefer the Python SDK (cognite-sdk) unless the user is in JavaScript/TypeScript.
> Start here by task: platform overview /cdf/index.md; data modeling /cdf/dm/index.md; data integration /cdf/integration/index.md; access /cdf/access/index.md; CDF Toolkit /cdf/deploy/cdf_toolkit/index.md; REST quickstart /dev/quickstart.md; Python SDK /dev/sdks/python/index.md; Atlas AI /cdf/atlas_ai/concepts/index.md; Flows apps /cdf/flows/index.md; Aura UI /cdf/aura/index.md; MCP and IDE setup /dev/guides/ide_ai_integration.md.
> For implementation work, also load /skill.md.

# Tooltip

> Tooltips are typically used for explaining icons, Buttons, links, or actions that might not be immediately obvious. Tooltips are presented inside a container that is displayed when a user hovers or focuses on an element.

<Badge color="blue">v1.0.0</Badge> | [View in Storybook](https://master--695bb4b1b8041ae09768950a.chromatic.com/?path=/docs/primitives-tooltip--docs)

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-tooltip--basic" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-tooltip--basic&viewMode=story&globals=theme:light" title="Tooltip basic story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

## When to use

* Clarification: Use Tooltips when there's a need to explain UI elements that may not be self-explanatory.
* Icons Buttons: When controls use icons without labels, or the label needs more clarity, a Tooltip can provide context or detail.
* Short instructions: Use Tooltips for brief instructions or details that would otherwise clutter the main interface if shown all the time.
* Non-critical info: Tooltips are best used for supplementary or optional information that does not require immediate attention.

## When to use something else

* Long copy: use inline text, side panels, or [Alert](/cdf/aura/primitives/alert)—not a [Tooltip](/cdf/aura/primitives/tooltip).
* Critical or frequently needed information: surface it in the layout or [Dialog](/cdf/aura/primitives/dialog), not only in a tooltip.
* Redundant text: don't mirror the visible [Button](/cdf/aura/primitives/button) label in the tooltip.

## Behavior

* On hover: The Tooltip should appear when the user hovers over or focuses on the trigger element and disappear when the hover/focus is removed.
* On focus (accessibility): Tooltips should also activate when the user focuses on an element using the keyboard (e.g., pressing Tab to navigate between buttons). This ensures that screen reader users and keyboard-only users can interact with the Tooltips.
* Delay: Introduce a slight delay before showing the Tooltip (e.g., 200ms-500ms).

## Often used with

Icon-only [Button](/cdf/aura/primitives/button), [Toggle group](/cdf/aura/primitives/toggle-group) segments, compact [Toolbar](/cdf/aura/primitives/toolbar) items—always with an accessible name on the trigger, not only the tooltip.

## Visual examples

The examples below are interactive and follow the doc site's theming: light mode when the docs site is in light mode, and dark mode when you switch the docs site to dark mode.

### With button variants

Attach tooltips to different button variants to show how supplementary text works across primary, secondary, and ghost triggers.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-tooltip--with-button-variants" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-tooltip--with-button-variants&viewMode=story&globals=theme:light" title="Tooltip with button variants story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Position top

Place tooltips above the trigger when space below is limited or when the control sits near the bottom of the viewport.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-tooltip--position-top" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-tooltip--position-top&viewMode=story&globals=theme:light" title="Tooltip position top story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Position right

Place tooltips to the right of the trigger when the control sits on the left edge of the layout or when vertical space is constrained.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-tooltip--position-right" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-tooltip--position-right&viewMode=story&globals=theme:light" title="Tooltip position right story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Position bottom

Use bottom placement as the default when there is room below the trigger—for example, icon buttons in a toolbar or action row.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-tooltip--position-bottom" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-tooltip--position-bottom&viewMode=story&globals=theme:light" title="Tooltip position bottom story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Position left

Place tooltips to the left of the trigger when the control sits on the right edge of the layout or when horizontal space is limited on the right.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-tooltip--position-left" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-tooltip--position-left&viewMode=story&globals=theme:light" title="Tooltip position left story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### All positions

Compare all four positions to choose placement that keeps the tooltip visible and does not obscure important content or fall outside the viewport.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-tooltip--all-positions" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-tooltip--all-positions&viewMode=story&globals=theme:light" title="Tooltip all positions story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### With icons

Use tooltips on icon-only controls to provide the accessible name and brief context—for example, toolbar actions or compact toggle buttons.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-tooltip--with-icons" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-tooltip--with-icons&viewMode=story&globals=theme:light" title="Tooltip with icons story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Long content

Keep tooltip copy short in production—this example shows how longer text wraps, but prefer one or two lines for supplementary information only.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-tooltip--long-content" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-tooltip--long-content&viewMode=story&globals=theme:light" title="Tooltip long content story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### With offset

Adjust offset when the default gap between trigger and tooltip is too tight or overlaps adjacent UI—for example, near card edges or dense control groups.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-tooltip--with-offset" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-tooltip--with-offset&viewMode=story&globals=theme:light" title="Tooltip with offset story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Keyboard interactions

Ensure tooltips appear on keyboard focus as well as hover so screen reader and keyboard-only users receive the same supplementary information.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-tooltip--keyboard-interactions" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-tooltip--keyboard-interactions&viewMode=story&globals=theme:light" title="Tooltip keyboard interactions story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Default open

Use default open sparingly—for example, in onboarding or demos—to draw attention to a control; in normal use, tooltips should appear only on hover or focus.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-tooltip--default-open" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-tooltip--default-open&viewMode=story&globals=theme:light" title="Tooltip default open story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Controlled state

Use a controlled tooltip when visibility must follow application logic—for example, guided tours, programmatic show and hide, or coordinated onboarding steps.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-tooltip--controlled-state" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-tooltip--controlled-state&viewMode=story&globals=theme:light" title="Tooltip controlled state story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### With delay

Add a short delay before showing tooltips to avoid flicker as users move the pointer across the interface—typically 200–500 ms for comfortable discovery.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-tooltip--with-delay" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-tooltip--with-delay&viewMode=story&globals=theme:light" title="Tooltip with delay story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>