TailGrids LogoTailGrids Logo
Components

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.

All Placements Example

Installation

Usage

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 "@tailgrids/icons";

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

Examples

Custom Placement

Control where the tooltip appears using the placement prop on the root.

<Tooltip placement="right">
  <TooltipTrigger>
    <button>Hover me (Right)</button>
  </TooltipTrigger>
  <TooltipContent>I'm on the right!</TooltipContent>
</Tooltip>

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 to use any element (like an icon button, link, or custom component) as the trigger.

<Tooltip>
  <TooltipTrigger asChild>
    <a href="#" className="font-semibold text-blue-600 hover:underline">
      View Details
    </a>
  </TooltipTrigger>
  <TooltipContent>Click to see the full report.</TooltipContent>
</Tooltip>

Controlled Tooltip

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

const [isOpen, setIsOpen] = React.useState(true);

return (
  <Tooltip open={isOpen} onOpenChange={setIsOpen}>
    <TooltipTrigger>
      <button>Toggle Manually</button>
    </TooltipTrigger>
    <TooltipContent>
      I am always open until controlled otherwise.
    </TooltipContent>
  </Tooltip>
);

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>.
...propsReact.HTMLProps<HTMLElement>-Standard HTML props forwarded to the trigger element.

TooltipContent

The popup containing the descriptive content.

PropTypeDefaultDescription
childrenReact.ReactNode-The content to be displayed inside the tooltip.
...propsReact.HTMLProps<HTMLDivElement>-Standard HTML props forwarded to the content wrapper div.

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

License

TailGrids licensing information

On this page

TooltipInstallationUsageExamplesCustom PlacementTriggering with any Element (asChild)Controlled TooltipAPI ReferenceTooltipTooltipTriggerTooltipContentAccessibilityNotes