headless-tooltip

A lightweight, customizable tooltip component for React with zero styling opinions. Built with accessibility in mind.

If you find Headless-Tooltip useful, please consider giving it a ⭐

Table of Contents

• Features
• Installation
• Basic Usage
• API Reference
• Accessibility
• Advanced Usage
• Animation Example
• Contributing

Features

• 🎨 Truly headless: No predefined styles, full control over tooltip appearance
• ♿ Accessible: Follows WAI-ARIA Tooltip Pattern
• 🧩 Flexible: Supports custom content, including HTML and React components
• 📱 Responsive: Automatically adapts to different screen sizes
• 🔄 Interactive mode: Optional interactive tooltips that remain visible when hovering
• 🏹 Customizable arrow: Optional arrow that can be styled and positioned
• 🌐 Placement options: 12 different placement positions for tooltip
• ⌨️ Keyboard friendly: Fully keyboard accessible with proper focus management
• ✨ Animation ready: Built-in support for CSS transitions and animations
• 🎭 State-based styling: CSS data attributes for different tooltip states

Installation

npm

npm install headless-tooltip

yarn

yarn add headless-tooltip

pnpm

pnpm add headless-tooltip

Basic Usage

import { Tooltip } from 'headless-tooltip';

function Example() {
  return (
    <Tooltip content="This is a tooltip message">
      <button>Hover me</button>
    </Tooltip>
  );
}

Styled Example

import { Tooltip } from 'headless-tooltip';

function StyledExample() {
  return (
    <Tooltip
      content={<span>This is a tooltip message</span>}
      placement="bottom"
      arrow={true}
      className="max-w-80 rounded-lg bg-gray-900 px-3 py-2 text-xs font-normal text-white"
      arrowClassName="bg-gray-900"
    >
      <button className="px-4 py-2 bg-blue-500 text-white rounded">
        Hover me
      </button>
    </Tooltip>
  );
}

API Reference

Props

| Prop | Type | Default | Description | | -------------------------- | ------------------------- | --------------- | ------------------------------------------------------------ | | children | React.ReactNode | (required) | The element that triggers the tooltip | | content | React.ReactNode | (required) | The content to be displayed in the tooltip | | placement | Placement | 'top' | Tooltip placement relative to the trigger element | | className | string | '' | Additional CSS classes to apply to the tooltip | | offset | number | 4 | Distance between tooltip and trigger element in pixels | | zIndex | number | undefined | Z-index value for the tooltip | | open | boolean | undefined | Control tooltip visibility (makes it a controlled component) | | openDelay | number | 300 | Delay in ms before showing the tooltip | | closeDelay | number | 200 | Delay in ms before hiding the tooltip | | disableInteractive | boolean | false | If true, tooltip will close when mouse leaves trigger | | onOpenChange | (open: boolean) => void | undefined | Callback when tooltip visibility changes | | portalContainer | HTMLElement | document.body | DOM element where tooltip portal will be rendered | | arrow | boolean | false | Whether to show an arrow pointing to the trigger | | arrowSize | number | 12 | Size of the arrow in pixels | | arrowClassName | string | undefined | Additional CSS classes to apply to the arrow | | transition | object | undefined | Configuration for tooltip enter/exit animations | | transition.enable | boolean | false | Whether to enable transition animations | | transition.enterDuration | number | 300 | Duration of the enter animation in milliseconds | | transition.exitDuration | number | 300 | Duration of the exit animation in milliseconds |

Placement Types

The placement prop accepts the following values:

• 'top'
• 'right'
• 'bottom'
• 'left'
• 'top-start'
• 'top-end'
• 'right-start'
• 'right-end'
• 'bottom-start'
• 'bottom-end'
• 'left-start'
• 'left-end'

Accessibility

This tooltip implementation follows the WAI-ARIA Tooltip Pattern to ensure accessibility compliance:

• Uses appropriate ARIA attributes (role="tooltip", aria-describedby)
• Supports keyboard navigation with proper focus management
• Dismissible with Escape key
• Works with screen readers
• Triggered by both hover and focus events

Browser Support

The component is compatible with all modern browsers:

• Chrome (and Chromium-based browsers)
• Firefox
• Safari
• Edge

Advanced Usage

Controlled Mode

import { useState } from 'react';
import { Tooltip } from 'headless-tooltip';

function ControlledExample() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <div>
      <button onClick={() => setIsOpen(!isOpen)}>Toggle Tooltip</button>

      <Tooltip
        content="This is a controlled tooltip"
        open={isOpen}
        onOpenChange={setIsOpen}
      >
        <button>Hover me too</button>
      </Tooltip>
    </div>
  );
}

Interactive Tooltip

import { Tooltip } from 'headless-tooltip';

function InteractiveExample() {
  return (
    <Tooltip
      content={
        <div>
          <p>Interactive tooltip with a button:</p>
          <button onClick={() => alert('Clicked!')}>Click me</button>
        </div>
      }
      disableInteractive={false}
    >
      <button>Hover for interactive tooltip</button>
    </Tooltip>
  );
}

Animation Example

import { Tooltip } from 'headless-tooltip';
import './animations.css';

function ZoomTooltip() {
  return (
    <Tooltip
      content="This tooltip zooms in and out!"
      className="tooltip-base zoom-in-out"
      transition={{
        enable: true,
        enterDuration: 400,
        exitDuration: 400,
      }}
    >
      <button>Hover for zoom animation</button>
    </Tooltip>
  );
}

/* animations.css */
.tooltip-base {
  background: #333;
  color: white;
  padding: 8px 12px;
  border-radius: 6px;
  font-size: 14px;
}

/* Zoom In/Out Animation */
.zoom-in-out[data-enter] {
  opacity: 0;
}

.zoom-in-out[data-entering] {
  opacity: 1;
  animation: zoomIn 400ms ease-out;
}

.zoom-in-out[data-exiting] {
  animation: zoomOut 400ms ease-in;
}

/* Keyframe Animations */
@keyframes zoomIn {
  0% {
    opacity: 0;
    transform: scale(0.3);
  }
  50% {
    opacity: 1;
  }
  100% {
    opacity: 1;
    transform: scale(1);
  }
}

@keyframes zoomOut {
  0% {
    opacity: 1;
    transform: scale(1);
  }
  50% {
    opacity: 1;
    transform: scale(0.3);
  }
  100% {
    opacity: 0;
    transform: scale(0.3);
  }
}

Contributing

Contributions are always welcome! Please feel free to submit a Pull Request.

License

MIT