react-js-tooltips

A powerful and flexible React library for adding customizable tooltips to your application.

🎯 Features

• Simple and intuitive API
• Highly customizable (colors, positions, animations)
• Responsive design with automatic positioning
• Smart pointer placement
• TypeScript support
• Lightweight and performant
• Multiple placement options
• Programmatic control via TooltipManager

📦 Installation

npm install react-js-tooltips

🚀 Quick Start

1. Add TooltipContainer to your app

Wrap your application with TooltipContainer at the root level:

import React from 'react';
import { TooltipContainer } from 'react-js-tooltips';

function App() {
  return (
    <div>
      <TooltipContainer />
      {/* Your app content */}
    </div>
  );
}

2. Basic Usage with TooltipWrapper

import { TooltipWrapper, Tooltip, TooltipTriggerType } from 'react-js-tooltips';

function MyComponent() {
  return (
      <TooltipWrapper
        renderOverlay={(tooltipProps: any) => {
          return (
            <Tooltip {...tooltipProps} width={240}>
              <div>
                <h3>Tooltip Title</h3>
                <p>This is a tooltip with some content.</p>
              </div>
            </Tooltip>
          );
        }}
      >
        <button>
          Click me!
        </button>
      </TooltipWrapper>
  );
}

3. Programmatic Control with TooltipManager

You can control tooltips programmatically using the TooltipManager:

import { useTooltipManager, TooltipTriggerType } from 'react-js-tooltips';

function Example() {
  const tooltipManager = useTooltipManager();

  const openTooltip = () => {
    // Activates a tooltip with the given uniqueId
    tooltipManager.activateAwaitingTooltip('my-tooltip');
  };

  return (
    <div>
      <button onClick={openTooltip}>Open Tooltip</button>
    </div>
  );
}

🔧 API Reference

TooltipWrapper Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | children | React.ReactNode | required | The element that triggers the tooltip | | renderOverlay | TRenderOverlayFunction | required | Function that returns the tooltip content (Tooltip component) | | triggerType | TooltipTriggerType | CLICK | How the tooltip is triggered (CLICK | CODE) | | uniqueId | string | undefined | Unique identifier for the tooltip (required when triggerType is CODE) | | blocker | boolean | false | If true, user must interact with tooltip before closing | | backdropColor | string | rgba(0,0,0,0.01) | Background color of the tooltip backdrop | | disableAnimation | boolean | false | Disable fade animations | | className | string | undefined | Custom CSS class for the wrapper element | | onClose | () => void | undefined | Callback when tooltip closes | | onOpen | () => void | undefined | Callback when tooltip opens | | onTargetClick | () => void | undefined | Callback when target element is clicked |

Tooltip Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | children | React.ReactNode | required | Tooltip content | | target | TTooltipTarget | required | Ref to the target element (provided by renderOverlay) | | preferredPlacement | TooltipPlacement | undefined | Preferred position for the tooltip | | width | number | undefined | Fixed width for the tooltip | | pointer | boolean | true | Show pointer arrow | | forcePointer | boolean | true | Force pointer to always be visible | | backgroundColor | string | #E8EEF7 | Background color of the tooltip | | borderRadius | number | 5 | Border radius of the tooltip | | containerMaxWidth | number | 400 | Maximum width of the tooltip container | | containerMaxHeight | number | 600 | Maximum height of the tooltip container |

TooltipPlacement Enum

Available placement options:

enum TooltipPlacement {
  TOP = 'top',
  LEFT = 'left',
  BOTTOM = 'bottom',
  RIGHT = 'right',
  
  TOP_LEFT = 'top-left',
  TOP_RIGHT = 'top-right',
  BOTTOM_LEFT = 'bottom-left',
  BOTTOM_RIGHT = 'bottom-right',
  
  LEFT_TOP = 'left-top',
  LEFT_BOTTOM = 'left-bottom',
  RIGHT_TOP = 'right-top',
  RIGHT_BOTTOM = 'right-bottom',
  
  NONE = 'none'
}

TooltipTriggerType Enum

enum TooltipTriggerType {
  CLICK = 'click',  // Triggered by clicking the element
  CODE = 'code'     // Triggered programmatically
}

TooltipManager Methods

| Method | Parameters | Description | |--------|------------|-------------| | add(tooltip) | tooltip: Omit<ITooltipInner, 'id'> | Add a new tooltip | | remove({id, uniqueId}) | {id: number, uniqueId?: string} | Remove a specific tooltip | | removeByUniqueId(uniqueId) | uniqueId: string | Remove tooltip by unique ID | | removeAll() | - | Remove all active tooltips | | reset() | - | Reset the tooltip manager (alias for removeAll) | | getActiveTooltips() | - | Get all active tooltip configurations | | getAwaitingTooltips() | - | Get all waiting tooltip configurations | | addAwaitingTooltip(tooltip) | tooltip: Omit<ITooltipInner, 'id'> | Add tooltip to waiting list (for CODE trigger) | | activateAwaitingTooltip(uniqueId) | uniqueId: string | Activate a waiting tooltip | | removeAwaitingTooltip(uniqueId) | uniqueId: string | Remove a waiting tooltip | | isAwaitingTooltipActive(uniqueId) | uniqueId: string | Check if a waiting tooltip is active |

🎨 Styling

The library includes default styles and animations. You can customize tooltips using:

• Props: Most styling props are available directly on the Tooltip component
• CSS Modules: Import and override styles from the library's CSS modules
• Inline styles: Pass custom styles through props

🌐 Demo

Check out the live demo to see all features in action:

• GitHub Repo: react-js-tooltips-demo
• Live Demo: egorlitsky.github.io/react-js-tooltips-demo

📖 Documentation

For more information, visit the GitHub repository.

🤝 Contributing

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

📄 License

MIT © Vladislav Egorlitskii