tooltip

A customizable and accessible tooltip component with smooth animations, global configuration, and flexible triggers.

Features

  • Floating UI powered positioning – Smart positioning with flip, shift, and offset middleware for optimal placement.
  • Origin-aware animations – Uses AnimVariants and AnimDialogVariants for smooth, direction-aware transitions.
  • Customizable delays – Control open/close delays with delayDuration and skipDelayDuration.
  • Global configuration – Manage tooltip behavior across your app using Tooltip.
  • Flexible triggers – Wrap any element (asChild) or use built-in styled Button variants.
  • Accessible by default – Implements proper ARIA attributes and keyboard navigation.
  • Portal rendering – Renders tooltips with FloatingPortal to avoid layout clipping.
  • Imperative animation control – Ensures animations play correctly using Mount lifecycle hooks.

Installation

npx @gentleduck/cli add tooltip
npx @gentleduck/cli add tooltip

Usage

import { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from '@/components/ui'
 
<TooltipProvider>
  <Tooltip delayDuration={500} skipDelayDuration={100}>
    <TooltipTrigger variant="outline">Hover</TooltipTrigger>
    <TooltipContent>Tooltip text</TooltipContent>
  </Tooltip>
</TooltipProvider>
import { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from '@/components/ui'
 
<TooltipProvider>
  <Tooltip delayDuration={500} skipDelayDuration={100}>
    <TooltipTrigger variant="outline">Hover</TooltipTrigger>
    <TooltipContent>Tooltip text</TooltipContent>
  </Tooltip>
</TooltipProvider>

Examples

Custom Trigger with asChild

<TooltipProvider>
  <Tooltip>
    <TooltipTrigger asChild>
      <span className="underline cursor-pointer">Hover me</span>
    </TooltipTrigger>
    <TooltipContent>Custom element trigger</TooltipContent>
  </Tooltip>
</TooltipProvider>
<TooltipProvider>
  <Tooltip>
    <TooltipTrigger asChild>
      <span className="underline cursor-pointer">Hover me</span>
    </TooltipTrigger>
    <TooltipContent>Custom element trigger</TooltipContent>
  </Tooltip>
</TooltipProvider>

Animated Tooltip

<Tooltip animation="default" overlay="fade">
  <TooltipTrigger>Hover</TooltipTrigger>
  <TooltipContent className="TooltipContent">Animated tooltip</TooltipContent>
</Tooltip>
<Tooltip animation="default" overlay="fade">
  <TooltipTrigger>Hover</TooltipTrigger>
  <TooltipContent className="TooltipContent">Animated tooltip</TooltipContent>
</Tooltip>
.TooltipContent {
  transform-origin: var(--duck-tooltip-transform-origin);
  animation: scaleIn 0.3s ease-out;
}
 
@keyframes scaleIn {
  from {
    opacity: 0;
    transform: scale(0.95);
  }
  to {
    opacity: 1;
    transform: scale(1);
  }
}
.TooltipContent {
  transform-origin: var(--duck-tooltip-transform-origin);
  animation: scaleIn 0.3s ease-out;
}
 
@keyframes scaleIn {
  from {
    opacity: 0;
    transform: scale(0.95);
  }
  to {
    opacity: 1;
    transform: scale(1);
  }
}

API Reference

Tooltip

  • skipDelayDuration (boolean, optional): If true, disables the delay before showing the tooltip.
  • delayDuration (number, optional): Milliseconds delay before showing the tooltip.
  • ...props (React.ComponentPropsWithRef<typeof TooltipPrimitive.Root>): Additional props forwarded to the underlying Tooltip root component.

TooltipTrigger

  • props (Omit<React.ComponentPropsWithRef<typeof TooltipPrimitive.Trigger>, 'size'>): Additional props forwarded to the tooltip trigger element.

TooltipContent

  • animation ('default' | 'nothing', optional, default: 'default'): Animation variant controlling how the tooltip appears.
  • overlay ('default' | 'nothing' | ..., optional, default: 'nothing'): Overlay variant controlling background overlay style (from AnimVariants).
  • ...props (React.ComponentPropsWithRef<typeof TooltipPrimitive.Content>): Additional props forwarded to the tooltip content container.

Behavior: Provides accessible tooltip functionality by wrapping the primitive tooltip components. Supports animation and overlay variants for styling the tooltip appearance. The tooltip content is absolutely positioned with maximum width and styled with a border, background, and padding to match popover UI standards. The trigger handles user interaction to show or hide the tooltip content.

Toggle GroupTypography