0
# Tooltip Directive
1

2
The `v-tooltip` directive provides simple tooltip functionality for Vue.js elements. It supports string content, positioning modifiers, configuration objects, and dynamic content including async loading.
3

4
## Capabilities
5

6
### Basic Tooltip Usage
7

8
Simple string-based tooltips with reactive content support.
9

10
```javascript { .api }
11
// String content
12
v-tooltip="'Static tooltip text'"
13

14
// Reactive property
15
v-tooltip="tooltipContent"
16

17
// Template expression
18
v-tooltip="'You have ' + count + ' new messages'"
19
```
20

21
**Usage Examples:**
22

23
```html
24
<template>
25
  <div>
26
    <!-- Static tooltip -->
27
    <button v-tooltip="'Click me!'">Button</button>
28
    
29
    <!-- Reactive tooltip -->
30
    <button v-tooltip="dynamicMessage">Dynamic Button</button>
31
    
32
    <!-- Expression tooltip -->
33
    <span v-tooltip="'Total: ' + itemCount + ' items'">Items</span>
34
  </div>
35
</template>
36

37
<script>
38
export default {
39
  data() {
40
    return {
41
      dynamicMessage: 'This updates reactively',
42
      itemCount: 42
43
    };
44
  }
45
};
46
</script>
47
```
48

49
### Positioning Modifiers
50

51
Control tooltip placement using directive modifiers.
52

53
```javascript { .api }
54
// Positioning modifiers
55
v-tooltip.top="content"
56
v-tooltip.top-start="content"
57
v-tooltip.top-end="content"
58
v-tooltip.right="content"
59
v-tooltip.right-start="content"
60
v-tooltip.right-end="content"
61
v-tooltip.bottom="content"
62
v-tooltip.bottom-start="content"
63
v-tooltip.bottom-end="content"
64
v-tooltip.left="content"
65
v-tooltip.left-start="content"
66
v-tooltip.left-end="content"
67
v-tooltip.auto="content"
68
v-tooltip.auto-start="content"
69
v-tooltip.auto-end="content"
70
```
71

72
**Usage Examples:**
73

74
```html
75
<template>
76
  <div>
77
    <!-- Position tooltip at bottom-start -->
78
    <button v-tooltip.bottom-start="'Tooltip positioned at bottom-start'">
79
      Bottom Start
80
    </button>
81
    
82
    <!-- Position tooltip on right -->
83
    <button v-tooltip.right="'Right positioned tooltip'">
84
      Right Position
85
    </button>
86
    
87
    <!-- Auto positioning -->
88
    <button v-tooltip.auto="'Auto positioned based on available space'">
89
      Auto Position
90
    </button>
91
  </div>
92
</template>
93
```
94

95
### Configuration Object
96

97
Advanced tooltip configuration using object notation.
98

99
```javascript { .api }
100
interface TooltipConfig {
101
  content: string | function | Promise;
102
  classes?: string | string[];
103
  targetClasses?: string | string[];
104
  html?: boolean;
105
  delay?: number | DelayConfig;
106
  placement?: string;
107
  trigger?: string;
108
  show?: boolean;
109
  offset?: number | string;
110
  container?: string | HTMLElement | false;
111
  boundariesElement?: string | HTMLElement;
112
  template?: string;
113
  arrowSelector?: string;
114
  innerSelector?: string;
115
  autoHide?: boolean;
116
  hideOnTargetClick?: boolean;
117
  loadingClass?: string;
118
  loadingContent?: string;
119
  popperOptions?: any;
120
}
121

122
// Object configuration
123
v-tooltip="configObject"
124
```
125

126
**Usage Examples:**
127

128
```html
129
<template>
130
  <div>
131
    <!-- Full configuration object -->
132
    <button v-tooltip="fullConfig">Configured Tooltip</button>
133
    
134
    <!-- Dynamic classes -->
135
    <button v-tooltip="classConfig">Custom Classes</button>
136
    
137
    <!-- Manual trigger -->
138
    <button v-tooltip="manualConfig">Manual Tooltip</button>
139
  </div>
140
</template>
141

142
<script>
143
export default {
144
  data() {
145
    return {
146
      fullConfig: {
147
        content: 'Advanced tooltip with custom settings',
148
        placement: 'bottom',
149
        delay: { show: 500, hide: 100 },
150
        html: false,
151
        classes: ['custom-tooltip', 'important'],
152
        offset: 10
153
      },
154
      classConfig: {
155
        content: 'Tooltip with dynamic classes',
156
        classes: this.isImportant ? ['urgent'] : ['normal']
157
      },
158
      manualConfig: {
159
        content: 'Manually controlled tooltip',
160
        trigger: 'manual',
161
        show: this.showTooltip
162
      },
163
      isImportant: true,
164
      showTooltip: false
165
    };
166
  },
167
  methods: {
168
    toggleTooltip() {
169
      this.showTooltip = !this.showTooltip;
170
    }
171
  }
172
};
173
</script>
174
```
175

176
### Async Content
177

178
Support for asynchronous content loading with loading states.
179

180
```javascript { .api }
181
interface AsyncTooltipConfig {
182
  content: () => Promise<string>;
183
  loadingContent?: string;
184
  loadingClass?: string;
185
}
186

187
// Async content function
188
v-tooltip="{ content: asyncContentFunction, loadingContent: 'Loading...' }"
189
```
190

191
**Usage Examples:**
192

193
```html
194
<template>
195
  <div>
196
    <!-- Async content with loading state -->
197
    <button v-tooltip="asyncConfig">Async Content</button>
198
    
199
    <!-- Function returning promise -->
200
    <button v-tooltip="promiseConfig">Promise Content</button>
201
  </div>
202
</template>
203

204
<script>
205
export default {
206
  data() {
207
    return {
208
      asyncConfig: {
209
        content: this.loadTooltipContent,
210
        loadingContent: 'Loading tooltip...',
211
        loadingClass: 'tooltip-loading'
212
      },
213
      promiseConfig: {
214
        content: () => this.fetchUserInfo(this.userId),
215
        loadingContent: 'Fetching user info...'
216
      },
217
      userId: 123
218
    };
219
  },
220
  methods: {
221
    async loadTooltipContent() {
222
      // Simulate API call
223
      await new Promise(resolve => setTimeout(resolve, 1000));
224
      return 'Content loaded from server';
225
    },
226
    
227
    async fetchUserInfo(userId) {
228
      const response = await fetch(`/api/users/${userId}`);
229
      const user = await response.json();
230
      return `User: ${user.name} (${user.email})`;
231
    }
232
  }
233
};
234
</script>
235
```
236

237
### Event Triggers
238

239
Control when tooltips appear and disappear.
240

241
```javascript { .api }
242
// Trigger options
243
interface TriggerConfig {
244
  trigger: 'hover' | 'focus' | 'click' | 'manual' | string;
245
  show?: boolean; // For manual trigger
246
}
247

248
// Available triggers
249
'hover'           // Mouse enter/leave
250
'focus'           // Element focus/blur
251
'click'           // Click events
252
'manual'          // Programmatic control
253
'hover focus'     // Multiple triggers (space-separated)
254
```
255

256
**Usage Examples:**
257

258
```html
259
<template>
260
  <div>
261
    <!-- Click trigger -->
262
    <button v-tooltip="{ content: 'Click to toggle', trigger: 'click' }">
263
      Click Tooltip
264
    </button>
265
    
266
    <!-- Focus trigger for inputs -->
267
    <input v-tooltip="{ content: 'Help text', trigger: 'focus' }" 
268
           placeholder="Focus me" />
269
    
270
    <!-- Manual control -->
271
    <button v-tooltip="manualTooltip" @click="toggleManualTooltip">
272
      Manual Control
273
    </button>
274
    
275
    <!-- Multiple triggers -->
276
    <button v-tooltip="{ content: 'Hover or focus', trigger: 'hover focus' }">
277
      Multiple Triggers
278
    </button>
279
  </div>
280
</template>
281

282
<script>
283
export default {
284
  data() {
285
    return {
286
      manualTooltip: {
287
        content: 'Manually controlled tooltip',
288
        trigger: 'manual',
289
        show: this.isTooltipVisible
290
      },
291
      isTooltipVisible: false
292
    };
293
  },
294
  methods: {
295
    toggleManualTooltip() {
296
      this.isTooltipVisible = !this.isTooltipVisible;
297
    }
298
  }
299
};
300
</script>
301
```
302

303
### Directive Functions
304

305
Low-level functions for manual tooltip management.
306

307
```javascript { .api }
308
/**
309
 * Create a tooltip on an element
310
 * @param el - Target HTML element
311
 * @param value - Tooltip configuration
312
 * @param modifiers - Directive modifiers object
313
 * @returns Tooltip instance
314
 */
315
function createTooltip(el: HTMLElement, value: any, modifiers?: object): Tooltip;
316

317
/**
318
 * Destroy tooltip on an element
319
 * @param el - Target HTML element
320
 */
321
function destroyTooltip(el: HTMLElement): void;
322

323
/**
324
 * Process tooltip options
325
 * @param options - Raw options object
326
 * @returns Processed options
327
 */
328
function getOptions(options: any): ProcessedOptions;
329

330
/**
331
 * Get tooltip placement from value and modifiers
332
 * @param value - Directive value
333
 * @param modifiers - Directive modifiers
334
 * @returns Placement string
335
 */
336
function getPlacement(value: any, modifiers: object): string;
337

338
/**
339
 * Extract content from directive value
340
 * @param value - Directive value
341
 * @returns Content string or false
342
 */
343
function getContent(value: any): string | false;
344
```
345

346
### HTML Content Security
347

348
Control HTML content rendering for security.
349

350
```javascript { .api }
351
// Global HTML setting
352
Vue.use(VTooltip, {
353
  defaultHtml: false, // Disable HTML by default for security
354
});
355

356
// Or set directly
357
VTooltip.options.defaultHtml = false;
358

359
// Per-tooltip HTML control
360
v-tooltip="{ content: '<strong>Bold</strong>', html: true }"
361
```
362

363
**Security Warning:**
364

365
```html
366
<!-- UNSAFE: User-generated content -->
367
<button v-tooltip="{ content: userGeneratedContent, html: true }">
368
  Dangerous
369
</button>
370

371
<!-- SAFE: Controlled content -->
372
<button v-tooltip="{ content: '<em>Emphasis</em>', html: true }">
373
  Safe HTML
374
</button>
375

376
<!-- SAFE: Text-only rendering -->
377
<button v-tooltip="{ content: userGeneratedContent, html: false }">
378
  Safe Text
379
</button>
380
```
381

382
## Directive Implementation
383

384
```javascript { .api }
385
interface VueDirective {
386
  bind(el: HTMLElement, binding: DirectiveBinding): void;
387
  update(el: HTMLElement, binding: DirectiveBinding): void;
388
  unbind(el: HTMLElement): void;
389
}
390

391
interface DirectiveBinding {
392
  value: any;
393
  oldValue: any;
394
  modifiers: { [key: string]: boolean };
395
}
396
```