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
```