@versini/ui-tooltip

An accessible React tooltip component built with TypeScript and TailwindCSS.

The Tooltip component provides contextual help and information with proper accessibility support, adaptive placement, delayed appearance, and theme awareness.

Table of Contents

• Features
• Installation
• Usage
• Examples
• API

Features

• 🧭 Smart Positioning: Uses Floating UI for collision-aware placement & arrow positioning
• ⏱️ Configurable Timing: Show delay (delay prop) and fade-in duration (animationDuration prop)
• ♿ Accessible: Proper role="tooltip", hover & focus behavior, optional disabling period
• 🎨 Theming: Supports light / dark / system / alt-system modes
• 🪶 Lightweight: Minimal DOM & style footprint; only renders when visible
• ⚡ Adaptive: Auto flips / shifts to remain within viewport

Installation

npm install @versini/ui-tooltip

Note: This component requires TailwindCSS and the @versini/ui-styles plugin for proper styling. See the installation documentation for complete setup instructions.

Usage

import { Tooltip } from "@versini/ui-tooltip";

function App() {
  return <Tooltip label="Helpful tip" trigger={<button>Hover me</button>} />;
}

Examples

Different Placements

<div className="flex flex-wrap gap-4">
  <Tooltip label="Top" placement="top" trigger={<button>Top</button>} />
  <Tooltip label="Right" placement="right" trigger={<button>Right</button>} />
  <Tooltip
    label="Bottom"
    placement="bottom"
    trigger={<button>Bottom</button>}
  />
  <Tooltip label="Left" placement="left" trigger={<button>Left</button>} />
</div>

Custom Animation Duration & Dark Mode

<Tooltip
  label="Smooth fade-in"
  animationDuration={1000}
  mode="dark"
  trigger={<button>Slow animation</button>}
/>

Delayed Appearance

<Tooltip
  label="Appears after 500ms"
  delay={500}
  trigger={<button>Hover and wait</button>}
/>;

{
  /* Combine delay and animation duration */
}
<Tooltip
  label="Wait 300ms, then fade in over 800ms"
  delay={300}
  animationDuration={800}
  trigger={<button>Delayed & animated</button>}
/>;

Styling the Tooltip & Arrow

<Tooltip
  label="Custom styled"
  tooltipClassName="bg-indigo-600 text-white text-sm"
  arrowClassName="bg-indigo-600"
  trigger={<button>Custom</button>}
/>

API

Tooltip Props

| Prop | Type | Default | Description | | ------------------- | --------------------------------------- | ------- | -------------------------------------------------- | ------------- | ---------- | ------------------------------ | | label | string | - | Text content of the tooltip. | | trigger | React.ReactNode | - | Element that the tooltip is anchored to. | | placement | Placement (from @floating-ui/react) | "top" | Preferred initial placement (auto flips / shifts). | | mode | "dark" | "light" | "system" | "alt-system" | "system" | Theme mode controlling colors. | | delay | number | 0 | Delay before showing tooltip (milliseconds). | | animationDuration | number | 300 | Duration of fade-in animation (milliseconds). | | className | string | - | Extra classes for outer wrapper. | | tooltipClassName | string | - | Extra classes for tooltip bubble. | | arrowClassName | string | - | Extra classes for tooltip arrow element. |

Tooltip appears on hover/focus, hides on leave/click, and temporarily disables after click to prevent flicker.