0
# Intro.js
1

2
Intro.js is a comprehensive user onboarding and product walkthrough library that enables developers to create step-by-step guides and interactive tours for web applications. It provides a flexible API for creating guided tours with customizable tooltips, positioning, and styling options, supporting both programmatic control and HTML data attributes for configuration.
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
```typescript
14
import introJs from "intro.js";
15
```
16

17
For named imports including utilities:
18

19
```typescript
20
import introJs, { getDefaultOptions } from "intro.js";
21
```
22

23
For CommonJS:
24

25
```javascript
26
const introJs = require("intro.js");
27
```
28

29
## Basic Usage
30

31
```typescript
32
import introJs from "intro.js";
33

34
// Basic tour with default options
35
const intro = introJs();
36
intro.start();
37

38
// Tour with specific target element
39
const intro = introJs("#my-container");
40
intro.start();
41

42
// Tour with custom options
43
const intro = introJs()
44
  .setOptions({
45
    nextLabel: "Next →",
46
    prevLabel: "← Previous", 
47
    doneLabel: "Finish",
48
    showStepNumbers: true,
49
    exitOnOverlayClick: false
50
  })
51
  .start();
52

53
// Add steps programmatically
54
introJs()
55
  .addStep({
56
    element: "#step1",
57
    intro: "This is the first step",
58
    position: "bottom"
59
  })
60
  .addStep({
61
    element: "#step2", 
62
    intro: "This is the second step",
63
    position: "top"
64
  })
65
  .start();
66
```
67

68
## Architecture
69

70
Intro.js is built around several key components:
71

72
- **Factory Function**: `introJs()` creates instances with optional element targeting
73
- **IntroJs Class**: Main API with fluent interface for tour control and configuration
74
- **Step System**: Tour steps with positioning, styling, and content options
75
- **Hint System**: Persistent hints that can be shown/hidden independently
76
- **Options System**: Comprehensive configuration for UI, behavior, and styling
77
- **Callback System**: Event hooks for tour lifecycle and user interactions
78
- **CSS Themes**: Customizable styling with built-in themes and RTL support
79

80
## Capabilities
81

82
### Tour Creation and Control
83

84
Core functionality for creating and managing guided tours. Perfect for user onboarding flows and feature introductions.
85

86
```typescript { .api }
87
function introJs(targetElm?: string | HTMLElement): IntroJs;
88
```
89

90
**Properties:**
91
```typescript { .api }
92
introJs.version: string;
93
introJs.instances: { [key: number]: IntroJs };
94
```
95

96
[Tour Control](./tour-control.md)
97

98
### Configuration and Options
99

100
Comprehensive options system for customizing tour behavior, appearance, and interaction patterns.
101

102
```typescript { .api }
103
interface Options {
104
  steps: Partial<IntroStep>[];
105
  hints: Partial<HintStep>[];
106
  isActive: boolean;
107
  nextLabel: string;
108
  prevLabel: string;
109
  skipLabel: string;
110
  doneLabel: string;
111
  hidePrev: boolean;
112
  hideNext: boolean;
113
  nextToDone: boolean;
114
  tooltipPosition: string;
115
  tooltipClass: string;
116
  group: string;
117
  highlightClass: string;
118
  exitOnEsc: boolean;
119
  exitOnOverlayClick: boolean;
120
  showStepNumbers: boolean;
121
  stepNumbersOfLabel: string;
122
  keyboardNavigation: boolean;
123
  showButtons: boolean;
124
  showBullets: boolean;
125
  showProgress: boolean;
126
  scrollToElement: boolean;
127
  scrollTo: ScrollTo;
128
  scrollPadding: number;
129
  overlayOpacity: number;
130
  autoPosition: boolean;
131
  positionPrecedence: TooltipPosition[];
132
  disableInteraction: boolean;
133
  dontShowAgain: boolean;
134
  dontShowAgainLabel: string;
135
  dontShowAgainCookie: string;
136
  dontShowAgainCookieDays: number;
137
  helperElementPadding: number;
138
  hintPosition: HintPosition;
139
  hintButtonLabel: string;
140
  hintShowButton: boolean;
141
  hintAutoRefreshInterval: number;
142
  hintAnimation: boolean;
143
  buttonClass: string;
144
  progressBarAdditionalClass: boolean;
145
}
146
```
147

148
[Configuration](./configuration.md)
149

150
### Step Management
151

152
Step system for defining tour content, positioning, and behavior. Supports both programmatic and HTML data attribute configuration.
153

154
```typescript { .api }
155
interface IntroStep {
156
  step: number;
157
  title: string;
158
  intro: string;
159
  tooltipClass?: string;
160
  highlightClass?: string;
161
  element?: HTMLElement | string | null;
162
  position: TooltipPosition;
163
  scrollTo: ScrollTo;
164
  disableInteraction?: boolean;
165
}
166
```
167

168
[Step Management](./step-management.md)
169

170
### Hint System
171

172
Persistent hint system for showing contextual help and tips that users can access on-demand.
173

174
```typescript { .api }
175
interface HintStep {
176
  element?: HTMLElement | string | null;
177
  tooltipClass?: string;
178
  position: TooltipPosition;
179
  hint?: string;
180
  hintTargetElement?: HTMLElement;
181
  hintAnimation?: boolean;
182
  hintPosition: HintPosition;
183
}
184
```
185

186
[Hints](./hints.md)
187

188
### Event Callbacks
189

190
Comprehensive callback system for hooking into tour lifecycle events and user interactions.
191

192
```typescript { .api }
193
type introBeforeChangeCallback = (
194
  this: IntroJs,
195
  targetElement: HTMLElement,
196
  currentStep: number,
197
  direction: "backward" | "forward"
198
) => Promise<boolean> | boolean;
199

200
type introChangeCallback = (
201
  this: IntroJs,
202
  targetElement: HTMLElement
203
) => void | Promise<void>;
204

205
type introAfterChangeCallback = (
206
  this: IntroJs,
207
  targetElement: HTMLElement
208
) => void | Promise<void>;
209

210
type introCompleteCallback = (
211
  this: IntroJs,
212
  currentStep: number,
213
  reason: "skip" | "end" | "done"
214
) => void | Promise<void>;
215

216
type introStartCallback = (
217
  this: IntroJs,
218
  targetElement: HTMLElement
219
) => void | Promise<void>;
220

221
type introExitCallback = (this: IntroJs) => void | Promise<void>;
222

223
type introSkipCallback = (
224
  this: IntroJs,
225
  currentStep: number
226
) => void | Promise<void>;
227

228
type introBeforeExitCallback = (
229
  this: IntroJs,
230
  targetElement: HTMLElement
231
) => boolean | Promise<boolean>;
232
```
233

234
[Event Callbacks](./callbacks.md)
235

236
## Type Definitions
237

238
```typescript { .api }
239
type ScrollTo = "off" | "element" | "tooltip";
240

241
type TooltipPosition =
242
  | "floating"
243
  | "top"
244
  | "bottom"
245
  | "left" 
246
  | "right"
247
  | "top-right-aligned"
248
  | "top-left-aligned"
249
  | "top-middle-aligned"
250
  | "bottom-right-aligned"
251
  | "bottom-left-aligned"
252
  | "bottom-middle-aligned";
253

254
type HintPosition =
255
  | "top-left"
256
  | "top-right"
257
  | "top-middle" 
258
  | "bottom-left"
259
  | "bottom-right"
260
  | "bottom-middle"
261
  | "middle-left"
262
  | "middle-right"
263
  | "middle-middle";
264
```