Tooltip.js: Reference Manual & API Guide

1. Installation & Setup

# Install via NPM
npm install @modracx/tooltip-js

# Or include via CDN script tag
<script src="https://cdn.jsdelivr.net/npm/@modracx/tooltip-js/dist/tooltip.min.js"></script>

2. Declarative HTML Setup

You can initialize tooltips declaratively without writing custom JavaScript by adding data attributes:

<button 
  type="button" 
  data-tooltip="Flush Redis Object Cache" 
  data-tooltip-placement="top"
  data-tooltip-delay="150">
  Clear Cache
</button>

3. JavaScript API Initialization

import { TooltipManager } from '@modracx/tooltip-js';

// Auto-bind all elements matching selector
const tooltips = new TooltipManager('[data-tooltip]', {
  placement: 'top',      // 'top' | 'bottom' | 'left' | 'right' | 'auto'
  offset: 8,             // Distance from target in pixels
  delay: [100, 50],      // [showDelayMs, hideDelayMs]
  theme: 'dark',         // 'dark' | 'light' | 'custom'
  arrow: true,           // Render SVG pointer arrow
  interactive: false     // Allow hovering inside tooltip content
});

4. Positioning & Auto-Flip Matrix

Desired Placement	Viewport Collision Behavior	Calculated Fallback
`top`	Insufficient space above element (< tooltip height + offset)	Auto-flips to `bottom`
`bottom`	Insufficient space below element	Auto-flips to `top`
`left`	Target element is against left screen margin	Auto-flips to `right`
`right`	Target element is against right screen margin	Auto-flips to `left`

5. Accessibility & Keyboard Focus

Tooltip.js automatically assigns unique ID attributes and updates aria-describedby or aria-labelledby on the host trigger element upon focus and hover, ensuring screen readers announce the tooltip content seamlessly without manual configuration.