0
# Utility Functions
1

2
The tooltip system provides utility functions for advanced scenarios, including context scoping for nested tooltips and complex component hierarchies.
3

4
## Capabilities
5

6
### Context Scoping
7

8
Create scoped contexts for tooltip components to enable nesting and avoid conflicts.
9

10
```typescript { .api }
11
/**
12
 * Creates a scoped context for tooltip components
13
 * Enables nesting tooltips and avoiding context conflicts
14
 * @returns Scope object for scoped tooltip components
15
 */
16
function createTooltipScope(): Scope;
17

18
type Scope = {
19
  [scopeName: string]: React.Context<any>[];
20
};
21
```
22

23
**Usage Examples:**
24

25
```typescript
26
import { createTooltipScope, TooltipProvider, Tooltip } from "@radix-ui/react-tooltip";
27

28
// Basic scoped tooltips
29
function ScopedTooltips() {
30
  const scope = createTooltipScope();
31
  
32
  return (
33
    <TooltipProvider __scopeTooltip={scope}>
34
      <Tooltip __scopeTooltip={scope}>
35
        {/* This tooltip uses scoped context */}
36
      </Tooltip>
37
    </TooltipProvider>
38
  );
39
}
40

41
// Nested tooltip scenarios
42
function NestedTooltipExample() {
43
  const outerScope = createTooltipScope();
44
  const innerScope = createTooltipScope();
45
  
46
  return (
47
    <TooltipProvider __scopeTooltip={outerScope}>
48
      <Tooltip __scopeTooltip={outerScope}>
49
        <TooltipTrigger __scopeTooltip={outerScope}>
50
          Outer tooltip trigger
51
        </TooltipTrigger>
52
        <TooltipPortal __scopeTooltip={outerScope}>
53
          <TooltipContent __scopeTooltip={outerScope}>
54
            Outer tooltip content
55
            
56
            {/* Inner scoped tooltip */}
57
            <TooltipProvider __scopeTooltip={innerScope}>
58
              <Tooltip __scopeTooltip={innerScope}>
59
                <TooltipTrigger __scopeTooltip={innerScope}>
60
                  Inner trigger
61
                </TooltipTrigger>
62
                <TooltipPortal __scopeTooltip={innerScope}>
63
                  <TooltipContent __scopeTooltip={innerScope}>
64
                    Inner tooltip content
65
                  </TooltipContent>
66
                </TooltipPortal>
67
              </Tooltip>
68
            </TooltipProvider>
69
          </TooltipContent>
70
        </TooltipPortal>
71
      </Tooltip>
72
    </TooltipProvider>
73
  );
74
}
75

76
// Component library with scoped tooltips
77
function ComponentLibrary() {
78
  const libraryScope = createTooltipScope();
79
  
80
  return (
81
    <div className="library-wrapper">
82
      <TooltipProvider 
83
        __scopeTooltip={libraryScope}
84
        delayDuration={500}
85
      >
86
        {/* All tooltips in this library use scoped context */}
87
        <LibraryComponent scope={libraryScope} />
88
        <AnotherLibraryComponent scope={libraryScope} />
89
      </TooltipProvider>
90
    </div>
91
  );
92
}
93

94
function LibraryComponent({ scope }) {
95
  return (
96
    <Tooltip __scopeTooltip={scope}>
97
      <TooltipTrigger __scopeTooltip={scope}>
98
        Library component
99
      </TooltipTrigger>
100
      <TooltipPortal __scopeTooltip={scope}>
101
        <TooltipContent __scopeTooltip={scope}>
102
          Scoped tooltip for library
103
        </TooltipContent>
104
      </TooltipPortal>
105
    </Tooltip>
106
  );
107
}
108
```
109

110
### Scope Usage Patterns
111

112
#### Nested Tooltips
113

114
Use scoping when tooltips need to be nested within each other:
115

116
```typescript
117
// Each level gets its own scope
118
const level1Scope = createTooltipScope();
119
const level2Scope = createTooltipScope();
120
const level3Scope = createTooltipScope();
121
```
122

123
#### Component Library Isolation
124

125
Use scoping to isolate tooltip behavior in reusable components:
126

127
```typescript
128
// Library creates its own scope
129
function MyLibraryProvider({ children }) {
130
  const libraryScope = createTooltipScope();
131
  
132
  return (
133
    <TooltipProvider __scopeTooltip={libraryScope}>
134
      {React.Children.map(children, child => 
135
        React.cloneElement(child, { __scopeTooltip: libraryScope })
136
      )}
137
    </TooltipProvider>
138
  );
139
}
140
```
141

142
#### Multi-Instance Applications
143

144
Use scoping when multiple independent tooltip systems exist:
145

146
```typescript
147
function MultiInstanceApp() {
148
  const headerScope = createTooltipScope();
149
  const sidebarScope = createTooltipScope();
150
  const contentScope = createTooltipScope();
151
  
152
  return (
153
    <div>
154
      <Header tooltipScope={headerScope} />
155
      <Sidebar tooltipScope={sidebarScope} />
156
      <Content tooltipScope={contentScope} />
157
    </div>
158
  );
159
}
160
```
161

162
### Scope Properties
163

164
#### Context Isolation
165

166
Each scope creates isolated context that:
167
- Prevents provider/consumer mismatches across different tooltip hierarchies
168
- Allows independent configuration for different tooltip groups
169
- Enables safe nesting without context conflicts
170

171
#### Provider Independence
172

173
Scoped tooltips maintain independent:
174
- **Delay timers**: Each scope has its own delay state
175
- **Hover behavior**: Independent hover and grace area handling
176
- **Configuration**: Separate delay durations and settings
177
- **Event handling**: Isolated open/close event coordination
178

179
### Advanced Scoping
180

181
#### Scope Composition
182

183
Scopes can be composed for complex hierarchies:
184

185
```typescript
186
function ComplexApp() {
187
  const appScope = createTooltipScope();
188
  const modalScope = createTooltipScope();
189
  
190
  return (
191
    <TooltipProvider __scopeTooltip={appScope}>
192
      {/* App-level tooltips */}
193
      <AppTooltips scope={appScope} />
194
      
195
      <Modal>
196
        <TooltipProvider __scopeTooltip={modalScope}>
197
          {/* Modal-level tooltips */}
198
          <ModalTooltips scope={modalScope} />
199
        </TooltipProvider>
200
      </Modal>
201
    </TooltipProvider>
202
  );
203
}
204
```
205

206
#### Dynamic Scoping
207

208
Scopes can be created dynamically:
209

210
```typescript
211
function DynamicTooltips() {
212
  const [scopes] = useState(() => ({
213
    primary: createTooltipScope(),
214
    secondary: createTooltipScope(),
215
  }));
216
  
217
  return (
218
    <div>
219
      <Section scope={scopes.primary} />
220
      <Section scope={scopes.secondary} />
221
    </div>
222
  );
223
}
224
```
225

226
### Scope Integration
227

228
All tooltip components accept the `__scopeTooltip` prop:
229

230
- `TooltipProvider`
231
- `Tooltip` 
232
- `TooltipTrigger`
233
- `TooltipPortal`
234
- `TooltipContent`
235
- `TooltipArrow`
236

237
When using scopes, ensure all related components use the same scope object.
238

239
## Types
240

241
```typescript { .api }
242
type Scope = {
243
  [scopeName: string]: React.Context<any>[];
244
};
245

246
type ScopedProps<P = {}> = P & { 
247
  __scopeTooltip?: Scope;
248
};
249
```