0
# Low-Level API
1

2
v-tooltip exposes low-level APIs for advanced use cases, direct tooltip management, and integration with other libraries. These APIs provide direct access to the underlying Tooltip class and utility functions.
3

4
## Capabilities
5

6
### Tooltip Class
7

8
Direct access to the core Tooltip class for advanced tooltip management.
9

10
```javascript { .api }
11
/**
12
 * Core Tooltip class for creating and managing individual tooltips
13
 */
14
class Tooltip {
15
  /**
16
   * Create a new Tooltip instance
17
   * @param reference - The DOM node used as reference for the tooltip
18
   * @param options - Configuration options for the tooltip
19
   */
20
  constructor(reference: HTMLElement, options: TooltipOptions);
21
  
22
  /** Current tooltip state */
23
  _isOpen: boolean;
24
  
25
  /** Reference element */
26
  reference: HTMLElement;
27
  
28
  /** Tooltip configuration options */
29
  options: TooltipOptions;
30
  
31
  /** Popper.js instance for positioning */
32
  popperInstance: any;
33
  
34
  /** CSS classes to apply to tooltip */
35
  _classes: string | string[];
36
  
37
  /** Internal Vue element reference (when used with directive) */
38
  _vueEl?: HTMLElement;
39
}
40

41
interface TooltipOptions {
42
  /** Tooltip placement */
43
  placement?: string;
44
  
45
  /** Container element */
46
  container?: string | HTMLElement | false;
47
  
48
  /** Show/Hide delay */
49
  delay?: number | DelayConfig;
50
  
51
  /** Allow HTML content */
52
  html?: boolean;
53
  
54
  /** Tooltip content */
55
  title?: string | (() => string) | (() => Promise<string>);
56
  
57
  /** HTML template */
58
  template?: string;
59
  
60
  /** Trigger events */
61
  trigger?: string;
62
  
63
  /** Position offset */
64
  offset?: number | string;
65
  
66
  /** Boundaries element */
67
  boundariesElement?: string | HTMLElement;
68
  
69
  /** Popper.js options */
70
  popperOptions?: any;
71
  
72
  /** Arrow selector */
73
  arrowSelector?: string;
74
  
75
  /** Inner content selector */
76
  innerSelector?: string;
77
  
78
  /** Auto-hide on hover */
79
  autoHide?: boolean;
80
  
81
  /** Hide on target click */
82
  hideOnTargetClick?: boolean;
83
  
84
  /** Loading CSS class */
85
  loadingClass?: string;
86
  
87
  /** Loading content */
88
  loadingContent?: string;
89
  
90
  /** Accessibility aria ID */
91
  ariaId?: string;
92
}
93
```
94

95
**Usage Examples:**
96

97
```javascript
98
import { Tooltip } from 'v-tooltip';
99

100
// Create tooltip manually
101
const button = document.getElementById('my-button');
102
const tooltip = new Tooltip(button, {
103
  title: 'Manual tooltip',
104
  placement: 'top',
105
  trigger: 'hover',
106
  html: false
107
});
108

109
// Show/hide manually
110
tooltip.show();
111
setTimeout(() => tooltip.hide(), 2000);
112

113
// Clean up
114
tooltip.dispose();
115
```
116

117
### Tooltip Class Methods
118

119
Core methods for tooltip lifecycle management.
120

121
```javascript { .api }
122
interface TooltipMethods {
123
  /**
124
   * Show the tooltip
125
   * Reveals an element's tooltip. This is considered a "manual" triggering.
126
   * Tooltips with zero-length titles are never displayed.
127
   */
128
  show(): void;
129
  
130
  /**
131
   * Hide the tooltip
132
   * Hides an element's tooltip. This is considered a "manual" triggering.
133
   */
134
  hide(): void;
135
  
136
  /**
137
   * Toggle tooltip visibility
138
   * Toggles an element's tooltip. This is considered a "manual" triggering.
139
   */
140
  toggle(): void;
141
  
142
  /**
143
   * Dispose and destroy the tooltip
144
   * Hides and destroys an element's tooltip, cleaning up all resources.
145
   */
146
  dispose(): void;
147
  
148
  /**
149
   * Set tooltip CSS classes
150
   * @param classes - CSS classes to apply to tooltip
151
   */
152
  setClasses(classes: string | string[]): void;
153
  
154
  /**
155
   * Update tooltip content
156
   * @param content - New content for the tooltip
157
   */
158
  setContent(content: string | (() => string) | (() => Promise<string>)): void;
159
  
160
  /**
161
   * Update tooltip options
162
   * @param options - New options to merge with existing configuration
163
   */
164
  setOptions(options: Partial<TooltipOptions>): void;
165
}
166
```
167

168
**Usage Examples:**
169

170
```javascript
171
import { Tooltip } from 'v-tooltip';
172

173
const element = document.querySelector('.my-element');
174
const tooltip = new Tooltip(element, {
175
  title: 'Initial content',
176
  placement: 'top'
177
});
178

179
// Method usage
180
tooltip.show();                          // Show tooltip
181
tooltip.hide();                          // Hide tooltip
182
tooltip.toggle();                        // Toggle visibility
183

184
tooltip.setContent('New content');       // Update content
185
tooltip.setClasses(['custom', 'theme']); // Update styling
186

187
// Update configuration
188
tooltip.setOptions({
189
  placement: 'bottom',
190
  delay: { show: 200, hide: 100 },
191
  html: true
192
});
193

194
// Cleanup
195
tooltip.dispose();
196
```
197

198
### Direct Tooltip Functions
199

200
Utility functions for creating and managing tooltips without class instantiation.
201

202
```javascript { .api }
203
/**
204
 * Create a tooltip on an element using directive-style configuration
205
 * @param el - Target HTML element
206
 * @param value - Tooltip configuration (string, object, or function)
207
 * @param modifiers - Directive modifiers for placement
208
 * @returns Tooltip instance attached to element
209
 */
210
function createTooltip(
211
  el: HTMLElement, 
212
  value: string | TooltipConfig | (() => string), 
213
  modifiers?: DirectiveModifiers
214
): Tooltip;
215

216
/**
217
 * Destroy tooltip on an element
218
 * @param el - Target HTML element with attached tooltip
219
 */
220
function destroyTooltip(el: HTMLElement): void;
221

222
interface DirectiveModifiers {
223
  [placement: string]: boolean;
224
}
225

226
interface TooltipConfig {
227
  content: string | (() => string) | (() => Promise<string>);
228
  classes?: string | string[];
229
  targetClasses?: string | string[];
230
  html?: boolean;
231
  delay?: number | DelayConfig;
232
  placement?: string;
233
  trigger?: string;
234
  show?: boolean;
235
  offset?: number | string;
236
  container?: string | HTMLElement | false;
237
  boundariesElement?: string | HTMLElement;
238
  template?: string;
239
  arrowSelector?: string;
240
  innerSelector?: string;
241
  autoHide?: boolean;
242
  hideOnTargetClick?: boolean;
243
  loadingClass?: string;
244
  loadingContent?: string;
245
  popperOptions?: any;
246
}
247
```
248

249
**Usage Examples:**
250

251
```javascript
252
import { createTooltip, destroyTooltip } from 'v-tooltip';
253

254
const element = document.querySelector('.tooltip-target');
255

256
// Create simple tooltip
257
const tooltip = createTooltip(element, 'Simple tooltip');
258

259
// Create with modifiers (like v-tooltip.bottom)
260
const tooltipWithPlacement = createTooltip(
261
  element, 
262
  'Bottom tooltip', 
263
  { bottom: true }
264
);
265

266
// Create with full configuration
267
const configuredTooltip = createTooltip(element, {
268
  content: 'Advanced tooltip',
269
  placement: 'right',
270
  delay: { show: 300, hide: 100 },
271
  classes: ['custom-tooltip'],
272
  html: true
273
});
274

275
// Create with async content
276
const asyncTooltip = createTooltip(element, {
277
  content: async () => {
278
    const response = await fetch('/api/tooltip-content');
279
    return response.text();
280
  },
281
  loadingContent: 'Loading...',
282
  loadingClass: 'tooltip-loading'
283
});
284

285
// Cleanup
286
destroyTooltip(element);
287
```
288

289
### Utility Functions
290

291
Helper functions for processing tooltip configurations and content.
292

293
```javascript { .api }
294
/**
295
 * Process and normalize tooltip options
296
 * @param options - Raw options object
297
 * @returns Processed options with defaults applied
298
 */
299
function getOptions(options: any): ProcessedTooltipOptions;
300

301
/**
302
 * Determine tooltip placement from directive value and modifiers
303
 * @param value - Directive value object
304
 * @param modifiers - Directive modifiers object
305
 * @returns Placement string
306
 */
307
function getPlacement(value: any, modifiers: DirectiveModifiers): string;
308

309
/**
310
 * Extract content from various directive value formats
311
 * @param value - Directive value (string, object, or function)
312
 * @returns Content string or false if no content
313
 */
314
function getContent(value: any): string | false;
315

316
interface ProcessedTooltipOptions extends TooltipOptions {
317
  // All options with defaults applied
318
  placement: string;
319
  delay: number | DelayConfig;
320
  html: boolean;
321
  template: string;
322
  arrowSelector: string;
323
  innerSelector: string;
324
  trigger: string;
325
  offset: number | string;
326
  container: string | HTMLElement | false;
327
  autoHide: boolean;
328
  hideOnTargetClick: boolean;
329
  loadingClass: string;
330
  loadingContent: string;
331
  popperOptions: any;
332
}
333
```
334

335
**Note:** These functions are internal to the v-tooltip directive and are not exported. They are documented here for reference when extending or customizing the library.
336

337
**Usage Examples:**
338

339
```javascript
340
// These are internal functions - not directly importable
341
// Shown for reference only:
342

343
// Process options
344
const rawOptions = { content: 'Hello', delay: 200 };
345
const processedOptions = getOptions(rawOptions);
346
console.log(processedOptions.placement); // 'top' (default)
347

348
// Get placement from modifiers
349
const modifiers = { bottom: true, start: true };
350
const placement = getPlacement({}, modifiers);
351
console.log(placement); // 'bottom-start'
352

353
// Extract content
354
const stringContent = getContent('Hello World');
355
console.log(stringContent); // 'Hello World'
356

357
const objectContent = getContent({ content: 'Object content' });
358
console.log(objectContent); // 'Object content'
359

360
const noContent = getContent({});
361
console.log(noContent); // false
362
```
363

364
### DOM Utility Functions
365

366
Utility functions for DOM manipulation and class management.
367

368
```javascript { .api }
369
/**
370
 * Add CSS classes to an element (IE-compatible)
371
 * @param el - Target DOM element
372
 * @param classes - Space-separated class names or array
373
 */
374
function addClasses(el: HTMLElement, classes: string | string[]): void;
375

376
/**
377
 * Remove CSS classes from an element (IE-compatible)
378
 * @param el - Target DOM element
379
 * @param classes - Space-separated class names or array
380
 */
381
function removeClasses(el: HTMLElement, classes: string | string[]): void;
382

383
/**
384
 * Convert string to array format
385
 * @param value - String with space-separated values or array
386
 * @returns Array of individual values
387
 */
388
function convertToArray(value: string | string[]): string[];
389

390
/** Whether passive event listeners are supported */
391
const supportsPassive: boolean;
392
```
393

394
**Note:** These functions are internal utilities and are not exported. They are documented here for reference when extending or customizing the library.
395

396
**Usage Examples:**
397

398
```javascript
399
// These are internal utilities - not directly importable
400
// Shown for reference only:
401

402
const element = document.querySelector('.my-element');
403

404
// Class management
405
addClasses(element, 'tooltip-target active');
406
addClasses(element, ['theme-dark', 'size-large']);
407

408
removeClasses(element, 'active');
409
removeClasses(element, ['theme-dark', 'size-large']);
410

411
// Array conversion
412
const classArray = convertToArray('class1 class2 class3');
413
console.log(classArray); // ['class1', 'class2', 'class3']
414

415
// Feature detection
416
if (supportsPassive) {
417
  element.addEventListener('touchstart', handler, { passive: true });
418
} else {
419
  element.addEventListener('touchstart', handler, false);
420
}
421
```
422

423
### State Management
424

425
Access to global state and directive state.
426

427
```javascript { .api }
428
/**
429
 * Global state object
430
 */
431
interface TooltipState {
432
  /** Whether tooltips are globally enabled */
433
  enabled: boolean;
434
}
435

436
/**
437
 * Global state instance
438
 */
439
const state: TooltipState;
440

441
/**
442
 * Default options object (can be modified)
443
 */
444
const defaultOptions: GlobalVTooltipOptions;
445
```
446

447
**Note:** These are internal state objects and are not directly exported. They are documented here for reference.
448

449
**Usage Examples:**
450

451
```javascript
452
// Access global state through the plugin
453
VTooltip.enabled = window.innerWidth > 768;
454

455
// Access options through the plugin interface
456
console.log(VTooltip.options.defaultPlacement); // 'top'
457

458
// Modify defaults (affects all new tooltips)
459
VTooltip.options.defaultClass = 'custom-theme';
460
VTooltip.options.defaultDelay = 300;
461
```
462

463
### Advanced Integration
464

465
Low-level APIs for framework integration and custom implementations.
466

467
```javascript { .api }
468
/**
469
 * Vue directive object for manual registration
470
 */
471
const directive: VueDirective;
472

473
/**
474
 * Plugin object with install method
475
 */
476
const plugin: VuePlugin;
477

478
interface VueDirective {
479
  bind(el: HTMLElement, binding: DirectiveBinding): void;
480
  update(el: HTMLElement, binding: DirectiveBinding): void;
481
  unbind(el: HTMLElement): void;
482
  options: GlobalVTooltipOptions;
483
}
484

485
interface VuePlugin {
486
  install(Vue: any, options?: Partial<GlobalVTooltipOptions>): void;
487
  enabled: boolean;
488
  options: GlobalVTooltipOptions;
489
}
490

491
interface DirectiveBinding {
492
  value: any;
493
  oldValue: any;
494
  modifiers: { [key: string]: boolean };
495
}
496
```
497

498
**Usage Examples:**
499

500
```javascript
501
import { directive, plugin } from 'v-tooltip';
502

503
// Manual directive registration
504
Vue.directive('custom-tooltip', directive);
505

506
// Access directive options
507
console.log(directive.options.defaultClass);
508

509
// Plugin properties
510
console.log(plugin.enabled); // Global enabled state
511
plugin.enabled = false; // Disable all tooltips
512

513
// Custom directive implementation
514
const customDirective = {
515
  bind(el, binding) {
516
    // Custom bind logic
517
    directive.bind(el, binding);
518
  },
519
  update(el, binding) {
520
    // Custom update logic
521
    directive.update(el, binding);
522
  },
523
  unbind(el) {
524
    // Custom cleanup
525
    directive.unbind(el);
526
  }
527
};
528

529
Vue.directive('my-tooltip', customDirective);
530
```
531

532
### Browser Compatibility
533

534
Low-level browser compatibility utilities and polyfills.
535

536
```javascript { .api }
537
/**
538
 * Browser environment detection
539
 */
540
const isIOS: boolean;
541

542
/**
543
 * SVG element support
544
 */
545
const SVGAnimatedString: any;
546

547
/**
548
 * Element constructor (browser-safe)
549
 */
550
const Element: any;
551
```
552

553
**Note:** These are internal browser compatibility utilities and are not exported. They are documented here for reference.
554

555
**Usage Examples:**
556

557
```javascript
558
// These are internal utilities - not directly importable
559
// Shown for reference only:
560

561
// iOS-specific handling
562
if (isIOS) {
563
  // Special touch handling for iOS
564
  console.log('Running on iOS device');
565
}
566

567
// SVG element support
568
function isSVGElement(el) {
569
  return el instanceof SVGElement;
570
}
571

572
// Safe element type checking
573
function isElement(obj) {
574
  return obj instanceof Element;
575
}
576
```