Tooltip | HeroUI v3 (Previously NextUI) - The design system you don't have to build

Import

import { Tooltip } from '@heroui/react';

Usage

"use client";

import {Button, TooltipContent, TooltipRoot} from "@heroui/react";
import {Icon} from "@iconify/react";

export function TooltipBasic() {
  return (
    <div className="flex items-center gap-4">
      <TooltipRoot delay={0}>
        <Button variant="secondary">Hover me</Button>
        <TooltipContent>
          <p>This is a tooltip</p>
        </TooltipContent>
      </TooltipRoot>

      <TooltipRoot delay={0}>
        <Button isIconOnly variant="tertiary">
          <Icon icon="gravity-ui:circle-info" />
        </Button>
        <TooltipContent>
          <p>More information</p>
        </TooltipContent>
      </TooltipRoot>
    </div>
  );
}

Anatomy

Import the Tooltip component and access all parts using dot notation.

import { Tooltip } from '@heroui/react';

export default () => (
  <Tooltip.Root>
    <Tooltip.Trigger>
      <button>Hover for tooltip</button>
    </Tooltip.Trigger>
    <Tooltip.Content>
      <Tooltip.Arrow />
      Helpful information about this element
    </Tooltip.Content>
  </Tooltip.Root>
)

With Arrow

"use client";

import {Button, TooltipArrow, TooltipContent, TooltipRoot} from "@heroui/react";

export function TooltipWithArrow() {
  return (
    <div className="flex items-center gap-4">
      <TooltipRoot delay={0}>
        <Button variant="secondary">With Arrow</Button>
        <TooltipContent showArrow>
          <TooltipArrow />
          <p>Tooltip with arrow indicator</p>
        </TooltipContent>
      </TooltipRoot>

      <TooltipRoot delay={0}>
        <Button variant="primary">Custom Offset</Button>
        <TooltipContent showArrow offset={12}>
          <TooltipArrow />
          <p>Custom offset from trigger</p>
        </TooltipContent>
      </TooltipRoot>
    </div>
  );
}

Placement

Hover buttons

"use client";

import {Button, TooltipArrow, TooltipContent, TooltipRoot} from "@heroui/react";

export function TooltipPlacement() {
  return (
    <div className="grid grid-cols-3 gap-4">
      <div />
      <TooltipRoot delay={0}>
        <Button className="w-full" variant="tertiary">
          Top
        </Button>
        <TooltipContent showArrow placement="top">
          <TooltipArrow />
          <p>Top placement</p>
        </TooltipContent>
      </TooltipRoot>
      <div />

      <TooltipRoot delay={0}>
        <Button className="w-full" variant="tertiary">
          Left
        </Button>
        <TooltipContent showArrow placement="left">
          <TooltipArrow />
          <p>Left placement</p>
        </TooltipContent>
      </TooltipRoot>

      <div className="flex items-center justify-center">
        <span className="text-muted text-sm">Hover buttons</span>
      </div>

      <TooltipRoot delay={0}>
        <Button className="w-full" variant="tertiary">
          Right
        </Button>
        <TooltipContent showArrow placement="right">
          <TooltipArrow />
          <p>Right placement</p>
        </TooltipContent>
      </TooltipRoot>

      <div />
      <TooltipRoot delay={0}>
        <Button className="w-full" variant="tertiary">
          Bottom
        </Button>
        <TooltipContent showArrow placement="bottom">
          <TooltipArrow />
          <p>Bottom placement</p>
        </TooltipContent>
      </TooltipRoot>
      <div />
    </div>
  );
}

Custom Triggers

Active

"use client";

import {
  AvatarFallback,
  AvatarImage,
  AvatarRoot,
  Chip,
  TooltipArrow,
  TooltipContent,
  TooltipRoot,
  TooltipTrigger,
} from "@heroui/react";
import {Icon} from "@iconify/react";

export function TooltipCustomTrigger() {
  return (
    <div className="flex items-center gap-6">
      <TooltipRoot delay={0}>
        <TooltipTrigger aria-label="User avatar">
          <AvatarRoot>
            <AvatarImage
              alt="John Doe"
              src="https://img.heroui.chat/image/avatar?w=400&h=400&u=1"
            />
            <AvatarFallback>JD</AvatarFallback>
          </AvatarRoot>
        </TooltipTrigger>
        <TooltipContent showArrow>
          <TooltipArrow />
          <div className="flex flex-col gap-0 py-1">
            <p className="font-semibold">Jane Doe</p>
            <p className="text-muted text-xs">jane@example.com</p>
          </div>
        </TooltipContent>
      </TooltipRoot>

      <TooltipRoot delay={0}>
        <TooltipTrigger aria-label="Status chip">
          <Chip type="success">
            <Icon icon="gravity-ui:circle-check-fill" width={12} />
            Active
          </Chip>
        </TooltipTrigger>
        <TooltipContent className="flex items-center gap-1.5">
          <span className="relative flex size-2">
            <span className="bg-success absolute inline-flex h-full w-full animate-ping rounded-full opacity-75" />
            <span className="bg-success relative inline-flex size-2 rounded-full" />
          </span>
          <p>Jane is currently online</p>
        </TooltipContent>
      </TooltipRoot>

      <TooltipRoot delay={0}>
        <TooltipTrigger aria-label="Info icon">
          <div className="bg-accent-soft rounded-full p-2">
            <Icon className="text-accent" icon="gravity-ui:circle-question" />
          </div>
        </TooltipTrigger>
        <TooltipContent showArrow>
          <TooltipArrow />
          <div className="max-w-xs px-1 py-1.5">
            <p className="mb-1 font-semibold">Help Information</p>
            <p className="text-muted text-sm">
              This is a helpful tooltip with more detailed information about this feature.
            </p>
          </div>
        </TooltipContent>
      </TooltipRoot>
    </div>
  );
}

Styling

Passing Tailwind CSS classes

import { Tooltip, Button } from '@heroui/react';

function CustomTooltip() {
  return (
    <Tooltip.Root>
      <Tooltip.Trigger>
        <Button>Hover me</Button>
      </Tooltip.Trigger>
      <Tooltip.Content className="bg-accent text-accent-foreground">
        <p>Custom styled tooltip</p>
      </Tooltip.Content>
    </Tooltip.Root>
  );
}

Customizing the component classes

To customize the Tooltip component classes, you can use the @layer components directive.
Learn more.

@layer components {
  .tooltip {
    @apply rounded-xl shadow-lg;
  }

  .tooltip__trigger {
    @apply cursor-help;
  }
}

HeroUI follows the BEM methodology to ensure component variants and states are reusable and easy to customize.

CSS Classes

The Tooltip component uses these CSS classes (View source styles):

Base Classes

.tooltip - Base tooltip styles with animations
.tooltip__trigger - Trigger element styles

Interactive States

The component supports animation states:

Entering: [data-entering] - Applied during tooltip appearance
Exiting: [data-exiting] - Applied during tooltip disappearance
Placement: [data-placement="*"] - Applied based on tooltip position

API Reference

Tooltip.Root Props

Prop	Type	Default	Description
`children`	`React.ReactNode`	-	Trigger element and content
`delay`	`number`	`700`	Delay in milliseconds before showing tooltip
`closeDelay`	`number`	`0`	Delay in milliseconds before hiding tooltip
`trigger`	`"hover" \| "focus"`	`"hover"`	How the tooltip is triggered
`isDisabled`	`boolean`	`false`	Whether the tooltip is disabled

Tooltip.Content Props

Prop	Type	Default	Description
`children`	`React.ReactNode`	-	Content to display in the tooltip
`showArrow`	`boolean`	`false`	Whether to show the arrow indicator
`offset`	`number`	`3` (7 with arrow)	Distance from the trigger element
`placement`	`"top" \| "bottom" \| "left" \| "right"` (and variants)	`"top"`	Placement of the tooltip
`className`	`string`	-	Additional CSS classes

Tooltip.Trigger Props

Prop	Type	Default	Description
`children`	`React.ReactNode`	-	Element that triggers the tooltip
`className`	`string`	-	Additional CSS classes

Tooltip.Arrow Props

Prop	Type	Default	Description
`children`	`React.ReactNode`	-	Custom arrow element
`className`	`string`	-	Additional CSS classes

TooltipUpdated