0
# Tippy.js for React
1

2
Tippy.js for React is a comprehensive React wrapper for Tippy.js, providing the complete tooltip, popover, dropdown, and menu solution for the web. It offers two rendering approaches: default DOM rendering with built-in CSS for out-of-the-box functionality, and headless rendering for full integration with CSS-in-JS libraries and design systems.
3

4
## Package Information
5

6
- **Package Name**: @tippyjs/react
7
- **Package Type**: npm
8
- **Language**: TypeScript/JavaScript
9
- **Installation**: `npm install @tippyjs/react` or `yarn add @tippyjs/react`
10

11
## Core Imports
12

13
Default Tippy with built-in rendering:
14

15
```typescript
16
import Tippy from '@tippyjs/react';
17
import 'tippy.js/dist/tippy.css'; // optional CSS
18
```
19

20
Headless Tippy for custom rendering:
21

22
```typescript
23
import Tippy from '@tippyjs/react/headless';
24
```
25

26
Singleton hook for performance optimization:
27

28
```typescript
29
import Tippy, { useSingleton } from '@tippyjs/react';
30
```
31

32
Core Tippy.js access:
33

34
```typescript
35
import { tippy } from '@tippyjs/react';
36
```
37

38
## Basic Usage
39

40
```typescript
41
import React from 'react';
42
import Tippy from '@tippyjs/react';
43
import 'tippy.js/dist/tippy.css';
44

45
function App() {
46
  return (
47
    <Tippy content="Hello world" placement="top" arrow={true}>
48
      <button>Hover me</button>
49
    </Tippy>
50
  );
51
}
52
```
53

54
## Architecture
55

56
Tippy.js for React is built around several key components:
57

58
- **Default Rendering**: Complete tooltip implementation with built-in DOM rendering and CSS
59
- **Headless Rendering**: Custom render function approach for CSS-in-JS and design system integration
60
- **Controlled Mode**: React state-driven visibility control for programmatic tooltip management
61
- **Singleton Mode**: Performance optimization technique for multiple tooltips sharing a single instance
62
- **Plugin System**: Support for Tippy.js plugins and extensions for advanced functionality
63
- **Forward Ref Support**: Proper React ref forwarding for component composition
64

65
## Capabilities
66

67
### Default Rendering
68

69
Complete tooltip implementation with built-in DOM rendering, styling, and animations. Perfect for quick integration with minimal setup.
70

71
```typescript { .api }
72
interface TippyProps extends Partial<Omit<Props, 'content' | 'render'>> {
73
  children?: React.ReactElement<any>;
74
  content?: React.ReactNode;
75
  visible?: boolean;
76
  disabled?: boolean;
77
  className?: string;
78
  singleton?: SingletonObject;
79
  reference?: React.RefObject<Element> | Element | null;
80
  ref?: React.Ref<Element>;
81
}
82

83
declare const Tippy: React.ForwardRefExoticComponent<TippyProps>;
84
```
85

86
[Default Rendering](./default-rendering.md)
87

88
### Headless Rendering
89

90
Custom render function approach for complete control over tooltip appearance and behavior. Ideal for CSS-in-JS libraries and design systems.
91

92
```typescript { .api }
93
interface TippyProps {
94
  render?: (
95
    attrs: {
96
      'data-placement': Placement;
97
      'data-reference-hidden'?: string;
98
      'data-escaped'?: string;
99
    },
100
    content?: React.ReactNode,
101
    instance?: Instance
102
  ) => React.ReactNode;
103
}
104
```
105

106
[Headless Rendering](./headless-rendering.md)
107

108
### Singleton Mode
109

110
Performance optimization technique for multiple tooltips that share a single instance, reducing memory usage and improving performance.
111

112
```typescript { .api }
113
interface UseSingletonProps {
114
  disabled?: boolean;
115
  overrides?: Array<keyof Props>;
116
}
117

118
function useSingleton(
119
  props?: UseSingletonProps
120
): [SingletonObject, SingletonObject];
121

122
interface SingletonObject {
123
  data?: any;
124
  hook(args: SingletonHookArgs): void;
125
}
126

127
interface SingletonHookArgs {
128
  instance: Instance;
129
  content: React.ReactNode;
130
  props: Props;
131
}
132
```
133

134
[Singleton Mode](./singleton-mode.md)
135

136
### Core Tippy.js Access
137

138
Direct access to the core Tippy.js functionality for advanced use cases and imperative API usage.
139

140
```typescript { .api }
141
export const tippy: typeof tippyCore;
142
```
143

144
The `tippy` export provides direct access to the core Tippy.js library, allowing you to create tooltips imperatively or access advanced features not exposed through the React component API.
145

146
**Usage Examples:**
147

148
```typescript
149
import { tippy } from '@tippyjs/react';
150

151
// Create tooltip imperatively
152
function ImperativeTooltip() {
153
  const buttonRef = useRef<HTMLButtonElement>(null);
154

155
  useEffect(() => {
156
    if (buttonRef.current) {
157
      const instance = tippy(buttonRef.current, {
158
        content: 'Imperative tooltip',
159
        placement: 'top',
160
      });
161

162
      return () => {
163
        instance.destroy();
164
      };
165
    }
166
  }, []);
167

168
  return <button ref={buttonRef}>Imperative tooltip</button>;
169
}
170
```
171

172
## Core Types
173

174
```typescript { .api }
175
type Content = React.ReactNode;
176

177
interface TippyProps extends Partial<Omit<Props, 'content' | 'render'>> {
178
  children?: React.ReactElement<any>;
179
  content?: Content;
180
  visible?: boolean;
181
  disabled?: boolean;
182
  className?: string;
183
  singleton?: SingletonObject;
184
  reference?: React.RefObject<Element> | Element | null;
185
  ref?: React.Ref<Element>;
186
  render?: (
187
    attrs: {
188
      'data-placement': Placement;
189
      'data-reference-hidden'?: string;
190
      'data-escaped'?: string;
191
    },
192
    content?: Content,
193
    instance?: Instance
194
  ) => React.ReactNode;
195
}
196

197
interface SingletonObject {
198
  data?: any;
199
  hook(args: SingletonHookArgs): void;
200
}
201

202
interface SingletonHookArgs {
203
  instance: Instance;
204
  content: Content;
205
  props: Props;
206
}
207

208
interface UseSingletonProps {
209
  disabled?: boolean;
210
  overrides?: Array<keyof Props>;
211
}
212
```
213

214
Note: `Props`, `Instance`, and `Placement` types are imported from the core `tippy.js` library. The `Props` interface includes all native Tippy.js properties such as `placement`, `trigger`, `delay`, `animation`, `arrow`, `interactive`, `theme`, and many others. Refer to the [Tippy.js documentation](https://atomiks.github.io/tippyjs/v6/all-props/) for a complete list of available properties.