Tooltip

A popup that appears when an element is hovered or focused, showing a hint for sighted users.

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

export default function Particle() {
  return (
    <Tooltip>
      <TooltipTrigger render={<Button variant="outline" />}>
        Hover me
      </TooltipTrigger>
      <TooltipPopup>Helpful hint</TooltipPopup>
    </Tooltip>
  );
}

Installation


pnpm dlx shadcn@latest add @coss/tooltip

Usage

import {
  Tooltip,
  TooltipCreateHandle,
  TooltipPopup,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/tooltip"

<Tooltip>
  <TooltipTrigger render={<Button variant="outline" />}>
    Hover me
  </TooltipTrigger>
  <TooltipPopup>Helpful hint</TooltipPopup>
</Tooltip>

API Reference

Root component. Alias for Tooltip.Root from Base UI.

TooltipTrigger

Trigger element that shows the tooltip on hover/focus. Alias for Tooltip.Trigger from Base UI.

TooltipPopup

Popup container that displays the tooltip content. Also exported as TooltipContent.

Prop	Type	Default	Description
`side`	`"top" \| "bottom" \| "left" \| "right"`	`"top"`	Side of the trigger to position the tooltip
`align`	`"start" \| "center" \| "end"`	`"center"`	Alignment relative to the trigger
`sideOffset`	`number`	`4`	Distance from the trigger in pixels

TooltipProvider

Provider for grouping tooltips. Alias for Tooltip.Provider from Base UI.

TooltipCreateHandle

Creates a handle for detached tooltip triggers. Returns a handle object to attach to multiple triggers for animated transitions.

To group multiple tooltips so they appear instantly after the first one is opened, wrap them in TooltipProvider. The grouping logic ensures that once a tooltip becomes visible, the adjacent tooltips will be shown instantly.

import { BoldIcon, ItalicIcon, UnderlineIcon } from "lucide-react";

import { Toggle, ToggleGroup } from "@/components/ui/toggle-group";
import {
  Tooltip,
  TooltipPopup,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/tooltip";

export default function Particle() {
  return (
    <TooltipProvider>
      <ToggleGroup defaultValue={["bold"]} multiple>
        <Tooltip>
          <TooltipTrigger
            render={<Toggle aria-label="Toggle bold" value="bold" />}
          >
            <BoldIcon />
          </TooltipTrigger>
          <TooltipPopup>Bold</TooltipPopup>
        </Tooltip>
        <Tooltip>
          <TooltipTrigger
            render={<Toggle aria-label="Toggle italic" value="italic" />}
          >
            <ItalicIcon />
          </TooltipTrigger>
          <TooltipPopup>Italic</TooltipPopup>
        </Tooltip>
        <Tooltip>
          <TooltipTrigger
            render={<Toggle aria-label="Toggle underline" value="underline" />}
          >
            <UnderlineIcon />
          </TooltipTrigger>
          <TooltipPopup>Underline</TooltipPopup>
        </Tooltip>
      </ToggleGroup>
    </TooltipProvider>
  );
}

Animated Tooltips

You can create animated tooltips that smoothly transition between different triggers using detached triggers. This pattern allows multiple triggers to share a single tooltip popup, with automatic animations for position, size, and content changes.

To create detached triggers:

Create a handle using TooltipCreateHandle
Attach the same handle to multiple TooltipTrigger components
Each trigger provides a payload prop containing the content component
Use a single Tooltip component with the handle to render the popup

"use client";

import { BoldIcon, ItalicIcon, UnderlineIcon } from "lucide-react";
import type { ComponentType } from "react";

import { Toggle, ToggleGroup } from "@/components/ui/toggle-group";
import {
  Tooltip,
  TooltipCreateHandle,
  TooltipPopup,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/tooltip";

const tooltipHandle = TooltipCreateHandle<ComponentType>();

const BoldContent = () => {
  return <span>Make text bold</span>;
};

const ItalicContent = () => {
  return <span>Apply italic formatting to text</span>;
};

const UnderlineContent = () => {
  return <span>Underline text</span>;
};

export default function Particle() {
  return (
    <TooltipProvider>
      <ToggleGroup defaultValue={["bold"]} multiple>
        <TooltipTrigger
          className="after:absolute after:left-full after:h-full after:w-1"
          handle={tooltipHandle}
          payload={BoldContent}
          render={<Toggle aria-label="Toggle bold" value="bold" />}
        >
          <BoldIcon aria-hidden="true" />
        </TooltipTrigger>
        <TooltipTrigger
          className="after:absolute after:left-full after:h-full after:w-1"
          handle={tooltipHandle}
          payload={ItalicContent}
          render={<Toggle aria-label="Toggle italic" value="italic" />}
        >
          <ItalicIcon aria-hidden="true" />
        </TooltipTrigger>
        <TooltipTrigger
          className="after:absolute after:left-full after:h-full after:w-1"
          handle={tooltipHandle}
          payload={UnderlineContent}
          render={<Toggle aria-label="Toggle underline" value="underline" />}
        >
          <UnderlineIcon aria-hidden="true" />
        </TooltipTrigger>
      </ToggleGroup>

      <Tooltip handle={tooltipHandle}>
        {({ payload: Payload }) => (
          <TooltipPopup>{Payload !== undefined && <Payload />}</TooltipPopup>
        )}
      </Tooltip>
    </TooltipProvider>
  );
}

On This Page

Installation Usage API Reference Tooltip TooltipTrigger TooltipPopup TooltipProvider TooltipCreateHandle Examples Grouped Tooltips Animated Tooltips