0
# Default Rendering
1

2
Default rendering provides a complete tooltip implementation with built-in DOM rendering, styling, and animations. This is the standard approach that works out-of-the-box with minimal setup, perfect for most use cases.
3

4
## Capabilities
5

6
### Basic Tooltip
7

8
Creates a tooltip with built-in rendering and styling.
9

10
```typescript { .api }
11
/**
12
 * Main Tippy component with default rendering
13
 * @param props - TippyProps configuration
14
 * @returns React component with tooltip functionality
15
 */
16
declare const Tippy: React.ForwardRefExoticComponent<TippyProps>;
17

18
interface TippyProps extends Partial<Omit<Props, 'content' | 'render'>> {
19
  /** Child element to attach tooltip to */
20
  children?: React.ReactElement<any>;
21
  /** Tooltip content - can be string or React element */
22
  content?: React.ReactNode;
23
  /** Controlled mode - explicitly control visibility */
24
  visible?: boolean;
25
  /** Disable/enable the tooltip */
26
  disabled?: boolean;
27
  /** CSS classes to apply to tooltip */
28
  className?: string;
29
  /** Singleton configuration for shared instances */
30
  singleton?: SingletonObject;
31
  /** External reference element (alternative to children) */
32
  reference?: React.RefObject<Element> | Element | null;
33
  /** Forward ref to underlying element */
34
  ref?: React.Ref<Element>;
35
}
36
```
37

38
**Usage Examples:**
39

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

45
// String content
46
function StringTooltip() {
47
  return (
48
    <Tippy content="Hello world">
49
      <button>Hover me</button>
50
    </Tippy>
51
  );
52
}
53

54
// React element content
55
function ReactTooltip() {
56
  return (
57
    <Tippy content={<div><strong>Bold</strong> tooltip</div>}>
58
      <button>Hover me</button>
59
    </Tippy>
60
  );
61
}
62

63
// With styling
64
function StyledTooltip() {
65
  return (
66
    <Tippy 
67
      content="Styled tooltip" 
68
      className="custom-tooltip"
69
      theme="dark"
70
      arrow={true}
71
    >
72
      <button>Hover me</button>
73
    </Tippy>
74
  );
75
}
76
```
77

78
### Controlled Mode
79

80
Use React state to control tooltip visibility programmatically instead of relying on native triggers.
81

82
```typescript { .api }
83
interface TippyProps {
84
  /** Control visibility with React state */
85
  visible?: boolean;
86
}
87
```
88

89
**Usage Examples:**
90

91
```typescript
92
import React, { useState } from 'react';
93
import Tippy from '@tippyjs/react';
94

95
function ControlledTooltip() {
96
  const [visible, setVisible] = useState(false);
97

98
  const show = () => setVisible(true);
99
  const hide = () => setVisible(false);
100

101
  return (
102
    <Tippy 
103
      content="Controlled tooltip" 
104
      visible={visible}
105
      onClickOutside={hide}
106
    >
107
      <button onClick={visible ? hide : show}>
108
        {visible ? 'Hide' : 'Show'} tooltip
109
      </button>
110
    </Tippy>
111
  );
112
}
113
```
114

115
### External Reference
116

117
Attach tooltip to an element outside the component tree using a ref or direct element reference.
118

119
```typescript { .api }
120
interface TippyProps {
121
  /** External reference element */
122
  reference?: React.RefObject<Element> | Element | null;
123
}
124
```
125

126
**Usage Examples:**
127

128
```typescript
129
import React, { useRef } from 'react';
130
import Tippy from '@tippyjs/react';
131

132
function ExternalReference() {
133
  const buttonRef = useRef<HTMLButtonElement>(null);
134

135
  return (
136
    <>
137
      <button ref={buttonRef}>Target element</button>
138
      <Tippy content="External tooltip" reference={buttonRef} />
139
    </>
140
  );
141
}
142
```
143

144
### Disabled State
145

146
Temporarily disable tooltip functionality while keeping the component mounted.
147

148
```typescript { .api }
149
interface TippyProps {
150
  /** Disable the tooltip */
151
  disabled?: boolean;
152
}
153
```
154

155
**Usage Examples:**
156

157
```typescript
158
import React, { useState } from 'react';
159
import Tippy from '@tippyjs/react';
160

161
function DisableableTooltip() {
162
  const [disabled, setDisabled] = useState(false);
163

164
  return (
165
    <div>
166
      <Tippy content="This tooltip can be disabled" disabled={disabled}>
167
        <button>Hover me</button>
168
      </Tippy>
169
      <button onClick={() => setDisabled(!disabled)}>
170
        {disabled ? 'Enable' : 'Disable'} tooltip
171
      </button>
172
    </div>
173
  );
174
}
175
```
176

177
### Multiple Tooltips
178

179
Create multiple tooltips on a single element by nesting components.
180

181
```typescript
182
// Multiple tooltips with different placements
183
function MultipleTooltips() {
184
  return (
185
    <Tippy content="Top tooltip" placement="top">
186
      <Tippy content="Bottom tooltip" placement="bottom">
187
        <Tippy content="Left tooltip" placement="left">
188
          <Tippy content="Right tooltip" placement="right">
189
            <button>Hover me</button>
190
          </Tippy>
191
        </Tippy>
192
      </Tippy>
193
    </Tippy>
194
  );
195
}
196
```
197

198
### Component Children
199

200
When using custom components as children, ensure they forward refs properly.
201

202
```typescript
203
import React, { forwardRef } from 'react';
204

205
// This won't work - no ref forwarding
206
function BadComponent() {
207
  return <button>Reference</button>;
208
}
209

210
// This will work - properly forwards ref
211
const GoodComponent = forwardRef<HTMLButtonElement>((props, ref) => {
212
  return <button ref={ref} {...props}>Reference</button>;
213
});
214

215
function App() {
216
  return (
217
    <Tippy content="Tooltip">
218
      <GoodComponent />
219
    </Tippy>
220
  );
221
}
222
```
223

224
### All Tippy.js Props
225

226
The component accepts all native Tippy.js props for complete customization.
227

228
```typescript
229
// Common Tippy.js props
230
function AdvancedTooltip() {
231
  return (
232
    <Tippy
233
      content="Advanced tooltip"
234
      placement="top-start"
235
      trigger="click"
236
      interactive={true}
237
      interactiveBorder={20}
238
      delay={[100, 50]}
239
      duration={[200, 150]}
240
      animation="fade"
241
      arrow={true}
242
      theme="dark"
243
      maxWidth={300}
244
      hideOnClick={false}
245
      onShow={(instance) => console.log('Tooltip shown')}
246
      onHide={(instance) => console.log('Tooltip hidden')}
247
    >
248
      <button>Advanced tooltip</button>
249
    </Tippy>
250
  );
251
}
252
```
253

254
### Tippy.js Plugins
255

256
Extend tooltip functionality using Tippy.js plugins for tree-shaking optimization and advanced features.
257

258
```typescript { .api }
259
interface TippyProps {
260
  /** Array of Tippy.js plugins to extend functionality */
261
  plugins?: Plugin[];
262
}
263
```
264

265
**Usage Examples:**
266

267
```typescript
268
import React from 'react';
269
import Tippy from '@tippyjs/react';
270
import { followCursor } from 'tippy.js';
271

272
// Using followCursor plugin
273
function FollowCursorTooltip() {
274
  return (
275
    <Tippy 
276
      content="I follow the cursor!" 
277
      followCursor={true} 
278
      plugins={[followCursor]}
279
    >
280
      <button>Hover and move cursor</button>
281
    </Tippy>
282
  );
283
}
284

285
// Multiple plugins
286
import { sticky } from 'tippy.js';
287

288
function MultiplePlugins() {
289
  return (
290
    <Tippy 
291
      content="Advanced tooltip with plugins"
292
      followCursor="horizontal"
293
      sticky={true}
294
      plugins={[followCursor, sticky]}
295
    >
296
      <button>Advanced plugin example</button>
297
    </Tippy>
298
  );
299
}
300
```
301

302
Note: When using plugins, you must import them from `tippy.js` (not `tippy.js/headless`) even when using the default rendering mode.
303

304
## CSS Import
305

306
Import the default CSS for styling (optional but recommended):
307

308
```typescript
309
import 'tippy.js/dist/tippy.css';
310
```
311

312
The CSS provides default styling, themes, and animations. You can customize appearance using:
313
- The `className` prop for custom CSS classes
314
- The `theme` prop for built-in themes
315
- Custom CSS overrides targeting Tippy.js selectors