0
# Global Configuration
1
2
v-tooltip provides comprehensive global configuration options for customizing default behavior, styling, and functionality across all tooltip and popover instances.
3
4
## Capabilities
5
6
### Plugin Installation Options
7
8
Configure v-tooltip globally during Vue plugin installation.
9
10
```javascript { .api }
11
/**
12
* Install v-tooltip plugin with global options
13
* @param Vue - Vue constructor
14
* @param options - Global configuration options
15
*/
16
function install(Vue: any, options?: Partial<GlobalVTooltipOptions>): void;
17
18
// Plugin installation with options
19
Vue.use(VTooltip, options);
20
```
21
22
**Usage Examples:**
23
24
```javascript
25
import Vue from 'vue';
26
import VTooltip from 'v-tooltip';
27
28
// Install with custom defaults
29
Vue.use(VTooltip, {
30
defaultPlacement: 'bottom',
31
defaultClass: 'my-tooltip-theme',
32
defaultHtml: false, // Disable HTML for security
33
defaultDelay: 200,
34
autoHide: false,
35
popover: {
36
defaultTrigger: 'hover',
37
defaultAutoHide: false
38
}
39
});
40
41
// Or install with minimal config
42
Vue.use(VTooltip, {
43
defaultClass: 'custom-tooltip'
44
});
45
```
46
47
### Plugin Interface
48
49
The main VTooltip export provides a complete plugin interface.
50
51
```javascript { .api }
52
interface VTooltipPlugin {
53
/** Install function for Vue.use() */
54
install(Vue: any, options?: Partial<GlobalVTooltipOptions>): void;
55
56
/** Global enable/disable state */
57
enabled: boolean;
58
59
/** Current global configuration options */
60
options: GlobalVTooltipOptions;
61
}
62
63
// Plugin exports
64
const VTooltip: VTooltipPlugin;
65
const VPopover: VueComponent;
66
const VClosePopover: DirectiveOptions;
67
```
68
69
**Usage Examples:**
70
71
```javascript
72
import VTooltip, { VPopover, VClosePopover } from 'v-tooltip';
73
74
// Plugin properties
75
console.log(VTooltip.enabled); // true
76
console.log(VTooltip.options.defaultClass); // 'vue-tooltip-theme'
77
78
// Enable/disable globally
79
VTooltip.enabled = window.innerWidth > 768;
80
81
// Install plugin
82
Vue.use(VTooltip, { defaultClass: 'custom' });
83
```
84
85
### Direct Options Configuration
86
87
Modify global options after plugin installation.
88
89
```javascript { .api }
90
// Direct options access
91
VTooltip.options: GlobalVTooltipOptions;
92
93
// Modify individual options
94
VTooltip.options.defaultClass = 'new-theme';
95
VTooltip.options.defaultPlacement = 'top';
96
VTooltip.options.popover.defaultTrigger = 'click';
97
```
98
99
**Usage Examples:**
100
101
```javascript
102
import VTooltip from 'v-tooltip';
103
104
// Change default theme
105
VTooltip.options.defaultClass = 'material-tooltip';
106
107
// Disable HTML content globally for security
108
VTooltip.options.defaultHtml = false;
109
110
// Set global delays
111
VTooltip.options.defaultDelay = { show: 300, hide: 100 };
112
113
// Configure popover defaults
114
VTooltip.options.popover.defaultPlacement = 'bottom-start';
115
VTooltip.options.popover.defaultAutoHide = true;
116
117
// Custom template
118
VTooltip.options.defaultTemplate = `
119
<div class="custom-tooltip" role="tooltip">
120
<div class="tooltip-arrow"></div>
121
<div class="tooltip-content"></div>
122
</div>
123
`;
124
```
125
126
### Global Enable/Disable
127
128
Control tooltip functionality globally based on conditions.
129
130
```javascript { .api }
131
// Global enable/disable property
132
VTooltip.enabled: boolean;
133
134
// Enable/disable based on conditions
135
VTooltip.enabled = condition;
136
```
137
138
**Usage Examples:**
139
140
```javascript
141
import VTooltip from 'v-tooltip';
142
143
// Disable on mobile devices
144
VTooltip.enabled = window.innerWidth > 768;
145
146
// Disable during specific app states
147
VTooltip.enabled = !this.$store.state.isLoading;
148
149
// Toggle based on user preferences
150
VTooltip.enabled = this.$store.state.user.showTooltips;
151
152
// Responsive enable/disable
153
window.addEventListener('resize', () => {
154
VTooltip.enabled = window.innerWidth > 768;
155
});
156
```
157
158
### Tooltip Global Options
159
160
Core tooltip configuration options affecting directive behavior.
161
162
```javascript { .api }
163
interface GlobalVTooltipOptions {
164
/** Default tooltip placement relative to target element */
165
defaultPlacement: 'auto' | 'auto-start' | 'auto-end' | 'top' | 'top-start' |
166
'top-end' | 'right' | 'right-start' | 'right-end' | 'bottom' |
167
'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end';
168
169
/** Default CSS classes applied to the tooltip element */
170
defaultClass: string;
171
172
/** Default CSS classes applied to the target element of the tooltip */
173
defaultTargetClass: string;
174
175
/** Is the content HTML by default? */
176
defaultHtml: boolean;
177
178
/** Default HTML template of the tooltip element */
179
defaultTemplate: string;
180
181
/** Selector used to get the arrow element in the tooltip template */
182
defaultArrowSelector: string;
183
184
/** Selector used to get the inner content element in the tooltip template */
185
defaultInnerSelector: string;
186
187
/** Default delay in milliseconds or delay configuration object */
188
defaultDelay: number | DelayConfig;
189
190
/** Default events that trigger the tooltip */
191
defaultTrigger: string;
192
193
/** Default position offset in pixels */
194
defaultOffset: number | string;
195
196
/** Default container where the tooltip will be appended */
197
defaultContainer: string | HTMLElement | false;
198
199
/** Default boundaries element for positioning */
200
defaultBoundariesElement: string | HTMLElement;
201
202
/** Default Popper.js options */
203
defaultPopperOptions: any;
204
205
/** Class added when content is loading */
206
defaultLoadingClass: string;
207
208
/** Displayed when tooltip content is loading */
209
defaultLoadingContent: string;
210
211
/** Hide on mouseover tooltip */
212
autoHide: boolean;
213
214
/** Close tooltip on click on tooltip target? */
215
defaultHideOnTargetClick: boolean;
216
217
/** Auto destroy tooltip DOM nodes after specified milliseconds */
218
disposeTimeout: number;
219
220
/** Options specific to popovers */
221
popover: Partial<GlobalVTooltipPopoverOptions>;
222
}
223
```
224
225
**Configuration Examples:**
226
227
```javascript
228
Vue.use(VTooltip, {
229
// Appearance
230
defaultPlacement: 'top',
231
defaultClass: 'vue-tooltip-theme dark-theme',
232
defaultTargetClass: 'has-tooltip highlighted',
233
234
// Content
235
defaultHtml: false, // Security: disable HTML by default
236
defaultTemplate: `
237
<div class="tooltip custom-tooltip" role="tooltip">
238
<div class="tooltip-arrow"></div>
239
<div class="tooltip-inner"></div>
240
</div>
241
`,
242
243
// Behavior
244
defaultDelay: { show: 200, hide: 100 },
245
defaultTrigger: 'hover focus',
246
autoHide: true,
247
defaultHideOnTargetClick: true,
248
249
// Positioning
250
defaultOffset: 5,
251
defaultContainer: 'body',
252
defaultPopperOptions: {
253
modifiers: {
254
preventOverflow: {
255
boundariesElement: 'viewport'
256
}
257
}
258
},
259
260
// Loading states
261
defaultLoadingClass: 'tooltip-loading spinner',
262
defaultLoadingContent: 'Loading...',
263
264
// Performance
265
disposeTimeout: 3000 // Cleanup after 3 seconds
266
});
267
```
268
269
### Popover Global Options
270
271
Configuration options specific to popover components.
272
273
```javascript { .api }
274
interface GlobalVTooltipPopoverOptions {
275
/** Default popover placement */
276
defaultPlacement: string;
277
278
/** Default theme class for popovers */
279
defaultClass: string;
280
281
/** Base structural classes */
282
defaultBaseClass: string;
283
284
/** Wrapper element classes */
285
defaultWrapperClass: string;
286
287
/** Inner content classes */
288
defaultInnerClass: string;
289
290
/** Arrow element classes */
291
defaultArrowClass: string;
292
293
/** Classes applied when popover is open */
294
defaultOpenClass: string;
295
296
/** Default delay configuration */
297
defaultDelay: number | DelayConfig;
298
299
/** Default trigger events */
300
defaultTrigger: string;
301
302
/** Default position offset */
303
defaultOffset: number | string;
304
305
/** Default container element */
306
defaultContainer: string | HTMLElement | false;
307
308
/** Default boundaries element */
309
defaultBoundariesElement: string | HTMLElement;
310
311
/** Default Popper.js options */
312
defaultPopperOptions: any;
313
314
/** Hides if clicked outside of popover */
315
defaultAutoHide: boolean;
316
317
/** Update popper on content resize */
318
defaultHandleResize: boolean;
319
}
320
```
321
322
**Popover Configuration Examples:**
323
324
```javascript
325
Vue.use(VTooltip, {
326
popover: {
327
// Appearance
328
defaultPlacement: 'bottom-start',
329
defaultClass: 'vue-popover-theme material-design',
330
defaultBaseClass: 'tooltip popover elevated',
331
defaultWrapperClass: 'wrapper padded',
332
defaultInnerClass: 'tooltip-inner popover-inner scrollable',
333
defaultArrowClass: 'tooltip-arrow popover-arrow colored',
334
defaultOpenClass: 'open visible',
335
336
// Behavior
337
defaultTrigger: 'click',
338
defaultDelay: { show: 0, hide: 200 },
339
defaultAutoHide: true,
340
defaultHandleResize: true,
341
342
// Positioning
343
defaultOffset: 8,
344
defaultContainer: '.app-container',
345
defaultPopperOptions: {
346
modifiers: {
347
flip: {
348
behavior: ['bottom', 'top', 'right', 'left']
349
},
350
preventOverflow: {
351
escapeWithReference: true
352
}
353
}
354
}
355
}
356
});
357
```
358
359
### Template Customization
360
361
Customize the HTML structure of tooltips globally.
362
363
```javascript { .api }
364
interface TemplateOptions {
365
/** HTML template for tooltip element */
366
defaultTemplate: string;
367
368
/** CSS selector for arrow element */
369
defaultArrowSelector: string;
370
371
/** CSS selector for inner content element */
372
defaultInnerSelector: string;
373
}
374
```
375
376
**Template Examples:**
377
378
```javascript
379
Vue.use(VTooltip, {
380
// Custom template with additional elements
381
defaultTemplate: `
382
<div class="tooltip" role="tooltip">
383
<div class="tooltip-arrow"></div>
384
<div class="tooltip-header"></div>
385
<div class="tooltip-inner"></div>
386
<div class="tooltip-footer"></div>
387
</div>
388
`,
389
390
// Custom selectors for complex templates
391
defaultArrowSelector: '.tooltip-arrow, .custom-arrow',
392
defaultInnerSelector: '.tooltip-inner, .tooltip-content',
393
394
// Bootstrap-compatible template
395
defaultTemplate: `
396
<div class="tooltip bs-tooltip-auto" role="tooltip">
397
<div class="arrow"></div>
398
<div class="tooltip-inner"></div>
399
</div>
400
`,
401
defaultArrowSelector: '.arrow',
402
defaultInnerSelector: '.tooltip-inner'
403
});
404
```
405
406
### Delay Configuration
407
408
Advanced delay settings for show/hide timing.
409
410
```javascript { .api }
411
interface DelayConfig {
412
/** Delay before showing tooltip in milliseconds */
413
show?: number;
414
415
/** Delay before hiding tooltip in milliseconds */
416
hide?: number;
417
}
418
419
// Delay options
420
defaultDelay: number | DelayConfig;
421
```
422
423
**Delay Examples:**
424
425
```javascript
426
Vue.use(VTooltip, {
427
// Simple delay (applies to both show and hide)
428
defaultDelay: 300,
429
430
// Separate show/hide delays
431
defaultDelay: {
432
show: 500, // Wait 500ms before showing
433
hide: 100 // Wait 100ms before hiding
434
},
435
436
// Popover delays
437
popover: {
438
defaultDelay: {
439
show: 0, // Show immediately
440
hide: 300 // Wait 300ms before hiding
441
}
442
}
443
});
444
```
445
446
### Performance Configuration
447
448
Settings that affect performance and resource management.
449
450
```javascript { .api }
451
interface PerformanceOptions {
452
/** Auto destroy tooltip DOM nodes after specified milliseconds */
453
disposeTimeout: number;
454
455
/** Automatically hide tooltips on mouseover */
456
autoHide: boolean;
457
458
/** Update popover position when content size changes */
459
defaultHandleResize: boolean;
460
}
461
```
462
463
**Performance Examples:**
464
465
```javascript
466
Vue.use(VTooltip, {
467
// DOM cleanup timing
468
disposeTimeout: 2000, // Clean up after 2 seconds
469
470
// Auto-hide behavior
471
autoHide: true, // Hide when hovering over tooltip
472
473
// Popover performance
474
popover: {
475
defaultHandleResize: false // Disable resize handling for better performance
476
}
477
});
478
479
// Disable cleanup for persistent tooltips
480
Vue.use(VTooltip, {
481
disposeTimeout: null // Never auto-dispose
482
});
483
```
484
485
### Runtime Configuration Changes
486
487
Modify configuration during application runtime.
488
489
```javascript { .api }
490
// Runtime configuration changes
491
VTooltip.options[key] = value;
492
VTooltip.options.popover[key] = value;
493
```
494
495
**Runtime Examples:**
496
497
```javascript
498
// Change theme based on user preference
499
function setTooltipTheme(theme) {
500
VTooltip.options.defaultClass = `vue-tooltip-theme ${theme}`;
501
VTooltip.options.popover.defaultClass = `vue-popover-theme ${theme}`;
502
}
503
504
// Adjust delays based on device
505
function configureForDevice() {
506
const isMobile = window.innerWidth < 768;
507
508
VTooltip.options.defaultDelay = isMobile ? 0 : 200;
509
VTooltip.options.popover.defaultAutoHide = isMobile;
510
VTooltip.enabled = !isMobile; // Disable on mobile
511
}
512
513
// Configure for accessibility
514
function enableAccessibleMode() {
515
VTooltip.options.defaultTrigger = 'focus click';
516
VTooltip.options.defaultDelay = { show: 0, hide: 500 };
517
VTooltip.options.popover.defaultTrigger = 'click';
518
}
519
```