Tooltip

Patterns

Icon Hint

When to use:

• An icon or compact trigger needs a short explanation.

Composition notes:

• Keep the trigger labeled independently.
• Keep the tooltip content shorter than a popover would need.

Trade-offs:

• Low-friction help.
• Weak fit for required instructions.

import {
  Icon,
  IconButton,
  Text,
  Tooltip,
  TooltipArrow,
  TooltipContent,
  TooltipTrigger,
} from '@vega-ui/react';
import { ArchiveIcon, ReplyIcon, Trash2Icon } from '@vega-ui/icons';

const actions = [

Field Helper

When to use:

• A field needs optional background context.

Composition notes:

• Keep the main label outside the tooltip.
• Use the tooltip only for optional explanation, not validation.

Trade-offs:

• Preserves clean forms.
• Easy to misuse for mandatory instructions.

import { useId, useState, type FormEvent } from 'react';
import {
  Button,
  Icon,
  IconButton,
  Label,
  Text,
  TextField,
  TextFieldInput,
  Tooltip,
  TooltipArrow,
  TooltipContent,

Dense Data Hint

When to use:

• Tables, metrics, or compact settings rows need a very short explanation.

Composition notes:

• Keep the copy descriptive and scannable.
• Prefer one sentence over multi-step instructions.

Trade-offs:

• Helps preserve dense layouts.
• Breaks down quickly if the explanation becomes workflow guidance.

import {
  Icon,
  IconButton,
  Text,
  Tooltip,
  TooltipArrow,
  TooltipContent,
  TooltipTrigger,
} from '@vega-ui/react';
import { InfoIcon } from '@vega-ui/icons';

const metrics = [

Comparison

Quick Decision Rule

Choose Tooltip when the content is brief, supplemental, and non-essential.

Tooltip vs Popover

Use Tooltip when:

• the content is just a hint or description

Use Popover when:

• the content is richer or interactive

Tooltip vs Dialog

Use Tooltip when:

• the user does not need a modal interaction

Use Dialog when:

• the content represents an actual task flow

Choose This Component When

• the content is a short hint
• the UI should stay non-modal and lightweight

Do Not Choose This Component When

• the content is required, interactive, or task-oriented

Troubleshooting

Tooltip Content Feels Too Important

Symptom

Users need the tooltip to complete the task correctly.

Likely Cause

Required instructions were placed in a supplemental component.

How To Verify

• Hide the tooltip and check whether the control is still understandable.

Fix

• Move essential instructions into visible UI.

Tooltip Inside Overlay Feels Unstable

Symptom

Tooltip timing or placement behaves oddly inside a dialog or other overlay.

Likely Cause

The tooltip was only tested in isolation.

How To Verify

• Render it inside the real overlay flow.

Fix

• Retest the exact stack and simplify where necessary.

Tooltip Should Probably Be A Popover

Symptom

The content keeps growing and starts to need actions, form controls, or multiple paragraphs.

Likely Cause

Tooltip is being used for a richer contextual overlay than it was designed for.

How To Verify

• Check whether the content includes controls or task instructions.
• Compare the experience with Popover.

Fix

• Switch to Popover for richer contextual content.
• Keep tooltip content short and purely supplemental.