0
# Tippy.js
1

2
Tippy.js is the complete tooltip, popover, dropdown, and menu solution for the web. It provides a powerful, feature-rich system for creating highly customizable interactive elements with automatic positioning, animations, and accessibility features built on top of Popper.js.
3

4
## Package Information
5

6
- **Package Name**: tippy.js
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install tippy.js`
10

11
## Core Imports
12

13
```typescript
14
import tippy from "tippy.js";
15
import "tippy.js/dist/tippy.css"; // Required CSS
16
```
17

18
For named exports:
19

20
```typescript
21
import tippy, { hideAll, delegate, createSingleton, roundArrow } from "tippy.js";
22
// Plugins
23
import { animateFill, followCursor, inlinePositioning, sticky } from "tippy.js";
24
// CSS
25
import "tippy.js/dist/tippy.css";
26
```
27

28
Headless (without default animations):
29

30
```typescript
31
import tippy from "tippy.js/headless";
32
// All other exports available too
33
import { hideAll, delegate, createSingleton } from "tippy.js/headless";
34
```
35

36
CommonJS:
37

38
```javascript
39
const tippy = require("tippy.js").default;
40
// CSS (using a bundler that supports CSS imports)
41
require("tippy.js/dist/tippy.css");
42
// or
43
const { default: tippy, hideAll } = require("tippy.js");
44
```
45

46
## Basic Usage
47

48
```typescript
49
import tippy from "tippy.js";
50

51
// Create a tooltip for a single element
52
const instance = tippy('#myButton', {
53
  content: 'My tooltip content',
54
  placement: 'top',
55
  animation: 'fade',
56
});
57

58
// Create tooltips for multiple elements
59
const instances = tippy('.tooltip', {
60
  content(reference) {
61
    return reference.getAttribute('data-tooltip');
62
  },
63
  placement: 'bottom',
64
});
65

66
// Show and hide programmatically
67
instance.show();
68
instance.hide();
69

70
// Update content dynamically
71
instance.setContent('New content');
72
```
73

74
## Architecture
75

76
Tippy.js is built around several key components:
77

78
- **Core Factory Function**: The main `tippy()` function creates and manages tooltip instances
79
- **Instance Management**: Each tooltip is represented by an `Instance` object with lifecycle methods
80
- **Plugin System**: Extensible plugin architecture for custom behaviors and animations
81
- **Popper.js Integration**: Advanced positioning engine with collision detection and boundary awareness
82
- **Lifecycle Hooks**: Comprehensive event system for customizing tooltip behavior
83
- **Theme System**: CSS-based theming with built-in themes and custom theme support
84

85
## Capabilities
86

87
### Core Tooltip Creation
88

89
Primary factory function for creating tooltip instances with comprehensive configuration options and lifecycle management.
90

91
```typescript { .api }
92
function tippy(
93
  targets: Element | Element[] | NodeList | string,
94
  optionalProps?: Partial<Props>
95
): Instance | Instance[];
96

97
interface Instance {
98
  clearDelayTimeouts(): void;
99
  destroy(): void;
100
  disable(): void;
101
  enable(): void;
102
  hide(): void;
103
  hideWithInteractivity(event: MouseEvent): void;
104
  id: number;
105
  plugins: Plugin[];
106
  popper: PopperElement;
107
  popperInstance: Popper.Instance | null;
108
  props: Props;
109
  reference: ReferenceElement;
110
  setContent(content: Content): void;
111
  setProps(partialProps: Partial<Props>): void;
112
  show(): void;
113
  state: {
114
    isEnabled: boolean;
115
    isVisible: boolean;
116
    isDestroyed: boolean;
117
    isMounted: boolean;
118
    isShown: boolean;
119
  };
120
  unmount(): void;
121
}
122
```
123

124
[Core Tooltip API](./core-tooltip.md)
125

126
### Global Utilities
127

128
Global utility functions for managing multiple tooltips and accessing framework-level functionality.
129

130
```typescript { .api }
131
function hideAll(options?: HideAllOptions): void;
132

133
interface HideAllOptions {
134
  duration?: number;
135
  exclude?: Instance | ReferenceElement;
136
}
137

138
// Static properties on tippy function
139
const tippy: {
140
  defaultProps: DefaultProps;
141
  setDefaultProps(partialProps: Partial<DefaultProps>): void;
142
  currentInput: { isTouch: boolean };
143
};
144
```
145

146
[Global Utilities](./global-utilities.md)
147

148
### Constants
149

150
Pre-defined constants for common tooltip styling and configuration.
151

152
```typescript { .api }
153
/** SVG markup for rounded arrow shape */
154
const roundArrow: '<svg width="16" height="6" xmlns="http://www.w3.org/2000/svg"><path d="M0 6s1.796-.013 4.67-3.615C5.851.9 6.93.006 8 0c1.07-.006 2.148.887 3.343 2.385C14.233 6.005 16 6 16 6H0z"></path></svg>';
155
```
156

157
### Event Delegation
158

159
Advanced event delegation system for handling tooltips on dynamically created elements and managing large sets of tooltip triggers.
160

161
```typescript { .api }
162
function delegate(
163
  targets: Element | Element[] | NodeList | string,
164
  props: Partial<Props> & { target: string }
165
): Instance | Instance[];
166
```
167

168
[Event Delegation](./event-delegation.md)
169

170
### Singleton Tooltips
171

172
Singleton system for creating shared tooltips that can be displayed across multiple reference elements with smooth transitions.
173

174
```typescript { .api }
175
function createSingleton(
176
  tippyInstances: Instance[],
177
  optionalProps?: Partial<CreateSingletonProps>
178
): CreateSingletonInstance;
179

180
interface CreateSingletonInstance extends Instance {
181
  setInstances(instances: Instance[]): void;
182
  show(target?: ReferenceElement | Instance | number): void;
183
  showNext(): void;
184
  showPrevious(): void;
185
}
186
```
187

188
[Singleton Tooltips](./singleton-tooltips.md)
189

190
### Plugins
191

192
Built-in plugin system with four official plugins for advanced behaviors and effects.
193

194
```typescript { .api }
195
// Official plugins
196
const animateFill: AnimateFill;
197
const followCursor: FollowCursor;
198
const inlinePositioning: InlinePositioning;
199
const sticky: Sticky;
200

201
interface Plugin {
202
  name?: string;
203
  defaultValue?: any;
204
  fn(instance: Instance): Partial<LifecycleHooks>;
205
}
206
```
207

208
[Plugins](./plugins.md)
209

210
## Core Types
211

212
```typescript { .api }
213
type Content = 
214
  | string 
215
  | Element 
216
  | DocumentFragment 
217
  | ((ref: Element) => string | Element | DocumentFragment);
218

219
type Placement = 
220
  | 'auto' | 'auto-start' | 'auto-end'
221
  | 'top' | 'top-start' | 'top-end'
222
  | 'bottom' | 'bottom-start' | 'bottom-end'
223
  | 'right' | 'right-start' | 'right-end'
224
  | 'left' | 'left-start' | 'left-end';
225

226
interface GetReferenceClientRect {
227
  (): ClientRect | DOMRect;
228
  contextElement?: Element;
229
}
230

231
interface ReferenceElement<TProps = Props> extends Element {
232
  _tippy?: Instance<TProps>;
233
}
234

235
interface PopperElement<TProps = Props> extends HTMLDivElement {
236
  _tippy?: Instance<TProps>;
237
}
238

239
interface Props extends LifecycleHooks, RenderProps {
240
  animateFill: boolean;
241
  appendTo: 'parent' | Element | ((ref: Element) => Element);
242
  aria: {
243
    content?: 'auto' | 'describedby' | 'labelledby' | null;
244
    expanded?: 'auto' | boolean;
245
  };
246
  delay: number | [number | null, number | null];
247
  duration: number | [number | null, number | null];
248
  followCursor: boolean | 'horizontal' | 'vertical' | 'initial';
249
  getReferenceClientRect: null | GetReferenceClientRect;
250
  hideOnClick: boolean | 'toggle';
251
  ignoreAttributes: boolean;
252
  inlinePositioning: boolean;
253
  interactive: boolean;
254
  interactiveBorder: number;
255
  interactiveDebounce: number;
256
  moveTransition: string;
257
  offset: [number, number] | ((args: {
258
    placement: Placement;
259
    popper: Popper.Rect;
260
    reference: Popper.Rect;
261
  }) => [number, number]);
262
  placement: Placement;
263
  plugins: Plugin[];
264
  popperOptions: Partial<Popper.Options>;
265
  render: ((instance: Instance) => {
266
    popper: PopperElement;
267
    onUpdate?: (prevProps: Props, nextProps: Props) => void;
268
  }) | null;
269
  showOnCreate: boolean;
270
  sticky: boolean | 'reference' | 'popper';
271
  touch: boolean | 'hold' | ['hold', number];
272
  trigger: string;
273
  triggerTarget: Element | Element[] | null;
274
}
275

276
interface LifecycleHooks {
277
  onAfterUpdate(instance: Instance, partialProps: Partial<Props>): void;
278
  onBeforeUpdate(instance: Instance, partialProps: Partial<Props>): void;
279
  onCreate(instance: Instance): void;
280
  onDestroy(instance: Instance): void;
281
  onHidden(instance: Instance): void;
282
  onHide(instance: Instance): void | false;
283
  onMount(instance: Instance): void;
284
  onShow(instance: Instance): void | false;
285
  onShown(instance: Instance): void;
286
  onTrigger(instance: Instance, event: Event): void;
287
  onUntrigger(instance: Instance, event: Event): void;
288
  onClickOutside(instance: Instance, event: Event): void;
289
}
290

291
interface RenderProps {
292
  allowHTML: boolean;
293
  animation: string | boolean;
294
  arrow: boolean | string | SVGElement | DocumentFragment;
295
  content: Content;
296
  inertia: boolean;
297
  maxWidth: number | string;
298
  role: string;
299
  theme: string;
300
  zIndex: number;
301
}
302
```