Tooltip

v0.5.9

Documentation Under Review

The Tooltip component is built on top of Radix UI's Tooltip primitive. It provides a popup that displays supplementary information when a user hovers over or focuses on an element. The product variant supports custom neutral color theming.

Installation

npm install @pmi/catalyst-tooltip

Tailwind Config

The Tooltip package comes with a Tailwind preset that provides entrance animations for the component. Import this into your Tailwind configuration and add the preset to the presets array.

import type { Config } from 'tailwindcss';
import { default as tailwindTooltipPreset } from '@pmi/catalyst-tooltip/tailwind.config';

export default {
  content: ['./src/**/*.{ts,tsx,js,jsx}', './node_modules/@pmi/catalyst-*/**/*.{ts,tsx,js,jsx}'],
  theme: {},
  presets: [tailwindTooltipPreset],
  plugins: [],
} satisfies Config;

The preset includes:

• Animations: Smooth slide and fade animations from all four directions
• Keyframes: slideDownAndFade, slideUpAndFade, slideLeftAndFade, slideRightAndFade
• Timing: 400ms cubic-bezier easing for smooth motion

Usage

import {
  TooltipRoot,
  TooltipTrigger,
  TooltipContent,
  TooltipProvider,
  TooltipArrow,
} from '@pmi/catalyst-tooltip';

<TooltipProvider>
  <TooltipRoot>
    <TooltipTrigger>Hover</TooltipTrigger>
    <TooltipContent>
      Tooltip content
      <TooltipArrow />
    </TooltipContent>
  </TooltipRoot>
</TooltipProvider>

Important: Always wrap your tooltips with TooltipProvider to enable proper delay and open/close behavior.

Examples

Basic Tooltip

A simple tooltip with text content.

Positioning

Control tooltip placement using side and align props.

With Icon Trigger

Use icons as tooltip triggers for compact UI elements.

Complex Content

Tooltips can contain rich content including lists and formatted text.

With Call-to-Action Link

Tooltips can include interactive links for additional actions.

Custom Styling

Apply custom neutral color palette for product-specific designs.

API Reference

TooltipProvider

Wraps tooltip components to provide shared configuration.

TooltipRoot

The root component that manages tooltip state.

TooltipTrigger

The element that triggers the tooltip.

TooltipContent

The tooltip content that appears.

TooltipPortal

Renders the tooltip content in a portal (outside the DOM hierarchy).

TooltipArrow

An optional arrow element that points to the trigger.

Accessibility

The Tooltip component follows WAI-ARIA best practices:

• Keyboard Navigation: Tooltips appear on focus and hover, dismiss on blur and mouse leave
• Escape Key: Pressing Escape dismisses the tooltip
• ARIA Attributes: Automatically applies proper aria-describedby relationships
• Screen Readers: Content is announced when the trigger receives focus
• Icon Triggers: Always provide aria-label on icon-only triggers for screen reader users

Best Practices

1. Keep Content Concise: Tooltips should provide brief, supplementary information
2. Avoid Essential Information: Don't hide critical information in tooltips (mobile users may not see them)
3. Use for Clarification: Ideal for explaining icons, abbreviations, or providing context
4. Ensure Keyboard Access: All tooltip triggers must be keyboard accessible
5. Match Arrow Colors: Ensure arrow fill color matches content bg color
6. Respect Max Width: Use max-w-[--radix-tooltip-content-available-width] for long content
7. Custom Colors: When using custom neutral palette, maintain sufficient contrast ratios (WCAG AA)

Related Components

• Popover - Click-triggered overlay with richer content
• HoverCard - Extended tooltip with preview content
• DropdownMenu - Menu overlay with actions