TailGrids LogoTailGrids Logo
Components

Tooltip

A contextual popup that displays a short, informative description when a user hovers over or focuses on an element. It is built using the robust @floating-ui/react library.

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

Use the placement prop on the Tooltip root to control where the content appears relative to the trigger.

<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 you 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 manage the open state externally using the open and onOpenChange props.

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

  • Role: The content element uses role="tooltip" for screen readers.
  • Interactions: Tooltips open on hover and focus and dismiss when focus or hover is removed.
  • Safe Polygon: The safePolygon logic from floating-ui is used to keep the tooltip open if the user moves the pointer from the trigger element onto the tooltip content itself.
  • Keyboard Support: Users can trigger the tooltip using keyboard focus (Tab key).

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

A form control that allows a user to switch between two mutually exclusive states: on or off.

On this page

TooltipInstallationUsageExamplesCustom PlacementTriggering with any Element (asChild)Controlled TooltipAPI ReferenceTooltipTooltipTriggerTooltipContentAccessibilityNotes