0
# Radix UI React Tooltip
1

2
Radix UI React Tooltip provides a comprehensive, accessible tooltip component system for React applications. It features sophisticated hover behavior, keyboard navigation, portal rendering, and full ARIA compliance through a compound component pattern.
3

4
## Package Information
5

6
- **Package Name**: @radix-ui/react-tooltip
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @radix-ui/react-tooltip`
10

11
## Core Imports
12

13
```typescript
14
import {
15
  createTooltipScope,
16
  TooltipProvider,
17
  Tooltip,
18
  TooltipTrigger,
19
  TooltipPortal,
20
  TooltipContent,
21
  TooltipArrow,
22
} from "@radix-ui/react-tooltip";
23
```
24

25
Alternative short aliases:
26

27
```typescript
28
import {
29
  Provider,
30
  Root,
31
  Trigger,
32
  Portal,
33
  Content,
34
  Arrow,
35
} from "@radix-ui/react-tooltip";
36
```
37

38
For TypeScript types:
39

40
```typescript
41
import type {
42
  TooltipProviderProps,
43
  TooltipProps,
44
  TooltipTriggerProps,
45
  TooltipPortalProps,
46
  TooltipContentProps,
47
  TooltipArrowProps,
48
} from "@radix-ui/react-tooltip";
49
```
50

51
## Basic Usage
52

53
```typescript
54
import {
55
  TooltipProvider,
56
  Tooltip,
57
  TooltipTrigger,
58
  TooltipPortal,
59
  TooltipContent,
60
  TooltipArrow,
61
} from "@radix-ui/react-tooltip";
62

63
function MyComponent() {
64
  return (
65
    <TooltipProvider>
66
      <Tooltip>
67
        <TooltipTrigger asChild>
68
          <button>Hover me</button>
69
        </TooltipTrigger>
70
        <TooltipPortal>
71
          <TooltipContent side="top">
72
            This is a tooltip!
73
            <TooltipArrow />
74
          </TooltipContent>
75
        </TooltipPortal>
76
      </Tooltip>
77
    </TooltipProvider>
78
  );
79
}
80
```
81

82
## Architecture
83

84
Radix UI React Tooltip uses a compound component pattern with hierarchical structure:
85

86
- **Provider Layer**: `TooltipProvider` manages global tooltip behavior and timing
87
- **Tooltip Instance**: `Tooltip` manages individual tooltip state and controls
88
- **Interaction Layer**: `TooltipTrigger` handles user interactions (hover, focus, keyboard)
89
- **Portal Layer**: `TooltipPortal` renders content outside normal DOM flow
90
- **Content Layer**: `TooltipContent` provides the visible tooltip with positioning and accessibility
91
- **Visual Enhancement**: `TooltipArrow` adds directional pointer to tooltip
92

93
Key design patterns:
94
- **Context-based state management** for component communication
95
- **Portal rendering** for z-index and positioning control
96
- **Sophisticated hover mechanics** with grace areas for smooth user experience  
97
- **Controlled/uncontrolled state patterns** for flexible integration
98
- **Accessibility-first design** with ARIA compliance and keyboard navigation
99

100
## Capabilities
101

102
### Provider Configuration
103

104
Global tooltip provider that manages timing, delays, and hover behavior across all tooltips in your application.
105

106
```typescript { .api }
107
interface TooltipProviderProps {
108
  children: React.ReactNode;
109
  delayDuration?: number;
110
  skipDelayDuration?: number;
111
  disableHoverableContent?: boolean;
112
}
113

114
const TooltipProvider: React.FC<TooltipProviderProps>;
115
```
116

117
[Provider Configuration](./provider.md)
118

119
### Tooltip Root Management
120

121
Individual tooltip instance that manages open/closed state, timing, and accessibility features.
122

123
```typescript { .api }
124
interface TooltipProps {
125
  children?: React.ReactNode;
126
  open?: boolean;
127
  defaultOpen?: boolean;
128
  onOpenChange?: (open: boolean) => void;
129
  delayDuration?: number;
130
  disableHoverableContent?: boolean;
131
}
132

133
const Tooltip: React.FC<TooltipProps>;
134
```
135

136
[Tooltip Root Management](./tooltip-root.md)
137

138
### Trigger Interaction
139

140
Interactive trigger element that responds to hover, focus, and keyboard events to show/hide tooltips.
141

142
```typescript { .api }
143
type TooltipTriggerElement = React.ComponentRef<"button">;
144
interface TooltipTriggerProps extends React.ComponentPropsWithoutRef<"button"> {
145
  asChild?: boolean;
146
}
147

148
const TooltipTrigger: React.forwardRef<TooltipTriggerElement, TooltipTriggerProps>;
149
```
150

151
[Trigger Interaction](./trigger.md)
152

153
### Portal Rendering and Content Display
154

155
Portal component for rendering tooltip content outside the normal DOM hierarchy, plus the main content component with positioning and accessibility features.
156

157
```typescript { .api }
158
interface TooltipPortalProps {
159
  children?: React.ReactNode;
160
  container?: HTMLElement;
161
  forceMount?: true;
162
}
163

164
interface TooltipContentProps {
165
  forceMount?: true;
166
  side?: "top" | "right" | "bottom" | "left";
167
  sideOffset?: number;
168
  align?: "start" | "center" | "end";
169
  alignOffset?: number;
170
  avoidCollisions?: boolean;
171
  collisionBoundary?: Element | Element[];
172
  collisionPadding?: number | Partial<Record<"top" | "right" | "bottom" | "left", number>>;
173
  arrowPadding?: number;
174
  sticky?: "partial" | "always";
175
  hideWhenDetached?: boolean;
176
  'aria-label'?: string;
177
  onEscapeKeyDown?: (event: KeyboardEvent) => void;
178
  onPointerDownOutside?: (event: CustomEvent) => void;
179
}
180

181
const TooltipPortal: React.FC<TooltipPortalProps>;
182
const TooltipContent: React.forwardRef<HTMLDivElement, TooltipContentProps>;
183
```
184

185
[Portal Rendering and Content Display](./portal-content.md)
186

187
### Arrow and Visual Enhancement
188

189
Optional arrow/pointer component that visually connects the tooltip to its trigger.
190

191
```typescript { .api }
192
interface TooltipArrowProps {
193
  width?: number;
194
  height?: number;
195
  offset?: number;
196
}
197

198
const TooltipArrow: React.forwardRef<SVGSVGElement, TooltipArrowProps>;
199
```
200

201
[Arrow and Visual Enhancement](./arrow.md)
202

203
### Utility Functions
204

205
Context scoping utilities for advanced tooltip customization and nesting scenarios.
206

207
```typescript { .api }
208
function createTooltipScope(): Scope;
209
```
210

211
[Utility Functions](./utilities.md)
212

213
## Types
214

215
```typescript { .api }
216
type TooltipProviderProps = {
217
  children: React.ReactNode;
218
  delayDuration?: number;
219
  skipDelayDuration?: number; 
220
  disableHoverableContent?: boolean;
221
};
222

223
type TooltipProps = {
224
  children?: React.ReactNode;
225
  open?: boolean;
226
  defaultOpen?: boolean;
227
  onOpenChange?: (open: boolean) => void;
228
  delayDuration?: number;
229
  disableHoverableContent?: boolean;
230
};
231

232
type TooltipTriggerProps = React.ComponentPropsWithoutRef<"button"> & {
233
  asChild?: boolean;
234
};
235

236
type TooltipPortalProps = {
237
  children?: React.ReactNode;
238
  container?: HTMLElement;
239
  forceMount?: true;
240
};
241

242
type TooltipContentProps = React.ComponentPropsWithoutRef<"div"> & {
243
  forceMount?: true;
244
  side?: "top" | "right" | "bottom" | "left";
245
  sideOffset?: number;
246
  align?: "start" | "center" | "end";
247
  alignOffset?: number;
248
  avoidCollisions?: boolean;
249
  collisionBoundary?: Element | Element[];
250
  collisionPadding?: number | Partial<Record<"top" | "right" | "bottom" | "left", number>>;
251
  arrowPadding?: number;
252
  sticky?: "partial" | "always";
253
  hideWhenDetached?: boolean;
254
  'aria-label'?: string;
255
  onEscapeKeyDown?: (event: KeyboardEvent) => void;
256
  onPointerDownOutside?: (event: CustomEvent) => void;
257
};
258

259
type TooltipArrowProps = React.ComponentPropsWithoutRef<"svg"> & {
260
  width?: number;
261
  height?: number;
262
  offset?: number;
263
};
264
```