Tooltip

Summary

Tooltip is a compound component for lightweight floating descriptions attached to a trigger. It should only carry supplemental, non-essential information.

Imports

import {
  Tooltip,
  TooltipTrigger,
  TooltipContent,
  TooltipArrow,
  type TooltipProps,
} from '@vega-ui/react';

Exported Types

• TooltipProps
• TooltipTriggerProps
• TooltipContentProps
• TooltipArrowProps

Minimal Composition

import {
  Button,
  Text,
  Tooltip,
  TooltipArrow,
  TooltipContent,
  TooltipTrigger,
} from '@vega-ui/react';

export default function MinimalComposition() {
  return (
    <Tooltip>

Required Parts

• Tooltip: root state and context provider
• TooltipTrigger: trigger surface
• TooltipContent: visible tooltip content

Optional Parts

• TooltipArrow: visual arrow for the floating content

Composition Order

1. Tooltip
2. TooltipTrigger
3. TooltipContent
4. TooltipArrow

Variants

• Simple label tooltip versus richer descriptive tooltip
• Controlled open state when consumer logic needs it

Edge Cases

• Tooltips should not contain critical actions or required instructions.
• The tooltip shows on mouse or pen hover and on keyboard focus, never on a tap, so touch users need the same information elsewhere.
• Trigger content should remain understandable even without the tooltip.

Common Mistakes

• Hiding mandatory instructions in a tooltip.
• Using tooltip content as the only accessible name of a control.
• Putting interactive flows into tooltip content.

Examples

Basic

Basic: icon buttons with hints

Each icon button is named by its own aria-label; the tooltip only adds a hint and a keyboard shortcut and is linked to the button through aria-describedby while it is open. It shows on hover after delayOpen and at once on keyboard focus, never on a tap.

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

const actions = [

Controlled/Stateful

Controlled/Stateful: copy feedback

The tooltip is controlled, so the click handler can open it right after copying and change its text to Copied. Closing it through onChangeOpen resets the text for the next hover.

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

Controlled/Stateful: open state in your state

onChangeOpen reports the hover and focus requests, and open decides what is shown: the checkbox pins the hint open whatever the pointer does. The line below shows both values.

import { useState } from 'react';
import {
  Button,
  Checkbox,
  CheckboxCheckedIcon,
  CheckboxIndeterminateIcon,
  CheckboxIndicator,
  CheckboxInput,
  Text,
  Tooltip,
  TooltipArrow,
  TooltipContent,

Form/Integration

Form/Integration: optional field hint

The label stays visible and names the field; the info button next to it explains when the field is needed. A tooltip only suits optional context like this: required instructions and errors belong in visible text.

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

Layout/Overlay

Layout/Overlay: tooltip inside a dialog

The tooltip renders in the top layer after the dialog, so it shows above the modal and is not clipped by it. delayOpen={0} shows it at once, and the copy result changes its text.

import { useId, useState, type CSSProperties } from 'react';
import {
  Button,
  Dialog,
  DialogClose,
  DialogContent,
  DialogTrigger,
  Heading,
  Icon,
  IconButton,
  Label,
  Text,

Layout/Overlay: toolbar with a shared delay

Once one tooltip has shown, moving to a neighbour shows its tooltip at once, without waiting for delayOpen again.

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

const tools = [

Error

Error: reason for a failed sync

The error state itself is visible as a badge, and the warning button's aria-label says what it is about; the tooltip adds the reason. Reconnect fixes the row, and the hint disappears with the error.

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

Disabled

Disabled: reason for an unavailable action

A disabled button gets no hover or focus, so its tooltip never shows. aria-disabled keeps the button focusable and styled as disabled, the tooltip explains why, and the click handler returns early while it is unavailable. Check Billing verified to enable it.

import { useState } from 'react';
import {
  Button,
  Checkbox,
  CheckboxCheckedIcon,
  CheckboxIndeterminateIcon,
  CheckboxIndicator,
  CheckboxInput,
  Text,
  Tooltip,
  TooltipArrow,
  TooltipContent,

Edge

Edge: full text of a truncated name

Long file names are cut with an ellipsis, and the tooltip shows the full name on hover or keyboard focus of the link. The content gets a max-width and overflow-wrap: anywhere, so the long name wraps instead of running off the screen.

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

const files = [
  'Kestrel Robotics – Master services agreement – signed – final v7 (2).pdf',
  'Q3 board deck.pdf',
  'Brand guidelines 2026 – typography, colour, photography and tone of voice.fig',

Edge: metric definitions in a dense row

Small info buttons next to each metric keep the row compact while the definitions stay one hover or Tab away. Each button is named after its metric, so the buttons are distinguishable for screen readers.

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

const metrics = [

Anatomy

Overview

Tooltip owns delayed open behavior and floating-layer coordination for a short, non-essential description. It is intentionally narrow: trigger plus descriptive content, with an optional arrow for visual anchoring.

Required Parts

Tooltip

Required. Owns open timing and trigger-to-content coordination.

TooltipTrigger

Required. Defines the hover or keyboard focus target. A tap does not show the tooltip, and pressing the trigger hides it.

TooltipContent

Required. Renders the visible descriptive content.

Optional Parts

TooltipArrow

Optional visual arrow when the floating content should point back to the trigger more clearly.

Composition Order

1. Tooltip
2. TooltipTrigger
3. TooltipContent
4. TooltipArrow

Valid Composition Patterns

import {
  Button,
  Text,
  Tooltip,
  TooltipArrow,
  TooltipContent,
  TooltipTrigger,
} from '@vega-ui/react';

export default function MinimalComposition() {
  return (
    <Tooltip>

Invalid Composition Patterns

Interactive controls inside TooltipContent

Tooltip content should remain descriptive, not become a mini-popover.

Tooltip as the only label for a control

The trigger still needs its own accessible meaning without the tooltip.

Required instructions hidden only in the tooltip

If the content is essential for completing the task, use inline help or another overlay pattern instead.