0
# Hint System
1

2
Contextual tooltip system for providing on-demand help and feature discovery. The Hint class enables creation of interactive help hints that users can click to reveal additional information.
3

4
## Capabilities
5

6
### Hint Creation
7

8
Create a new Hint instance with optional target element and configuration options.
9

10
```typescript { .api }
11
/**
12
 * Create a new Hint instance
13
 * @param elementOrSelector - Optional target element or CSS selector for hints
14
 * @param options - Optional Hint configuration options
15
 */
16
new Hint(elementOrSelector?: string | HTMLElement, options?: Partial<HintOptions>): Hint;
17

18
/**
19
 * Create Hint instance via static method (recommended)
20
 * @param elementOrSelector - Optional target element or CSS selector
21
 */
22
introJs.hint(elementOrSelector?: string | HTMLElement): Hint;
23
```
24

25
**Usage Examples:**
26

27
```javascript
28
import introJs from "intro.js";
29

30
// Create hint instance for entire document
31
const hint = introJs.hint();
32

33
// Create hint instance for specific container
34
const hint = introJs.hint("#main-content");
35

36
// Create hint instance with initial options
37
const hint = introJs.hint(document.body, {
38
  hintPosition: "top-middle",
39
  hintAnimation: true,
40
  hintAutoRefreshInterval: 100
41
});
42
```
43

44
### Hint Rendering and Lifecycle
45

46
Control hint visibility and lifecycle with rendering and destruction methods.
47

48
```typescript { .api }
49
/**
50
 * Render hints on the page
51
 */
52
render(): Promise<Hint>;
53

54
/**
55
 * Destroy and remove all hint elements from the page
56
 */
57
destroy(): Hint;
58

59
/**
60
 * Check if hints are currently rendered
61
 */
62
isRendered(): boolean;
63

64
/**
65
 * Check if the hint instance is active
66
 */
67
isActive(): boolean;
68

69
/**
70
 * Refresh hints on the page (updates positioning)
71
 */
72
refresh(): Hint;
73
```
74

75
**Usage Examples:**
76

77
```javascript
78
import introJs from "intro.js";
79

80
const hint = introJs.hint();
81

82
// Add some hints
83
hint.addHint({
84
  element: "#help-button",
85
  hint: "Click for help and support",
86
  hintPosition: "top-middle"
87
});
88

89
// Render hints on the page
90
await hint.render();
91

92
// Check if rendered
93
if (hint.isRendered()) {
94
  console.log("Hints are visible");
95
}
96

97
// Clean up when done
98
hint.destroy();
99
```
100

101
### Hint Management
102

103
Add, retrieve, and remove individual hints or collections of hints.
104

105
```typescript { .api }
106
/**
107
 * Add a single hint item
108
 * @param hint - Hint configuration object
109
 */
110
addHint(hint: HintItem): Hint;
111

112
/**
113
 * Set all hint items, replacing existing ones
114
 * @param hints - Array of hint items
115
 */
116
setHints(hints: HintItem[]): Hint;
117

118
/**
119
 * Get all hint items
120
 */
121
getHints(): HintItem[];
122

123
/**
124
 * Get a specific hint item by step ID
125
 * @param stepId - The hint step ID
126
 */
127
getHint(stepId: number): HintItem | undefined;
128

129
/**
130
 * Remove a single hint element by step ID
131
 * @param stepId - The hint step ID to remove
132
 */
133
removeHint(stepId: number): Hint;
134
```
135

136
**Usage Examples:**
137

138
```javascript
139
import introJs from "intro.js";
140

141
const hint = introJs.hint();
142

143
// Add individual hints
144
hint.addHint({
145
  element: "#save-button",
146
  hint: "Save your changes",
147
  hintPosition: "bottom-middle"
148
});
149

150
hint.addHint({
151
  element: "#settings-icon",
152
  hint: "Open settings panel",
153
  hintPosition: "top-left",
154
  hintAnimation: false
155
});
156

157
// Add multiple hints at once
158
hint.setHints([
159
  {
160
    element: "#profile-menu",
161
    hint: "Access your profile and account settings",
162
    hintPosition: "bottom-right"
163
  },
164
  {
165
    element: "#notification-bell",
166
    hint: "View your latest notifications",
167
    hintPosition: "bottom-middle"
168
  }
169
]);
170

171
await hint.render();
172
```
173

174
### Hint Visibility Control
175

176
Show and hide individual hints or all hints programmatically.
177

178
```typescript { .api }
179
/**
180
 * Show a specific hint on the page
181
 * @param stepId - The hint step ID
182
 */
183
showHint(stepId: number): Hint;
184

185
/**
186
 * Show all hints on the page
187
 */
188
showHints(): Promise<Hint>;
189

190
/**
191
 * Hide a specific hint on the page
192
 * @param stepId - The hint step ID
193
 */
194
hideHint(stepId: number): Promise<Hint>;
195

196
/**
197
 * Hide all hints on the page
198
 */
199
hideHints(): Promise<Hint>;
200
```
201

202
**Usage Examples:**
203

204
```javascript
205
import introJs from "intro.js";
206

207
const hint = introJs.hint()
208
  .addHint({
209
    element: "#feature-1",
210
    hint: "This is feature 1"
211
  })
212
  .addHint({
213
    element: "#feature-2", 
214
    hint: "This is feature 2"
215
  });
216

217
await hint.render();
218

219
// Show/hide specific hints
220
hint.showHint(0);  // Show first hint
221
await hint.hideHint(1);  // Hide second hint
222

223
// Show/hide all hints
224
await hint.showHints();  // Show all hints
225
await hint.hideHints();  // Hide all hints
226
```
227

228
### Hint Dialog Control
229

230
Control hint dialog visibility for detailed hint content display.
231

232
```typescript { .api }
233
/**
234
 * Show hint dialog for a specific hint
235
 * @param stepId - The hint step ID
236
 */
237
showHintDialog(stepId: number): Promise<Hint>;
238

239
/**
240
 * Hide hint dialog from the page
241
 */
242
hideHintDialog(): Hint;
243
```
244

245
**Usage Examples:**
246

247
```javascript
248
import introJs from "intro.js";
249

250
const hint = introJs.hint()
251
  .addHint({
252
    element: "#complex-feature",
253
    hint: "This feature has detailed options and settings available.",
254
    hintPosition: "top-middle"
255
  });
256

257
await hint.render();
258

259
// Show dialog for specific hint
260
await hint.showHintDialog(0);
261

262
// Hide dialog
263
hint.hideHintDialog();
264
```
265

266
### Options Management
267

268
Configure hint behavior, appearance, and interaction patterns.
269

270
```typescript { .api }
271
/**
272
 * Set multiple hint options
273
 * @param partialOptions - Object containing option key-value pairs
274
 */
275
setOptions(partialOptions: Partial<HintOptions>): Hint;
276

277
/**
278
 * Set a single hint option
279
 * @param key - Option key
280
 * @param value - Option value
281
 */
282
setOption<K extends keyof HintOptions>(key: K, value: HintOptions[K]): Hint;
283

284
/**
285
 * Get a specific hint option value
286
 * @param key - Option key
287
 */
288
getOption<K extends keyof HintOptions>(key: K): HintOptions[K];
289
```
290

291
**Usage Examples:**
292

293
```javascript
294
import introJs from "intro.js";
295

296
const hint = introJs.hint();
297

298
// Set multiple options
299
hint.setOptions({
300
  hintPosition: "top-middle",
301
  hintAnimation: true,
302
  hintAutoRefreshInterval: 50,
303
  hintButtonLabel: "Got it!"
304
});
305

306
// Set individual option
307
hint.setOption("hintShowButton", false);
308

309
// Get option value
310
const position = hint.getOption("hintPosition");
311
```
312

313
### Event Management
314

315
Control hint event handling including auto-refresh and dialog interaction.
316

317
```typescript { .api }
318
/**
319
 * Enable hint auto-refresh on page scroll and resize
320
 */
321
enableHintAutoRefresh(): Hint;
322

323
/**
324
 * Disable hint auto-refresh on page scroll and resize
325
 */
326
disableHintAutoRefresh(): Hint;
327

328
/**
329
 * Enable closing dialog when user clicks outside the hint
330
 */
331
enableCloseDialogOnWindowClick(): void;
332

333
/**
334
 * Disable closing dialog when user clicks outside the hint
335
 */
336
disableCloseDialogOnWindowClick(): void;
337
```
338

339
### Utility Methods
340

341
Additional utility methods for hint management and customization.
342

343
```typescript { .api }
344
/**
345
 * Clone the hint instance
346
 */
347
clone(): Hint;
348

349
/**
350
 * Get the target element for hints
351
 */
352
getTargetElement(): HTMLElement;
353

354
/**
355
 * Get specific callback function
356
 * @param callbackName - The name of the callback
357
 */
358
callback<K extends keyof HintCallbacks>(callbackName: K): HintCallbacks[K] | undefined;
359
```
360

361
### Hint Item Interface
362

363
Complete interface for defining hint items with all available options.
364

365
```typescript { .api }
366
interface HintItem {
367
  /** Target element for the hint */
368
  element?: HTMLElement | string | null;
369
  /** Hint content text */
370
  hint?: string;
371
  /** Position of the hint icon relative to the target element */
372
  hintPosition: HintPosition;
373
  /** Position of the tooltip when hint is clicked */
374
  position: TooltipPosition;
375
  /** Custom CSS class for the hint tooltip */
376
  tooltipClass?: string;
377
  /** Whether to animate the hint icon */
378
  hintAnimation?: boolean;
379
  /** Internal tooltip element reference (set automatically) */
380
  hintTooltipElement?: HTMLElement;
381
  /** Internal active state (managed automatically) */
382
  isActive?: boolean;
383
}
384
```
385

386
**Usage Examples:**
387

388
```javascript
389
import introJs from "intro.js";
390

391
const hint = introJs.hint();
392

393
// Complete hint definition
394
hint.addHint({
395
  element: "#advanced-settings",
396
  hint: "Configure advanced options and preferences for this feature.",
397
  hintPosition: "top-right",
398
  position: "bottom-left-aligned", 
399
  tooltipClass: "custom-hint-tooltip",
400
  hintAnimation: true
401
});
402

403
await hint.render();
404
```
405

406
### Deprecated Methods
407

408
Legacy methods maintained for backward compatibility:
409

410
```typescript { .api }
411
/**
412
 * @deprecated Use render() instead
413
 */
414
addHints(): Promise<Hint>;
415

416
/**
417
 * @deprecated Use destroy() instead  
418
 */
419
removeHints(): Hint;
420

421
/**
422
 * @deprecated Use onHintsAdded instead
423
 */
424
onhintsadded(callback: hintsAddedCallback): Hint;
425

426
/**
427
 * @deprecated Use onHintClick instead
428
 */
429
onhintclick(callback: hintClickCallback): Hint;
430

431
/**
432
 * @deprecated Use onHintClose instead
433
 */
434
onhintclose(callback: hintCloseCallback): Hint;
435
```
436

437
**Migration Examples:**
438

439
```javascript
440
// Old (deprecated)
441
await hint.addHints();
442
hint.removeHints();
443

444
// New (recommended)
445
await hint.render();
446
hint.destroy();
447
```