Tooltip

** Last Built**: September 2, 2025 at 4:19 PM A flexible and accessible tooltip component that provides contextual information when hovering over, clicking on, or focusing elements.

Overview

The Tooltip component displays additional information or context for UI elements. It supports multiple trigger modes, positioning options, and can be fully customized to match your application's design system.

Features

• Multiple Trigger Modes: Hover, click, focus, or manual control
• Flexible Positioning: 12 different position options with automatic viewport detection
• Accessibility: Full ARIA support and keyboard navigation
• Customizable: Styling, animations, delays, and offsets
• Responsive: Automatically adjusts position on scroll and resize
• Performance: Efficient event handling and cleanup

Basic Usage

import { Tooltip } from '@react-superadmin/web';
function BasicExample() {
  return (
    <Tooltip content='This is a helpful tooltip'>
  <button className='px-4 py-2 bg-blue-500 text-white rounded'>
  Hover me
  </button>
    </Tooltip>
  );
}

Live Examples

With Different Positions

import { Tooltip } from '@react-superadmin/web';
function PositionExample() {
  return (
    <div className='flex flex-wrap gap-4 p-8'>
  <Tooltip content='Top tooltip' position='top'>
  <button className='px-3 py-2 bg-gray-200 rounded'>Top</button>
  </Tooltip>
  <Tooltip content='Bottom tooltip' position='bottom'>
  <button className='px-3 py-2 bg-gray-200 rounded'>Bottom</button>
  </Tooltip>
  <Tooltip content='Left tooltip' position='left'>
  <button className='px-3 py-2 bg-gray-200 rounded'>Left</button>
  </Tooltip>
  <Tooltip content='Right tooltip' position='right'>
  <button className='px-3 py-2 bg-gray-200 rounded'>Right</button>
  </Tooltip>
    </div>
  );
}

With Different Triggers

import { Tooltip } from '@react-superadmin/web';
function TriggerExample() {
  return (
    <div className='flex flex-wrap gap-4 p-8'>
  <Tooltip content='Hover to see this' trigger='hover'>
  <button className='px-3 py-2 bg-blue-500 text-white rounded'>
  Hover Trigger
  </button>
  </Tooltip>
  <Tooltip content='Click to toggle' trigger='click'>
  <button className='px-3 py-2 bg-green-500 text-white rounded'>
  Click Trigger
  </button>
  </Tooltip>
  <Tooltip content='Focus to see this' trigger='focus'>
  <button className='px-3 py-2 bg-purple-500 text-white rounded'>
  Focus Trigger
  </button>
  </Tooltip>
    </div>
  );
}

With Custom Styling

import { Tooltip } from '@react-superadmin/web';
function StylingExample() {
  return (
    <div className='p-8'>
  <Tooltip
  content='Custom styled tooltip'
  className='bg-gradient-to-r from-purple-500 to-pink-500 text-white border-0 shadow-xl'
  showArrow={false}
  maxWidth={200}
  >
  <button className='px-4 py-2 bg-indigo-600 text-white rounded-lg hover:bg-indigo-700'>
  Custom Styling
  </button>
  </Tooltip>
    </div>
  );
}

With Manual Control

import { Tooltip } from '@react-superadmin/web';
import { useState } from 'react';
function ManualControlExample() {
  const [isOpen, setIsOpen] = useState(false);
  return (
    <div className='p-8 space-y-4'>
  <div className='flex gap-2'>
  <button
  onClick={() => setIsOpen(true)}
  className='px-3 py-2 bg-green-500 text-white rounded'
  >
  Show Tooltip
  </button>
  <button
  onClick={() => setIsOpen(false)}
  className='px-3 py-2 bg-red-500 text-white rounded'
  >
  Hide Tooltip
  </button>
  </div>
  <Tooltip
  content='This tooltip is manually controlled'
  trigger='manual'
  isOpen={isOpen}
  onOpenChange={setIsOpen}
  >
  <button className='px-4 py-2 bg-blue-500 text-white rounded'>
  Target Element
  </button>
  </Tooltip>
    </div>
  );
}

With Rich Content

import { Tooltip } from '@react-superadmin/web';
function RichContentExample() {
  return (
    <div className='p-8'>
  <Tooltip
  content={
  <div className='space-y-2'>
  <h4 className='font-semibold text-white'>User Information</h4>
  <div className='text-sm'>
  <p>Name: John Doe</p>
  <p>Email: john@example.com</p>
  <p>Role: Administrator</p>
  </div>
  }
  maxWidth={250}
  className='bg-gray-800 text-white p-3'
  >
  <button className='px-4 py-2 bg-gray-600 text-white rounded'>
  User Details
  </button>
  </Tooltip>
    </div>
  );
}

API Reference

| Prop | Type | Default | Description | | --------------------------------------------------- | | content | React.ReactNode | - | Required. The content to display in the tooltip | | children | React.ReactElement | - | Required. The element that triggers the tooltip | | position | Position | "top" | Position of the tooltip relative to the trigger | | trigger | Trigger | "hover" | How the tooltip is triggered | | isOpen | boolean | - | Whether the tooltip is visible (for manual trigger) | | onOpenChange | (isOpen: boolean) => void | - | Callback when tooltip visibility changes | | delay | number | 200 | Delay before showing the tooltip (ms) | | showArrow | boolean | true | Whether to show an arrow pointing to the trigger | | maxWidth | number | 300 | Maximum width of the tooltip | | className | string | - | Custom CSS classes for the tooltip | | disabled | boolean | false | Whether the tooltip is disabled | | zIndex | number | 1000 | Z-index for the tooltip | | animate | boolean | true | Whether to animate the tooltip | | offset | number | 8 | Custom offset from the trigger |

Position Options

type Position =
  | 'top'
  | 'bottom'
  | 'left'
  | 'right'
  | 'top-start'
  | 'top-end'
  | 'bottom-start'
  | 'bottom-end'
  | 'left-start'
  | 'left-end'
  | 'right-start'
  | 'right-end';

Trigger Options

type Trigger = 'hover' | 'click' | 'focus' | 'manual';

Advanced Usage

Integration with Form Libraries

import { Tooltip } from '@react-superadmin/web';
import { useForm, Controller } from 'react-hook-form';
function FormIntegrationExample() {
  const { control, handleSubmit } = useForm();
  return (
    <form onSubmit={handleSubmit(console.log)} className='space-y-4'>
  <div className='flex items-center gap-2'>
  <label htmlFor='email' className='text-sm font-medium'>
  Email Address
  </label>
  <Tooltip content="We'll never share your email with anyone else">
  <span className='text-gray-400 cursor-help'>ℹ️</span>
  </Tooltip>
  </div>
  <Controller
  name='email'
  control={control}
  rules={{ required: true, email: true }}
  render={({ field, fieldState }) => (
  <div>
  <input
  {...field}
  type='email'
  className='w-full px-3 py-2 border rounded'
  placeholder='Enter your email'
  />
  {fieldState.error && (
  <Tooltip
  content={fieldState.error.message}
  position='bottom'
  className='bg-red-500 text-white'
  >
  <span className='text-red-500 text-sm'>️</span>
  </Tooltip>
  )}
  </div>
  )}
  />
    </form>
  );
}

Custom Positioning Logic

import { Tooltip } from '@react-superadmin/web';
import { useCallback, useState } from 'react';
function CustomPositioningExample() {
  const [position, setPosition] = useState<'top' | 'bottom'>('top');
  const handleScroll = useCallback(() => {
    const scrollTop = window.pageYOffset;
    const elementTop = 400; // Example threshold
    if (scrollTop > elementTop) {
  setPosition('top');
    } else {
  setPosition('bottom');
  }, []);
  useState(() => {
    window.addEventListener('scroll', handleScroll);
    return () => window.removeEventListener('scroll', handleScroll);
  });
  return (
    <div className='p-8'>
  <Tooltip
  content='This tooltip changes position based on scroll'
  position={position}
  className='bg-blue-600 text-white'
  >
  <button className='px-4 py-2 bg-blue-500 text-white rounded'>
  Dynamic Position
  </button>
  </Tooltip>
    </div>
  );
}

Best Practices

Accessibility

• Always provide meaningful content in tooltips
• Use tooltips to supplement, not replace, accessible labels
• Ensure tooltips don't interfere with keyboard navigation
• Consider using aria-describedby for screen readers

Performance

• Avoid complex calculations in tooltip content
• Use delay to prevent tooltips from appearing too quickly
• Consider disabling tooltips on mobile devices if not needed
• Clean up event listeners properly

User Experience

• Keep tooltip content concise and helpful
• Use appropriate positioning to avoid covering important content
• Consider the user's context when choosing trigger modes
• Provide visual feedback for interactive tooltips

Performance Considerations

The Tooltip component is optimized for performance with:

• Debounced positioning: Position calculations are optimized and cached
• Efficient event handling: Uses passive event listeners where possible
• Memory management: Proper cleanup of timeouts and event listeners
• Viewport detection: Smart positioning that avoids unnecessary calculations

Accessibility Features

• ARIA attributes: Proper role="tooltip" and aria-describedby
• Keyboard support: Focus management for focus-triggered tooltips
• Screen reader support: Content is properly announced
• Focus indicators: Visual feedback for keyboard navigation

Related Components

• Button - Common trigger element for tooltips
• Input - Form inputs that benefit from help text
• Label - Labels that can include tooltip help
• Modal - For more complex information display
• Dropdown - Alternative to click-triggered tooltips