0
# Main Tooltip Component
1

2
The primary tooltip component providing comprehensive tooltip functionality with extensive customization options, accessibility features, and both declarative and imperative APIs.
3

4
## Capabilities
5

6
### Tooltip Component
7

8
Main tooltip component with full feature set including positioning, styling, events, and accessibility.
9

10
```typescript { .api }
11
/**
12
 * Main tooltip component providing comprehensive tooltip functionality
13
 * @param props - Configuration options for the tooltip
14
 * @returns React component with forwardRef support
15
 */
16
function Tooltip(props: ITooltipController): React.ReactElement;
17

18
interface ITooltipController {
19
  /** Unique identifier for the tooltip (required) */
20
  id?: string;
21
  /** CSS class name for the tooltip container */
22
  className?: string;
23
  /** CSS class name for the tooltip arrow */
24
  classNameArrow?: string;
25
  /** Text content for the tooltip */
26
  content?: string;
27
  /** HTML content (deprecated, use children or render instead) */
28
  html?: string;
29
  /** Custom render function for dynamic content */
30
  render?: (render: { content: string | null; activeAnchor: HTMLElement | null }) => ChildrenType;
31
  /** Tooltip placement position */
32
  place?: PlacesType;
33
  /** Distance from anchor element in pixels */
34
  offset?: number;
35
  /** Visual theme variant */
36
  variant?: VariantType;
37
  /** CSS selector for anchor elements */
38
  anchorSelect?: string;
39
  /** ID of anchor element (deprecated, use anchorSelect or data-tooltip-id) */
40
  anchorId?: string;
41
  /** HTML wrapper element type */
42
  wrapper?: WrapperType;
43
  /** React children content */
44
  children?: ChildrenType;
45
  /** Event types to trigger tooltip (deprecated, use openEvents/closeEvents) */
46
  events?: EventsType[];
47
  /** Open tooltip on click instead of hover */
48
  openOnClick?: boolean;
49
  /** Positioning strategy: absolute or fixed */
50
  positionStrategy?: PositionStrategy;
51
  /** Floating UI middleware for advanced positioning */
52
  middlewares?: Middleware[];
53
  /** Delay before showing tooltip in milliseconds */
54
  delayShow?: number;
55
  /** Delay before hiding tooltip in milliseconds */
56
  delayHide?: number;
57
  /** Allow tooltip to float and follow cursor */
58
  float?: boolean;
59
  /** Hide tooltip completely */
60
  hidden?: boolean;
61
  /** Disable arrow display */
62
  noArrow?: boolean;
63
  /** Allow tooltip content to be clickable */
64
  clickable?: boolean;
65
  /** Close on Escape key (deprecated, use globalCloseEvents) */
66
  closeOnEsc?: boolean;
67
  /** Close on scroll (deprecated, use globalCloseEvents) */
68
  closeOnScroll?: boolean;
69
  /** Close on window resize (deprecated, use globalCloseEvents) */
70
  closeOnResize?: boolean;
71
  /** Events to open tooltip on anchor elements */
72
  openEvents?: AnchorOpenEvents;
73
  /** Events to close tooltip on anchor elements */
74
  closeEvents?: AnchorCloseEvents;  
75
  /** Global events that close the tooltip */
76
  globalCloseEvents?: GlobalCloseEvents;
77
  /** Disable default behavior for manual control only */
78
  imperativeModeOnly?: boolean;
79
  /** Inline CSS styles */
80
  style?: CSSProperties;
81
  /** Fixed position coordinates */
82
  position?: IPosition;
83
  /** Controlled open state */
84
  isOpen?: boolean;
85
  /** Default open state for uncontrolled usage */
86
  defaultIsOpen?: boolean;
87
  /** Disable CSS injection (true, false, or 'core') */
88
  disableStyleInjection?: boolean | 'core';
89
  /** Border styling (width > 3px may break arrow positioning) */
90
  border?: CSSProperties['border'];
91
  /** Tooltip opacity */
92
  opacity?: CSSProperties['opacity'];
93
  /** Arrow background color */
94
  arrowColor?: CSSProperties['backgroundColor'];
95
  /** Arrow size in pixels */
96
  arrowSize?: number;
97
  /** State setter function for controlled usage */
98
  setIsOpen?: (value: boolean) => void;
99
  /** Callback after tooltip shows */
100
  afterShow?: () => void;
101
  /** Callback after tooltip hides */
102
  afterHide?: () => void;
103
  /** Function to conditionally disable tooltip */
104
  disableTooltip?: (anchorRef: HTMLElement | null) => boolean;
105
  /** ARIA role for accessibility */
106
  role?: React.AriaRole;
107
}
108
```
109

110
**Usage Examples:**
111

112
```typescript
113
import { Tooltip } from "react-tooltip";
114

115
// Basic declarative usage
116
<div>
117
  <button data-tooltip-id="basic" data-tooltip-content="Basic tooltip">
118
    Hover me
119
  </button>
120
  <Tooltip id="basic" />
121
</div>
122

123
// Advanced configuration
124
<div>
125
  <button data-tooltip-id="advanced" data-tooltip-content="Advanced tooltip">
126
    Hover me  
127
  </button>
128
  <Tooltip 
129
    id="advanced"
130
    place="top"
131
    variant="success"
132
    offset={15}
133
    delayShow={500}
134
    delayHide={200}
135
    clickable
136
    noArrow
137
    style={{ fontSize: '14px' }}
138
  />
139
</div>
140

141
// Custom content with render function
142
<div>
143
  <span data-tooltip-id="custom">Custom content</span>
144
  <Tooltip 
145
    id="custom"
146
    render={({ content, activeAnchor }) => (
147
      <div>
148
        <strong>{content}</strong>
149
        <br />
150
        <small>Element: {activeAnchor?.tagName}</small>
151
      </div>
152
    )}
153
  />
154
</div>
155
```
156

157
### Imperative API
158

159
Access tooltip methods programmatically using React refs.
160

161
```typescript { .api }
162
/**
163
 * Ref interface for programmatic tooltip control
164
 */
165
interface TooltipRefProps {
166
  /** Programmatically open the tooltip */
167
  open: (options?: TooltipImperativeOpenOptions) => void;
168
  /** Programmatically close the tooltip */  
169
  close: (options?: TooltipImperativeCloseOptions) => void;
170
  /** Currently active anchor element (readonly) */
171
  readonly activeAnchor: HTMLElement | null;
172
  /** Current placement position (readonly) */
173
  readonly place: PlacesType;
174
  /** Current open state (readonly) */
175
  readonly isOpen: boolean;
176
}
177

178
interface TooltipImperativeOpenOptions {
179
  /** CSS selector for anchor elements */
180
  anchorSelect?: string;
181
  /** Fixed position coordinates */
182
  position?: IPosition;
183
  /** Placement position */
184
  place?: PlacesType;
185
  /** Content to display */
186
  content?: ChildrenType;
187
  /** Delay before opening in milliseconds */
188
  delay?: number;
189
}
190

191
interface TooltipImperativeCloseOptions {
192
  /** Delay before closing in milliseconds */
193
  delay?: number;
194
}
195
```
196

197
**Usage Examples:**
198

199
```typescript
200
import { useRef } from 'react';
201
import { Tooltip, type TooltipRefProps } from 'react-tooltip';
202

203
function MyComponent() {
204
  const tooltipRef = useRef<TooltipRefProps>(null);
205
  
206
  const handleShowTooltip = () => {
207
    tooltipRef.current?.open({
208
      anchorSelect: '#my-button',
209
      content: 'Programmatically opened!',
210
      place: 'top'
211
    });
212
  };
213
  
214
  const handleHideTooltip = () => {
215
    tooltipRef.current?.close({ delay: 1000 });
216
  };
217
  
218
  return (
219
    <div>
220
      <button id="my-button">Target Element</button>
221
      <button onClick={handleShowTooltip}>Show Tooltip</button>
222
      <button onClick={handleHideTooltip}>Hide Tooltip</button>
223
      
224
      <Tooltip 
225
        id="imperative-tooltip"
226
        ref={tooltipRef}
227
        imperativeModeOnly
228
      />
229
    </div>
230
  );
231
}
232
```
233

234
## Event Configuration
235

236
### Anchor Events
237

238
Events that trigger tooltip actions on anchor elements.
239

240
```typescript { .api }
241
interface AnchorOpenEvents {
242
  mouseenter?: boolean;
243
  focus?: boolean;
244
  mouseover?: boolean;
245
  click?: boolean;
246
  dblclick?: boolean;
247
  mousedown?: boolean;
248
}
249

250
interface AnchorCloseEvents {
251
  mouseleave?: boolean;
252
  blur?: boolean;
253
  mouseout?: boolean;
254
  click?: boolean;
255
  dblclick?: boolean;
256
  mouseup?: boolean;
257
}
258
```
259

260
### Global Events
261

262
Global events that close the tooltip regardless of anchor element.
263

264
```typescript { .api }
265
interface GlobalCloseEvents {
266
  escape?: boolean;
267
  scroll?: boolean;
268
  resize?: boolean;
269
  clickOutsideAnchor?: boolean;
270
}
271
```
272

273
**Usage Examples:**
274

275
```typescript
276
// Custom event configuration
277
<Tooltip 
278
  id="custom-events"
279
  openEvents={{ click: true, focus: true }}
280
  closeEvents={{ blur: true }}
281
  globalCloseEvents={{ escape: true, clickOutsideAnchor: true }}
282
/>
283

284
// Click-to-toggle behavior
285
<Tooltip 
286
  id="click-toggle"
287
  openEvents={{ click: true }}
288
  closeEvents={{ click: true }}
289
  globalCloseEvents={{ clickOutsideAnchor: true }}
290
/>
291
```
292

293
## Data Attributes
294

295
HTML data attributes for declarative tooltip configuration on anchor elements.
296

297
```typescript { .api }
298
// Extended HTMLAttributes interface
299
interface HTMLAttributes<T> {
300
  'data-tooltip-id'?: string;
301
  'data-tooltip-place'?: PlacesType;
302
  'data-tooltip-content'?: string | null;
303
  'data-tooltip-html'?: string | null;
304
  'data-tooltip-variant'?: VariantType;
305
  'data-tooltip-offset'?: number;
306
  'data-tooltip-wrapper'?: WrapperType;
307
  'data-tooltip-events'?: EventsType[];
308
  'data-tooltip-position-strategy'?: PositionStrategy;
309
  'data-tooltip-delay-show'?: number;
310
  'data-tooltip-delay-hide'?: number;
311
  'data-tooltip-float'?: boolean;
312
  'data-tooltip-hidden'?: boolean;
313
  'data-tooltip-class-name'?: string;
314
}
315
```
316

317
**Usage Examples:**
318

319
```html
320
<!-- Basic data attributes -->
321
<button 
322
  data-tooltip-id="data-example"
323
  data-tooltip-content="Hello from data attributes!"
324
  data-tooltip-place="bottom"
325
  data-tooltip-variant="success"
326
>
327
  Hover me
328
</button>
329

330
<!-- Advanced data attributes -->
331
<span
332
  data-tooltip-id="advanced-data"
333
  data-tooltip-content="Advanced configuration"
334
  data-tooltip-delay-show="500"
335
  data-tooltip-delay-hide="200"
336
  data-tooltip-offset="15"
337
  data-tooltip-class-name="custom-tooltip"
338
>
339
  Advanced example
340
</span>
341
```
342

343
## Helper Types
344

345
```typescript { .api }
346
type WrapperType = ElementType | 'div' | 'span';
347
type ChildrenType = Element | ElementType | ReactNode;
348
type Middleware = any; // Floating UI middleware type
349
```