0
# Intro.js
1

2
Intro.js provides a comprehensive user onboarding and product walkthrough library that enables developers to create step-by-step tours and contextual hints for web applications. It offers a modern TypeScript API with two main components: Tour for guided walkthroughs and Hint for contextual tooltips, supporting both legacy JavaScript and modern modular implementations.
3

4
## Package Information
5

6
- **Package Name**: intro.js
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install intro.js`
10

11
## Core Imports
12

13
```javascript
14
import introJs from "intro.js";
15
```
16

17
Modern API (recommended):
18

19
```javascript
20
import introJs from "intro.js";
21

22
// Create tour instance
23
const tour = introJs.tour();
24

25
// Create hint instance  
26
const hint = introJs.hint();
27
```
28

29
For CommonJS:
30

31
```javascript
32
const introJs = require("intro.js");
33
```
34

35
## Basic Usage
36

37
### Creating a Simple Tour
38

39
```javascript
40
import introJs from "intro.js";
41

42
// Create and start a tour
43
const tour = introJs.tour()
44
  .addStep({
45
    title: "Welcome!",
46
    intro: "This is the main dashboard.",
47
    element: "#dashboard"
48
  })
49
  .addStep({  
50
    title: "Navigation",
51
    intro: "Use this menu to navigate.",
52
    element: ".nav-menu"
53
  })
54
  .start();
55
```
56

57
### Adding Contextual Hints
58

59
```javascript
60
import introJs from "intro.js";
61

62
// Create and render hints
63
const hint = introJs.hint()
64
  .addHint({
65
    element: "#help-button",
66
    hint: "Click for help and support",
67
    hintPosition: "top-middle"
68
  })
69
  .render();
70
```
71

72
### HTML Data Attributes
73

74
```html
75
<!-- Tour steps using data attributes -->
76
<div data-intro="Welcome to our app!" data-step="1">Dashboard</div>
77
<div data-intro="Manage your settings here" data-step="2">Settings</div>
78

79
<!-- Hints using data attributes -->
80
<button data-hint="Save your changes">Save</button>
81
<input data-hint="Enter your email address" data-hint-position="top-middle">
82

83
<script>
84
  // Start tour from HTML attributes
85
  introJs.tour().start();
86
  
87
  // Render hints from HTML attributes  
88
  introJs.hint().render();
89
</script>
90
```
91

92
## Architecture
93

94
Intro.js is built around several key components:
95

96
- **Main Entry Point**: The `introJs` function provides access to Tour and Hint instances
97
- **Tour System**: Comprehensive guided walkthrough functionality with step management, navigation, and customization
98
- **Hint System**: Contextual tooltip system for on-demand help and feature discovery
99
- **Configuration Options**: Extensive customization through TourOptions and HintOptions interfaces
100
- **Event System**: Rich callback system for handling tour/hint lifecycle events
101
- **Positioning Engine**: Automatic tooltip positioning with fallback handling and custom alignment
102
- **Data Attributes**: HTML-based configuration for seamless integration without JavaScript setup
103

104
## Capabilities
105

106
### Tour Management
107

108
Complete guided tour functionality for creating step-by-step product walkthroughs. Supports both programmatic step definition and HTML data-attribute discovery.
109

110
```typescript { .api }
111
interface Tour {
112
  start(): Promise<Tour>;
113
  exit(force?: boolean): Promise<Tour>;
114
  nextStep(): Promise<Tour>;
115
  previousStep(): Promise<Tour>;
116
  addStep(step: Partial<TourStep>): Tour;
117
  addSteps(steps: Partial<TourStep>[]): Tour;
118
}
119

120
interface TourStep {
121
  step: number;
122
  title: string;
123
  intro: string;
124
  element?: Element | HTMLElement | string | null;
125
  position: TooltipPosition;
126
  scrollTo: ScrollTo;
127
  disableInteraction?: boolean;
128
  tooltipClass?: string;
129
  highlightClass?: string;
130
}
131
```
132

133
[Tour Management](./tour-management.md)
134

135
### Hint System
136

137
Contextual tooltip system for providing on-demand help and feature discovery. Supports individual hint control and bulk operations.
138

139
```typescript { .api }
140
interface Hint {
141
  render(): Promise<Hint>;
142
  destroy(): Hint;
143
  showHint(stepId: number): Hint;
144
  hideHint(stepId: number): Promise<Hint>;
145
  addHint(hint: HintItem): Hint;
146
  showHintDialog(stepId: number): Promise<Hint>;
147
}
148

149
interface HintItem {
150
  element?: HTMLElement | string | null;
151
  hint?: string;
152
  hintPosition: HintPosition;
153
  position: TooltipPosition;
154
  tooltipClass?: string;
155
  hintAnimation?: boolean;
156
}
157
```
158

159
[Hint System](./hint-system.md)
160

161
### Configuration Options
162

163
Comprehensive configuration system with separate option sets for tours and hints, supporting extensive customization of appearance, behavior, and interaction patterns.
164

165
```typescript { .api }
166
interface TourOptions {
167
  steps: Partial<TourStep>[];
168
  isActive: boolean;
169
  nextLabel: string;
170
  prevLabel: string;
171
  skipLabel: string;
172
  doneLabel: string;
173
  tooltipPosition: TooltipPosition;
174
  exitOnEsc: boolean;
175
  exitOnOverlayClick: boolean;
176
  showStepNumbers: boolean;
177
  keyboardNavigation: boolean;
178
  showButtons: boolean;
179
  showBullets: boolean;
180
  showProgress: boolean;
181
  scrollToElement: boolean;
182
  overlayOpacity: number;
183
  autoPosition: boolean;
184
  dontShowAgain: boolean;
185
}
186

187
interface HintOptions {
188
  hints: Partial<HintItem>[];
189
  isActive: boolean;
190
  tooltipPosition: string;
191
  hintPosition: HintPosition;
192
  hintButtonLabel: string;
193
  hintShowButton: boolean;
194
  hintAutoRefreshInterval: number;
195
  hintAnimation: boolean;
196
  autoPosition: boolean;
197
}
198
```
199

200
[Configuration Options](./configuration-options.md)
201

202
### Event Handling
203

204
Rich callback system for handling tour and hint lifecycle events, enabling custom behavior and integration with analytics or other systems.
205

206
```typescript { .api }
207
interface TourCallbacks {
208
  onBeforeChange(callback: (targetElement: HTMLElement, currentStep: number, direction: "backward" | "forward") => Promise<boolean> | boolean): Tour;
209
  onChange(callback: (targetElement: HTMLElement) => void | Promise<void>): Tour;
210
  onAfterChange(callback: (targetElement: HTMLElement) => void | Promise<void>): Tour;
211
  onComplete(callback: (currentStep: number, reason: "skip" | "end" | "done") => void | Promise<void>): Tour;
212
  onStart(callback: (targetElement: HTMLElement) => void | Promise<void>): Tour;
213
  onExit(callback: () => void | Promise<void>): Tour;
214
  onSkip(callback: (currentStep: number) => void | Promise<void>): Tour;
215
  onBeforeExit(callback: (targetElement: HTMLElement) => boolean | Promise<boolean>): Tour;
216
}
217

218
interface HintCallbacks {
219
  onHintsAdded(callback: () => void | Promise<void>): Hint;
220
  onHintClick(callback: (item: HintItem) => void | Promise<void>): Hint;
221
  onHintClose(callback: (item: HintItem) => void | Promise<void>): Hint;
222
}
223
```
224

225
[Event Handling](./event-handling.md)
226

227
## Types
228

229
### Core Types
230

231
```typescript { .api }
232
type TooltipPosition = 
233
  | "floating" 
234
  | "top" 
235
  | "bottom" 
236
  | "left" 
237
  | "right" 
238
  | "top-right-aligned" 
239
  | "top-left-aligned" 
240
  | "top-middle-aligned" 
241
  | "bottom-right-aligned" 
242
  | "bottom-left-aligned" 
243
  | "bottom-middle-aligned";
244

245
type HintPosition = 
246
  | "top-left" 
247
  | "top-right" 
248
  | "top-middle" 
249
  | "bottom-left" 
250
  | "bottom-right" 
251
  | "bottom-middle" 
252
  | "middle-left" 
253
  | "middle-right" 
254
  | "middle-middle";
255

256
type ScrollTo = "off" | "element" | "tooltip";
257
```
258

259
### Main Entry Points
260

261
```typescript { .api }
262
/**
263
 * Legacy IntroJs class extending Tour with deprecated hint methods
264
 */
265
class LegacyIntroJs extends Tour {
266
  /** @deprecated Use introJs.hint().addHints() instead */
267
  addHints(...args: any[]): void;
268
  /** @deprecated Use introJs.hint().addHint() instead */
269
  addHint(...args: any[]): void;
270
  /** @deprecated Use introJs.hint().hideHints() instead */
271
  removeHints(...args: any[]): void;
272
}
273

274
/**
275
 * Main intro.js function - deprecated, use introJs.tour() or introJs.hint() instead
276
 */
277
declare function introJs(elementOrSelector?: string | HTMLElement): LegacyIntroJs;
278

279
declare namespace introJs {
280
  /**
281
   * Create new Tour instance for guided walkthroughs
282
   */
283
  function tour(elementOrSelector?: string | HTMLElement): Tour;
284
  
285
  /**
286
   * Create new Hint instance for contextual tooltips  
287
   */
288
  function hint(elementOrSelector?: string | HTMLElement): Hint;
289
  
290
  /**
291
   * Current package version
292
   */
293
  const version: string;
294
}
295

296
export default introJs;
297
```