Tooltip

Examples

The same supplemental message is available from pointer hover and keyboard focus.

"use client";

import { HelpCircle } from "@phuctech/ui/icons";
import { IconButton } from "@phuctech/ui/components/icon-button";
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@phuctech/ui/components/tooltip";

export function Example() {
  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger render={<IconButton aria-label="What is a workspace?" variant="outline"><HelpCircle aria-hidden="true" /></IconButton>} />
        <TooltipContent> A workspace keeps a team&apos;s settings together.</TooltipContent>
      </Tooltip>
    </TooltipProvider>
  );
}

Use sm for a short hint, md (the default) when the message needs two short lines, and lg when it needs a little more room.

"use client";

import { Button } from "@phuctech/ui/components/button";
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@phuctech/ui/components/tooltip";

export function Example() {
  return (
    <TooltipProvider>
      <div className="flex flex-wrap items-center gap-4">
        <Tooltip>
          <TooltipTrigger render={<Button variant="outline">Small</Button>} />
          <TooltipContent size="sm">Concise supplemental hint.</TooltipContent>
        </Tooltip>
        <Tooltip>
          <TooltipTrigger render={<Button variant="outline">Medium</Button>} />
          <TooltipContent size="md">The default size fits a supplemental message that needs two short lines to stay readable.</TooltipContent>
        </Tooltip>
        <Tooltip>
          <TooltipTrigger render={<Button variant="outline">Large</Button>} />
          <TooltipContent size="lg">Use the largest size when the supplemental message needs a little more room to breathe.</TooltipContent>
        </Tooltip>
      </div>
    </TooltipProvider>
  );
}

Tooltips clarify an unfamiliar icon while the control keeps its own accessible name.

"use client";

import { HelpCircle } from "@phuctech/ui/icons";
import { IconButton } from "@phuctech/ui/components/icon-button";
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@phuctech/ui/components/tooltip";

export function Example() {
  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger render={<IconButton aria-label="Open automation help" variant="ghost"><HelpCircle aria-hidden="true" /></IconButton>} />
        <TooltipContent>Learn how automation runs are scheduled.</TooltipContent>
      </Tooltip>
    </TooltipProvider>
  );
}

Use side and align props when the trigger needs a different placement.

"use client";

import { HelpCircle } from "@phuctech/ui/icons";
import { IconButton } from "@phuctech/ui/components/icon-button";
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@phuctech/ui/components/tooltip";

export function Example() {
  return (
    <TooltipProvider>
      <div className="flex flex-wrap items-center justify-center gap-3">
        {(["top", "right", "bottom", "left"] as const).map((side) => (
          <Tooltip key={side}>
            <TooltipTrigger render={<IconButton aria-label={`${side} placement`} variant="outline"><HelpCircle aria-hidden="true" /></IconButton>} />
            <TooltipContent side={side} align="center">{side} placement</TooltipContent>
          </Tooltip>
        ))}
      </div>
    </TooltipProvider>
  );
}

Coordinate a related group of tooltips with shared delay and close timing.

"use client";

import { HelpCircle, Info } from "@phuctech/ui/icons";
import { IconButton } from "@phuctech/ui/components/icon-button";
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@phuctech/ui/components/tooltip";

export function Example() {
  return (
    <TooltipProvider delay={450} closeDelay={100}>
      <div className="flex items-center gap-2">
        <Tooltip>
          <TooltipTrigger render={<IconButton aria-label="Workspace help" variant="outline"><HelpCircle aria-hidden="true" /></IconButton>} />
          <TooltipContent>Shared provider timing applies to this group.</TooltipContent>
        </Tooltip>
        <Tooltip>
          <TooltipTrigger render={<IconButton aria-label="Workspace status" variant="outline"><Info aria-hidden="true" /></IconButton>} />
          <TooltipContent>Move between related triggers to reuse the provider.</TooltipContent>
        </Tooltip>
      </div>
    </TooltipProvider>
  );
}

An optional arrow and a keyboard shortcut can reinforce a short, supplemental message.

"use client";

import { HelpCircle } from "@phuctech/ui/icons";
import { IconButton } from "@phuctech/ui/components/icon-button";
import { Tooltip, TooltipArrow, TooltipContent, TooltipProvider, TooltipTrigger } from "@phuctech/ui/components/tooltip";

export function Example() {
  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger render={<IconButton aria-label="Keyboard shortcut" variant="outline"><HelpCircle aria-hidden="true" /></IconButton>} />
        <TooltipContent side="right" className="flex items-center gap-2">
          Save quickly <kbd className="rounded border border-background/30 px-1.5 py-0.5 text-[0.7rem]">⌘ S</kbd><TooltipArrow />
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  );
}

Feature state can control visibility when the surrounding interaction needs coordination.

"use client";

import { useState } from "react";

import { Button } from "@phuctech/ui/components/button";
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@phuctech/ui/components/tooltip";

export function Example() {
  const [open, setOpen] = useState(true);

  return (
    <TooltipProvider>
      <div className="grid justify-items-center gap-2">
        <Tooltip open={open} onOpenChange={setOpen}>
          <TooltipTrigger render={<Button variant="outline">Controlled help</Button>} />
          <TooltipContent>Visibility is coordinated by feature state.</TooltipContent>
        </Tooltip>
        <Button size="sm" variant="ghost" onClick={() => setOpen((value) => !value)}>
          {open ? "Hide" : "Show"} tooltip
        </Button>
      </div>
    </TooltipProvider>
  );
}

Keep supplemental text concise and within the popup max width.

"use client";

import { HelpCircle } from "@phuctech/ui/icons";
import { IconButton } from "@phuctech/ui/components/icon-button";
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@phuctech/ui/components/tooltip";

export function Example() {
  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger render={<IconButton aria-label="Show automation context" variant="outline"><HelpCircle aria-hidden="true" /></IconButton>} />
        <TooltipContent>Short context remains supplemental and wraps within a bounded width.</TooltipContent>
      </Tooltip>
    </TooltipProvider>
  );
}

When to use

Use Tooltip for a short clarification, a keyboard shortcut, or context for an icon-only control. Use visible helper text when the information affects task completion, and use Dialog or Popover for interactive content.

Usage

"use client";

import { HelpCircle } from "@phuctech/ui/icons";
import { IconButton } from "@phuctech/ui/components/icon-button";
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@phuctech/ui/components/tooltip";

export function Example() {
  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger render={<IconButton aria-label="What is a workspace?" variant="outline"><HelpCircle aria-hidden="true" /></IconButton>} />
        <TooltipContent> A workspace keeps a team&apos;s settings together.</TooltipContent>
      </Tooltip>
    </TooltipProvider>
  );
}

Wrap related tooltips in TooltipProvider. Compose the trigger with Button or IconButton through Base UI's render prop to avoid nested buttons. Use TooltipArrow only when the visual connection helps; it is decorative.

Behavior

Pointer hover opens after the provider/trigger delay; keyboard focus opens immediately enough to be discoverable.
Escape and leaving the trigger close the tooltip; the trigger remains the focus owner.
Tooltip content is portaled and positioned against the trigger so nearby overflow does not clip it.

API

Component API
Prop	Type	Default	Description	Constraints
`TooltipProvider`	`Base UI provider props`	`—`	Coordinates delay and pointer transitions for a group of tooltips.	Place it around related triggers.
`Tooltip`	`Root props`	`—`	Controls one tooltip relationship.	Use disabled when the context should not appear.
`TooltipTrigger`	`Trigger props`	`—`	Attaches the tooltip to a focusable element.	Keep the trigger accessible without the tooltip.
`TooltipContent`	`Popup props + side/align/sideOffset + size`	`side=top, sideOffset=8, size="md"`	Portaled supplemental text; size sm/md/lg sets max width and padding.	Keep it short and non-essential.
`TooltipArrow`	`arrow props`	`—`	Optional decorative connection to the trigger.	Do not rely on the arrow for meaning.

Tokens

Component tokens
Token	Role	Effective value	Usage
`--color-text-primary / --color-bg-page`	Tooltip contrast	`foreground on background`	Uses a high-contrast text surface for brief context.
`--radius-md`	Popup geometry	`shared medium radius`	Keeps supplemental surfaces compact.
`--motion-duration-fast`	Open/close timing	`120ms`	Tooltip motion is quick and respects reduced motion.

Accessibility

The trigger must have its own accessible name; tooltip text is supplementary.
Verify the tooltip opens from keyboard focus, not only a mouse hover.
Never put a required instruction, error, or interactive form only inside a tooltip.

Do and don’t

Explain an unfamiliar icon in one short sentence and keep the trigger usable without it.

Don’t

Use a tooltip for a paragraph, a required form label, or an action that needs a click.

IconButton is a common tooltip trigger for icon-only actions.
Dialog handles longer tasks and focus-managed content.

Examples

Hover and focus

Size and multiline

IconButton context

Supported positions

Provider timing

Arrow and shortcut

Controlled visibility

Short, bounded content

When to use

Usage

Behavior

API

Tokens

Accessibility

Do and don’t

Examples

When to use

Usage

Behavior

API

Tokens

Accessibility

Do and don’t

Related