0
# Tooltip System
1

2
Comprehensive tooltip components with link lists, messages, and notes for enhanced user interactions and contextual information display.
3

4
## Capabilities
5

6
### Core Tooltip Components
7

8
Higher-order components for wrapping elements with tooltip functionality.
9

10
```typescript { .api }
11
/**
12
 * Higher-order tooltip wrapper component (lazy-loaded)
13
 * Wraps child elements to show tooltips on hover/focus
14
 */
15
const WithTooltip: React.ComponentType<{
16
  /** Tooltip content */
17
  tooltip: React.ReactNode | string;
18
  /** Tooltip placement */
19
  placement?: 'top' | 'bottom' | 'left' | 'right';
20
  /** Child element to attach tooltip to */
21
  children: React.ReactElement;
22
  /** Additional tooltip options */
23
  [key: string]: any;
24
}>;
25

26
/**
27
 * Pure tooltip wrapper component without lazy loading
28
 * Direct implementation of tooltip functionality
29
 */
30
const WithTooltipPure: React.ComponentType<{
31
  /** Tooltip content */
32
  tooltip: React.ReactNode | string;
33
  /** Tooltip placement */
34
  placement?: 'top' | 'bottom' | 'left' | 'right';
35
  /** Child element to attach tooltip to */
36
  children: React.ReactElement;
37
  /** Trigger behavior */
38
  trigger?: 'hover' | 'click' | 'focus';
39
  /** Additional tooltip options */
40
  [key: string]: any;
41
}>;
42
```
43

44
### Tooltip Content Components
45

46
Specialized components for different types of tooltip content.
47

48
```typescript { .api }
49
/**
50
 * Tooltip message component for simple text content
51
 */
52
const TooltipMessage: React.ComponentType<{
53
  /** Message title */
54
  title?: string;
55
  /** Message description */
56
  desc?: string;
57
  /** Message content */
58
  children?: React.ReactNode;
59
}>;
60

61
/**
62
 * Tooltip note component for informational content
63
 */
64
const TooltipNote: React.ComponentType<{
65
  /** Note content */
66
  note: string | React.ReactNode;
67
  /** Additional styling */
68
  [key: string]: any;
69
}>;
70
```
71

72
### Tooltip Link List
73

74
Tooltip component that displays a list of clickable links or actions.
75

76
```typescript { .api }
77
interface NormalLink {
78
  /** Unique identifier for the link */
79
  id: string;
80
  /** Display title for the link */
81
  title: string;
82
  /** Optional href for navigation */
83
  href?: string;
84
  /** Click handler for actions */
85
  onClick?: (event: SyntheticEvent, item: Pick<NormalLink, 'id' | 'active' | 'disabled' | 'title' | 'href'>) => void;
86
  /** Icon to display with the link */
87
  icon?: React.ReactNode;
88
  /** Active state */
89
  active?: boolean;
90
  /** Disabled state */
91
  disabled?: boolean;
92
}
93

94
interface CustomLink {
95
  /** Unique identifier for the link */
96
  id: string;
97
  /** Custom content to render instead of standard link */
98
  content: React.ReactNode;
99
}
100

101
type Link = NormalLink | CustomLink;
102

103
/**
104
 * @deprecated Use Link instead. This will be removed in Storybook 9.0
105
 */
106
type TooltipLinkListLink = Link;
107

108
interface TooltipLinkListProps {
109
  /** Array of links to display, can be flat array or grouped array */
110
  links: Link[] | Link[][];
111
  /** Custom link wrapper component */
112
  LinkWrapper?: React.ComponentType;
113
}
114

115
/**
116
 * Tooltip component that displays a list of links or actions
117
 * Supports both flat arrays and grouped arrays of links
118
 */
119
const TooltipLinkList: React.ComponentType<TooltipLinkListProps>;
120
```
121

122
### List Item Component
123

124
Individual list item component for building custom tooltip content.
125

126
```typescript { .api }
127
/**
128
 * Individual list item component for custom tooltip lists
129
 * Exported as default export from the module
130
 */
131
const ListItem: React.ComponentType<{
132
  /** Item content */
133
  children: React.ReactNode;
134
  /** Click handler */
135
  onClick?: () => void;
136
  /** Active state */
137
  active?: boolean;
138
  /** Disabled state */
139
  disabled?: boolean;
140
  /** Additional props */
141
  [key: string]: any;
142
}>;
143
```
144

145
## Usage Examples
146

147
**Basic Tooltip Usage:**
148

149
```typescript
150
import { WithTooltip, Button } from "@storybook/components";
151

152
// Simple text tooltip
153
<WithTooltip tooltip="This is a helpful tooltip">
154
  <Button>Hover me</Button>
155
</WithTooltip>
156

157
// Tooltip with placement
158
<WithTooltip tooltip="Top tooltip" placement="top">
159
  <Button>Top tooltip</Button>
160
</WithTooltip>
161

162
<WithTooltip tooltip="Bottom tooltip" placement="bottom">
163
  <Button>Bottom tooltip</Button>
164
</WithTooltip>
165
```
166

167
**Pure Tooltip Component:**
168

169
```typescript
170
import { WithTooltipPure, IconButton } from "@storybook/components";
171

172
// Click-triggered tooltip
173
<WithTooltipPure 
174
  tooltip="Click tooltip content" 
175
  trigger="click"
176
  placement="right"
177
>
178
  <IconButton>
179
    Settings
180
  </IconButton>
181
</WithTooltipPure>
182
```
183

184
**Tooltip Message Component:**
185

186
```typescript
187
import { WithTooltip, TooltipMessage, Button } from "@storybook/components";
188

189
<WithTooltip
190
  tooltip={
191
    <TooltipMessage
192
      title="Feature Info"
193
      desc="This feature helps you manage your content more effectively."
194
    />
195
  }
196
>
197
  <Button>Info</Button>
198
</WithTooltip>
199
```
200

201
**Tooltip Note Component:**
202

203
```typescript
204
import { WithTooltip, TooltipNote, Badge } from "@storybook/components";
205

206
<WithTooltip
207
  tooltip={
208
    <TooltipNote note="This feature is currently in beta" />
209
  }
210
>
211
  <Badge>Beta</Badge>
212
</WithTooltip>
213
```
214

215
**Tooltip Link List:**
216

217
```typescript
218
import { WithTooltip, TooltipLinkList, Button } from "@storybook/components";
219

220
const menuLinks = [
221
  {
222
    id: 'edit',
223
    title: 'Edit Story',
224
    onClick: () => console.log('Edit clicked'),
225
    icon: <EditIcon />
226
  },
227
  {
228
    id: 'duplicate',
229
    title: 'Duplicate Story',
230
    onClick: () => console.log('Duplicate clicked'),
231
    icon: <DuplicateIcon />
232
  },
233
  {
234
    id: 'delete',
235
    title: 'Delete Story',
236
    onClick: () => console.log('Delete clicked'),
237
    icon: <DeleteIcon />,
238
    disabled: true
239
  },
240
  {
241
    id: 'docs',
242
    title: 'View Documentation',
243
    href: 'https://storybook.js.org',
244
    icon: <DocsIcon />
245
  }
246
];
247

248
<WithTooltip
249
  tooltip={<TooltipLinkList links={menuLinks} />}
250
  trigger="click"
251
  placement="bottom"
252
>
253
  <Button>Actions Menu</Button>
254
</WithTooltip>
255
```
256

257
**Custom List Item Usage:**
258

259
```typescript
260
import { WithTooltip, ListItem, Button } from "@storybook/components";
261

262
<WithTooltip
263
  tooltip={
264
    <div>
265
      <ListItem onClick={() => console.log('Item 1')} active={true}>
266
        Active Item
267
      </ListItem>
268
      <ListItem onClick={() => console.log('Item 2')}>
269
        Regular Item
270
      </ListItem>
271
      <ListItem disabled={true}>
272
        Disabled Item
273
      </ListItem>
274
    </div>
275
  }
276
  trigger="click"
277
>
278
  <Button>Custom Menu</Button>
279
</WithTooltip>
280
```
281

282
**Complex Tooltip Content:**
283

284
```typescript
285
import { 
286
  WithTooltip, 
287
  TooltipMessage, 
288
  TooltipLinkList, 
289
  Button,
290
  Separator 
291
} from "@storybook/components";
292

293
const complexTooltip = (
294
  <div>
295
    <TooltipMessage
296
      title="Story Actions"
297
      desc="Choose an action to perform on this story"
298
    />
299
    <Separator />
300
    <TooltipLinkList
301
      links={[
302
        { id: 'view', title: 'View Story', onClick: () => {} },
303
        { id: 'edit', title: 'Edit Story', onClick: () => {} },
304
        { id: 'share', title: 'Share Story', onClick: () => {} }
305
      ]}
306
    />
307
  </div>
308
);
309

310
<WithTooltip tooltip={complexTooltip} placement="right">
311
  <Button>Story Menu</Button>
312
</WithTooltip>
313
```
314

315
## Tooltip Positioning
316

317
Tooltips support four main placement options:
318

319
- `top` - Tooltip appears above the trigger element
320
- `bottom` - Tooltip appears below the trigger element  
321
- `left` - Tooltip appears to the left of the trigger element
322
- `right` - Tooltip appears to the right of the trigger element
323

324
The tooltip system automatically adjusts positioning based on available space and viewport boundaries.
325

326
## Integration Notes
327

328
The tooltip system integrates with Storybook's theming and works seamlessly with all other components. Tooltips are optimized for both mouse and keyboard interactions, supporting proper accessibility patterns including ARIA attributes and focus management.
329

330
The `WithTooltip` component uses lazy loading to optimize bundle size, while `WithTooltipPure` provides immediate availability for performance-critical scenarios.