0
# Tour Control
1

2
Core functionality for creating and managing guided tours, including instance creation, navigation, and lifecycle management.
3

4
## Capabilities
5

6
### IntroJs Factory Function
7

8
Creates a new IntroJs instance for building guided tours.
9

10
```typescript { .api }
11
/**
12
 * Create a new IntroJS instance
13
 * @param targetElm - Optional target element to start the tour/hint on
14
 * @returns IntroJs instance for chaining operations
15
 * @throws Error when targetElm is a string selector that matches no elements
16
 */
17
function introJs(targetElm?: string | HTMLElement): IntroJs;
18
```
19

20
**Usage Examples:**
21

22
```typescript
23
import introJs from "intro.js";
24

25
// Create instance for entire page
26
const intro = introJs();
27

28
// Create instance for specific element
29
const intro = introJs("#dashboard");
30

31
// Create instance using DOM element
32
const element = document.getElementById("form-container");
33
const intro = introJs(element);
34

35
// Error handling for invalid selectors
36
try {
37
  const intro = introJs("#non-existent-element");
38
} catch (error) {
39
  console.error("Element not found:", error.message);
40
}
41
```
42

43
### IntroJs Class
44

45
Main class providing the fluent API for tour management.
46

47
```typescript { .api }
48
class IntroJs {
49
  _currentStep: number;
50
  _currentStepNumber: number | undefined;
51
  _direction: "forward" | "backward";
52
  _targetElement: HTMLElement;
53
  _introItems: IntroStep[];
54
  _hintItems: HintStep[];
55
  _options: Options;
56

57
  constructor(targetElement: HTMLElement);
58
}
59
```
60

61
### Tour Lifecycle Management
62

63
#### Start Tour
64

65
Begins the intro tour with configured steps and options.
66

67
```typescript { .api }
68
/**
69
 * Start the intro tour
70
 * @returns Promise resolving to the IntroJs instance
71
 */
72
start(): Promise<IntroJs>;
73
```
74

75
**Usage Examples:**
76

77
```typescript
78
// Basic start
79
await introJs().start();
80

81
// Start with configuration
82
await introJs()
83
  .setOptions({ showStepNumbers: true })
84
  .start();
85

86
// Start with callback
87
await introJs()
88
  .onstart(() => console.log("Tour started"))
89
  .start();
90
```
91

92
#### Exit Tour
93

94
Exits the current tour, optionally forcing the exit.
95

96
```typescript { .api }
97
/**
98
 * Exit the intro tour
99
 * @param force - Whether to force exit without calling beforeExit callback
100
 * @returns Promise resolving to the IntroJs instance
101
 */
102
exit(force: boolean): Promise<IntroJs>;
103
```
104

105
**Usage Examples:**
106

107
```typescript
108
// Normal exit (respects beforeExit callback)
109
await intro.exit(false);
110

111
// Force exit (bypasses beforeExit callback)
112
await intro.exit(true);
113
```
114

115
#### Check Active Status
116

117
Determines if the tour instance is currently active.
118

119
```typescript { .api }
120
/**
121
 * Check if intro is active (respects dontShowAgain setting)
122
 * @returns Boolean indicating if tour is active
123
 */
124
isActive(): boolean;
125
```
126

127
### Tour Navigation
128

129
#### Go to Step
130

131
Navigate to a specific step by index (1-based).
132

133
```typescript { .api }
134
/**
135
 * Go to specific step of introduction
136
 * @param step - Step number (1-indexed)
137
 * @returns Promise resolving to the IntroJs instance
138
 */
139
goToStep(step: number): Promise<IntroJs>;
140
```
141

142
#### Go to Step Number
143

144
Navigate to a step by its explicit step number (data-step attribute).
145

146
```typescript { .api }
147
/**
148
 * Go to the specific step with explicit [data-step] number
149
 * @param step - The data-step number to navigate to
150
 * @returns Promise resolving to the IntroJs instance
151
 */
152
goToStepNumber(step: number): Promise<IntroJs>;
153
```
154

155
#### Next Step
156

157
Advance to the next step in the tour.
158

159
```typescript { .api }
160
/**
161
 * Go to next step in the tour
162
 * @returns Promise resolving to the IntroJs instance
163
 */
164
nextStep(): Promise<IntroJs>;
165
```
166

167
#### Previous Step
168

169
Go back to the previous step in the tour.
170

171
```typescript { .api }
172
/**
173
 * Go to previous step in the tour  
174
 * @returns Promise resolving to the IntroJs instance
175
 */
176
previousStep(): Promise<IntroJs>;
177
```
178

179
#### Get Current Step
180

181
Returns the current step index.
182

183
```typescript { .api }
184
/**
185
 * Get the current step index
186
 * @returns Current step index (0-based, -1 if not started)
187
 */
188
currentStep(): number;
189
```
190

191
**Usage Examples:**
192

193
```typescript
194
// Navigation example
195
const intro = introJs();
196
await intro.start();
197

198
// Check current position
199
console.log(`Current step: ${intro.currentStep()}`);
200

201
// Navigate programmatically
202
await intro.goToStep(3);
203
await intro.nextStep();
204
await intro.previousStep();
205

206
// Navigate by data-step attribute
207
await intro.goToStepNumber(5);
208
```
209

210
### Instance Management
211

212
#### Clone Instance
213

214
Creates a copy of the current IntroJs instance.
215

216
```typescript { .api }
217
/**
218
 * Create a clone of the current instance
219
 * @returns New IntroJs instance with same target element
220
 */
221
clone(): IntroJs;
222
```
223

224
#### Refresh Tour
225

226
Refreshes the tour, optionally re-fetching steps from DOM.
227

228
```typescript { .api }
229
/**
230
 * Refresh the intro tour
231
 * @param refreshSteps - Whether to refresh steps from DOM
232
 * @returns IntroJs instance for chaining
233
 */
234
refresh(refreshSteps?: boolean): IntroJs;
235
```
236

237
**Usage Examples:**
238

239
```typescript
240
// Clone for different configuration
241
const baseIntro = introJs("#container");
242
const customIntro = baseIntro.clone().setOptions({ 
243
  nextLabel: "Continue" 
244
});
245

246
// Refresh after DOM changes
247
intro.refresh(true);
248
```
249

250
### Static Properties
251

252
Properties available on the introJs function itself.
253

254
```typescript { .api }
255
/**
256
 * Current IntroJs version
257
 */
258
introJs.version: string;
259

260
/**
261
 * Object storing all active IntroJs instances by ID
262
 */
263
introJs.instances: { [key: number]: IntroJs };
264
```
265

266
**Usage Examples:**
267

268
```typescript
269
// Check version
270
console.log(`Using Intro.js version ${introJs.version}`);
271

272
// Access all instances
273
Object.values(introJs.instances).forEach(instance => {
274
  console.log(`Instance step: ${instance.currentStep()}`);
275
});
276
```