Tailgrids LogoTailgrids Logo

Tooltip

The Tooltip component displays short, contextual information when a user hovers over or focuses on an element. It is commonly used to explain icons, buttons, or UI elements without taking up permanent space.

This component is built with React and powered by @floating-ui/react for accurate positioning, collision handling, and accessible interactions.

Installation

The Tooltip component relies on the @floating-ui/react library.

Install the component using the Tailgrids CLI.

npx @tailgrids/cli add tooltip

Anatomy

The Tooltip component uses a compound component pattern and must contain a TooltipTrigger and TooltipContent.

import {
  Tooltip,
  TooltipTrigger,
  TooltipContent
} from "@/registry/core/tooltip";
import { Info } from "lucide-react";

export default function TooltipUsageExample() {
  return (
    <Tooltip>
      <TooltipTrigger asChild>
        <button className="text-primary-500">
          <Info className="size-5" />
        </button>
      </TooltipTrigger>
      <TooltipContent>Helpful context.</TooltipContent>
    </Tooltip>
  );
}

Examples

Placements

The tooltip can be positioned in four directions: top, bottom, left, and right using the placement prop.

All Placements Example

Triggering with any Element (asChild)

Use the asChild prop on TooltipTrigger to forward all required event handlers and ref to its single child element, allowing you to use any element (like an icon button, link, or custom component) as the trigger.

View Details

Controlled Tooltip

You can fully control the open state using open and onOpenChange.

The tooltip state is controlled by the parent.

State: false

API Reference

Tooltip

The root component that manages state and floating logic.

PropTypeDefaultDescription
initialOpenbooleanfalseThe initial open state for uncontrolled usage.
placementPlacement'top'The position of the tooltip content relative to the trigger.
openboolean-(Controlled) The open state. Overrides internal state.
onOpenChange(open: boolean) => void-(Controlled) Event handler when the open state changes.

TooltipTrigger

The element that activates the tooltip.

PropTypeDefaultDescription
asChildbooleanfalseWhen true, props are forwarded to the single child element instead of rendering a default <button>.
childrenReact.ReactNode-The element that triggers the tooltip. Defaults to a <button>.

TooltipContent

The popup containing the descriptive content.

PropTypeDefaultDescription
childrenReact.ReactNode-The content to be displayed inside the tooltip.

Accessibility

  • Uses role="tooltip" for correct screen reader interpretation
  • Opens on hover and keyboard focus
  • Closes automatically when focus or pointer leaves
  • Fully keyboard accessible using the Tab key
  • Uses safePolygon logic to prevent accidental closing when moving the cursor
  • Screen readers announce tooltip content when the trigger is focused

Notes

  • The component uses FloatingPortal to render the content outside the DOM flow of the trigger, preventing clipping issues, while still maintaining correct positioning.
  • The content has an integrated arrow which is correctly positioned and styled to point toward the trigger.
  • offset, flip, and shift middleware ensure the tooltip stays in view and avoids being cut off by the viewport edges.

Toggle

Previous Page

Icons

Free and open-source SVG icons for React projects. 240+ scalable vector icons built for React and Tailwind CSS.

On this page

TooltipInstallationAnatomyExamplesPlacementsTriggering with any Element (asChild)Controlled TooltipAPI ReferenceTooltipTooltipTriggerTooltipContentAccessibilityNotes