0
# Core Tooltip API
1

2
The core tooltip functionality provides the primary interface for creating and managing individual tooltip instances with comprehensive configuration and lifecycle management.
3

4
## Capabilities
5

6
### Tippy Factory Function
7

8
Creates tooltip instances for DOM elements with optional configuration properties.
9

10
```typescript { .api }
11
/**
12
 * Creates tooltip instances for given DOM elements or selectors
13
 * @param targets - Element(s) or CSS selector for tooltip triggers
14
 * @param optionalProps - Optional configuration properties
15
 * @returns Single instance for single target, array for multiple targets
16
 */
17
function tippy<TProps = Props>(
18
  targets: Element | Element[] | NodeList | string,
19
  optionalProps?: Partial<TProps>
20
): Instance<TProps> | Instance<TProps>[];
21

22
// Target types
23
type SingleTarget = Element;
24
type MultipleTargets = string | Element[] | NodeList;
25
type Targets = SingleTarget | MultipleTargets;
26
```
27

28
**Usage Examples:**
29

30
```typescript
31
import tippy from "tippy.js";
32

33
// Single element
34
const button = document.querySelector('#myButton');
35
const instance = tippy(button, {
36
  content: 'Click me!',
37
  placement: 'top'
38
});
39

40
// Multiple elements by selector
41
const instances = tippy('.tooltip-trigger', {
42
  content: 'Default content',
43
  delay: [500, 100]
44
});
45

46
// Multiple elements by NodeList
47
const elements = document.querySelectorAll('.dynamic-tooltip');
48
const instances = tippy(elements, {
49
  content(reference) {
50
    return reference.getAttribute('data-title') || 'No title';
51
  }
52
});
53

54
// Dynamic content function
55
tippy('#user-info', {
56
  content(reference) {
57
    const userId = reference.dataset.userId;
58
    return `<div>Loading user ${userId}...</div>`;
59
  },
60
  allowHTML: true,
61
  onShow(instance) {
62
    // Fetch and update content asynchronously
63
    fetchUserData(instance.reference.dataset.userId)
64
      .then(data => instance.setContent(`<div>${data.name}</div>`));
65
  }
66
});
67
```
68

69
### Instance Methods
70

71
Core methods available on every tooltip instance for programmatic control.
72

73
```typescript { .api }
74
interface Instance<TProps = Props> {
75
  /** Unique identifier for this instance */
76
  id: number;
77
  /** Reference to the trigger element */
78
  reference: ReferenceElement<TProps>;
79
  /** Reference to the tooltip element (when mounted) */
80
  popper: PopperElement<TProps>;
81
  /** Popper.js instance for positioning (when mounted) */
82
  popperInstance: Popper.Instance | null;
83
  /** Current configuration properties */
84
  props: TProps;
85
  /** Active plugins for this instance */
86
  plugins: Plugin<TProps>[];
87
  /** Current state information */
88
  state: {
89
    isEnabled: boolean;
90
    isVisible: boolean;
91
    isDestroyed: boolean;
92
    isMounted: boolean;
93
    isShown: boolean;
94
  };
95
  
96
  /** Show the tooltip */
97
  show(): void;
98
  /** Hide the tooltip */
99
  hide(): void;
100
  /** Enable the tooltip (allow show/hide) */
101
  enable(): void;
102
  /** Disable the tooltip (prevent show/hide) */
103
  disable(): void;
104
  /** Update tooltip content */
105
  setContent(content: Content): void;
106
  /** Update configuration properties */
107
  setProps(partialProps: Partial<TProps>): void;
108
  /** Clear any pending delay timers */
109
  clearDelayTimeouts(): void;
110
  /** Hide with interactivity consideration */
111
  hideWithInteractivity(event: MouseEvent): void;
112
  /** Unmount tooltip from DOM (but keep instance) */
113
  unmount(): void;
114
  /** Destroy instance and remove all event listeners */
115
  destroy(): void;
116
}
117
```
118

119
**Usage Examples:**
120

121
```typescript
122
const instance = tippy('#myButton', { content: 'Hello' });
123

124
// Programmatic control
125
instance.show();
126
setTimeout(() => instance.hide(), 2000);
127

128
// Dynamic updates
129
instance.setContent('Updated content');
130
instance.setProps({ 
131
  placement: 'bottom',
132
  delay: 1000 
133
});
134

135
// State checking
136
if (instance.state.isVisible) {
137
  instance.hide();
138
}
139

140
// Cleanup
141
instance.destroy();
142
```
143

144
### Content Types
145

146
Flexible content system supporting multiple formats and dynamic generation.
147

148
```typescript { .api }
149
type Content = 
150
  | string 
151
  | Element 
152
  | DocumentFragment 
153
  | ((ref: Element) => string | Element | DocumentFragment);
154
```
155

156
**Usage Examples:**
157

158
```typescript
159
// String content
160
tippy('#basic', { content: 'Simple text' });
161

162
// HTML string (requires allowHTML: true)
163
tippy('#html', { 
164
  content: '<strong>Bold</strong> text',
165
  allowHTML: true 
166
});
167

168
// DOM element
169
const div = document.createElement('div');
170
div.textContent = 'Element content';
171
tippy('#element', { content: div });
172

173
// Function returning string
174
tippy('.dynamic', {
175
  content(reference) {
176
    return `Tooltip for ${reference.textContent}`;
177
  }
178
});
179

180
// Function returning element
181
tippy('.complex', {
182
  content(reference) {
183
    const container = document.createElement('div');
184
    container.innerHTML = `
185
      <h3>${reference.dataset.title}</h3>
186
      <p>${reference.dataset.description}</p>
187
    `;
188
    return container;
189
  }
190
});
191
```
192

193
### Lifecycle Hooks
194

195
Comprehensive event system for customizing tooltip behavior at different stages.
196

197
```typescript { .api }
198
interface LifecycleHooks<TProps = Props> {
199
  /** Called after instance properties are updated */
200
  onAfterUpdate(instance: Instance<TProps>, partialProps: Partial<TProps>): void;
201
  /** Called before instance properties are updated */
202
  onBeforeUpdate(instance: Instance<TProps>, partialProps: Partial<TProps>): void;
203
  /** Called when instance is first created */
204
  onCreate(instance: Instance<TProps>): void;
205
  /** Called when instance is destroyed */
206
  onDestroy(instance: Instance<TProps>): void;
207
  /** Called after tooltip is fully hidden */
208
  onHidden(instance: Instance<TProps>): void;
209
  /** Called before tooltip starts hiding (can prevent with return false) */
210
  onHide(instance: Instance<TProps>): void | false;
211
  /** Called after tooltip is mounted to DOM */
212
  onMount(instance: Instance<TProps>): void;
213
  /** Called before tooltip starts showing (can prevent with return false) */
214
  onShow(instance: Instance<TProps>): void | false;
215
  /** Called after tooltip is fully shown */
216
  onShown(instance: Instance<TProps>): void;
217
  /** Called when trigger event occurs */
218
  onTrigger(instance: Instance<TProps>, event: Event): void;
219
  /** Called when untrigger event occurs */
220
  onUntrigger(instance: Instance<TProps>, event: Event): void;
221
  /** Called when clicking outside interactive tooltip */
222
  onClickOutside(instance: Instance<TProps>, event: Event): void;
223
}
224
```
225

226
**Usage Examples:**
227

228
```typescript
229
tippy('#advanced', {
230
  content: 'Loading...',
231
  onShow(instance) {
232
    // Prevent showing if data not ready
233
    if (!instance.reference.dataset.ready) {
234
      return false;
235
    }
236
  },
237
  onMount(instance) {
238
    // Fetch content after mounting
239
    fetchTooltipContent(instance.reference.id)
240
      .then(content => instance.setContent(content));
241
  },
242
  onHidden(instance) {
243
    // Cleanup when hidden
244
    instance.setContent('Loading...');
245
  }
246
});
247
```
248

249
### Element References
250

251
Type-safe references to tooltip trigger and popup elements.
252

253
```typescript { .api }
254
interface ReferenceElement<TProps = Props> extends Element {
255
  /** Associated tippy instance (when created) */
256
  _tippy?: Instance<TProps>;
257
}
258

259
interface PopperElement<TProps = Props> extends HTMLDivElement {
260
  /** Associated tippy instance */
261
  _tippy?: Instance<TProps>;
262
}
263
```
264

265
### Default Properties
266

267
Access and modification of global default properties.
268

269
```typescript { .api }
270
interface DefaultProps extends Omit<Props, 'delay' | 'duration'> {
271
  delay: number | [number, number];
272
  duration: number | [number, number];
273
}
274

275
// Static properties on tippy function
276
interface TippyStatics {
277
  readonly currentInput: { isTouch: boolean };
278
  readonly defaultProps: DefaultProps;
279
  setDefaultProps(partialProps: Partial<DefaultProps>): void;
280
}
281
```
282

283
**Usage Examples:**
284

285
```typescript
286
import tippy from "tippy.js";
287

288
// Check current input type
289
if (tippy.currentInput.isTouch) {
290
  // Touch-specific behavior
291
}
292

293
// Update global defaults
294
tippy.setDefaultProps({
295
  delay: 500,
296
  duration: [200, 150],
297
  theme: 'dark'
298
});
299

300
// Access current defaults
301
console.log(tippy.defaultProps.placement); // 'top'
302
```