0
# Configuration Options
1

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

4
## Capabilities
5

6
### Tour Options
7

8
Complete configuration interface for Tour instances with extensive customization options.
9

10
```typescript { .api }
11
interface TourOptions {
12
  /** Array of tour steps */
13
  steps: Partial<TourStep>[];
14
  /** Is this tour instance active? Don't show the tour again if set to false */
15
  isActive: boolean;
16
  /** Next button label in tooltip box */
17
  nextLabel: string;
18
  /** Previous button label in tooltip box */
19
  prevLabel: string;
20
  /** Skip button label in tooltip box */
21
  skipLabel: string;
22
  /** Done button label in tooltip box */
23
  doneLabel: string;
24
  /** Hide previous button in the first step? Otherwise, it will be disabled */
25
  hidePrev: boolean;
26
  /** Hide next button in the last step? Otherwise, it will be disabled */
27
  hideNext: boolean;
28
  /** Change the Next button to Done in the last step of the intro */
29
  nextToDone: boolean;
30
  /** Default tooltip box position */
31
  tooltipPosition: TooltipPosition;
32
  /** CSS class for tooltip boxes */
33
  tooltipClass: string;
34
  /** Start intro for a group of elements */
35
  group: string;
36
  /** CSS class that is added to the helperLayer */
37
  highlightClass: string;
38
  /** Close introduction when pressing Escape button? */
39
  exitOnEsc: boolean;
40
  /** Close introduction when clicking on overlay layer? */
41
  exitOnOverlayClick: boolean;
42
  /** Display the pagination detail */
43
  showStepNumbers: boolean;
44
  /** Pagination "of" label */
45
  stepNumbersOfLabel: string;
46
  /** Let user use keyboard to navigate the tour? */
47
  keyboardNavigation: boolean;
48
  /** Show tour control buttons? */
49
  showButtons: boolean;
50
  /** Show tour bullets? */
51
  showBullets: boolean;
52
  /** Show tour progress? */
53
  showProgress: boolean;
54
  /** Scroll to highlighted element? */
55
  scrollToElement: boolean;
56
  /** Should we scroll the tooltip or target element? */
57
  scrollTo: ScrollTo;
58
  /** Padding to add after scrolling when element is not in the viewport (in pixels) */
59
  scrollPadding: number;
60
  /** Set the overlay opacity */
61
  overlayOpacity: number;
62
  /** To determine the tooltip position automatically based on the window.width/height */
63
  autoPosition: boolean;
64
  /** Precedence of positions, when auto is enabled */
65
  positionPrecedence: TooltipPosition[];
66
  /** Disable an interaction with element? */
67
  disableInteraction: boolean;
68
  /** To display the "Don't show again" checkbox in the tour */
69
  dontShowAgain: boolean;
70
  /** "Don't show again" checkbox label */
71
  dontShowAgainLabel: string;
72
  /** "Don't show again" cookie name */
73
  dontShowAgainCookie: string;
74
  /** "Don't show again" cookie expiry (in days) */
75
  dontShowAgainCookieDays: number;
76
  /** Set how much padding to be used around helper element */
77
  helperElementPadding: number;
78
  /** Additional classes to put on the buttons */
79
  buttonClass: string;
80
  /** Additional classes to put on progress bar */
81
  progressBarAdditionalClass: string;
82
  /** Optional property to determine if content should be rendered as HTML */
83
  tooltipRenderAsHtml?: boolean;
84
}
85
```
86

87
### Default Tour Options
88

89
Default configuration values for Tour instances.
90

91
```typescript { .api }
92
/**
93
 * Get the default tour options
94
 */
95
function getDefaultTourOptions(): TourOptions;
96
```
97

98
**Default Values:**
99

100
```javascript
101
{
102
  steps: [],
103
  isActive: true,
104
  nextLabel: "Next",
105
  prevLabel: "Back",
106
  skipLabel: "×",
107
  doneLabel: "Done",
108
  hidePrev: false,
109
  hideNext: false,
110
  nextToDone: true,
111
  tooltipPosition: "bottom",
112
  tooltipClass: "",
113
  group: "",
114
  highlightClass: "",
115
  exitOnEsc: true,
116
  exitOnOverlayClick: true,
117
  showStepNumbers: false,
118
  stepNumbersOfLabel: "of",
119
  keyboardNavigation: true,
120
  showButtons: true,
121
  showBullets: true,
122
  showProgress: false,
123
  scrollToElement: true,
124
  scrollTo: "element",
125
  scrollPadding: 30,
126
  overlayOpacity: 0.5,
127
  autoPosition: true,
128
  positionPrecedence: ["bottom", "top", "right", "left"],
129
  disableInteraction: false,
130
  dontShowAgain: false,
131
  dontShowAgainLabel: "Don't show this again",
132
  dontShowAgainCookie: "introjs-dontShowAgain",
133
  dontShowAgainCookieDays: 365,
134
  helperElementPadding: 10,
135
  buttonClass: "introjs-button",
136
  progressBarAdditionalClass: "",
137
  tooltipRenderAsHtml: true
138
}
139
```
140

141
### Tour Options Usage
142

143
**Basic Tour Configuration:**
144

145
```javascript
146
import introJs from "intro.js";
147

148
const tour = introJs.tour();
149

150
// Set comprehensive tour options
151
tour.setOptions({
152
  // Button labels
153
  nextLabel: "Continue →",
154
  prevLabel: "← Back",
155
  skipLabel: "Skip Tour",
156
  doneLabel: "Finish",
157
  
158
  // Appearance
159
  tooltipPosition: "top",
160
  tooltipClass: "custom-tour-tooltip",
161
  highlightClass: "custom-highlight",
162
  overlayOpacity: 0.7,
163
  
164
  // Behavior
165
  exitOnEsc: true,
166
  exitOnOverlayClick: false,
167
  keyboardNavigation: true,
168
  scrollToElement: true,
169
  scrollPadding: 50,
170
  
171
  // UI Elements
172
  showStepNumbers: true,
173
  showProgress: true,
174
  showButtons: true,
175
  showBullets: false,
176
  
177
  // Don't show again functionality
178
  dontShowAgain: true,
179
  dontShowAgainLabel: "Don't show this tour again",
180
  dontShowAgainCookie: "my-app-tour-seen",
181
  dontShowAgainCookieDays: 30
182
});
183
```
184

185
### Hint Options
186

187
Complete configuration interface for Hint instances.
188

189
```typescript { .api }
190
interface HintOptions {
191
  /** List of all HintItems */
192
  hints: Partial<HintItem>[];
193
  /** True if the Hint instance is set to active */
194
  isActive: boolean;
195
  /** Default tooltip box position */
196
  tooltipPosition: string;
197
  /** CSS class for tooltip boxes */
198
  tooltipClass: string;
199
  /** Default hint position */
200
  hintPosition: HintPosition;
201
  /** Hint button label */
202
  hintButtonLabel: string;
203
  /** Display the "Got it" button? */
204
  hintShowButton: boolean;
205
  /** Hints auto-refresh interval in ms (set to -1 to disable) */
206
  hintAutoRefreshInterval: number;
207
  /** Adding animation to hints? */
208
  hintAnimation: boolean;
209
  /** Additional classes to put on the buttons */
210
  buttonClass: string;
211
  /** Set how much padding to be used around helper element */
212
  helperElementPadding: number;
213
  /** To determine the tooltip position automatically based on the window.width/height */
214
  autoPosition: boolean;
215
  /** Precedence of positions, when auto is enabled */
216
  positionPrecedence: TooltipPosition[];
217
  /** Optional property to determine if content should be rendered as HTML */
218
  tooltipRenderAsHtml?: boolean;
219
}
220
```
221

222
### Default Hint Options
223

224
Default configuration values for Hint instances.
225

226
```typescript { .api }
227
/**
228
 * Get the default hint options
229
 */
230
function getDefaultHintOptions(): HintOptions;
231
```
232

233
**Default Values:**
234

235
```javascript
236
{
237
  hints: [],
238
  isActive: true,
239
  tooltipPosition: "bottom",
240
  tooltipClass: "",
241
  hintPosition: "top-middle",
242
  hintButtonLabel: "Got it",
243
  hintShowButton: true,
244
  hintAutoRefreshInterval: 10,
245
  hintAnimation: true,
246
  buttonClass: "introjs-button",
247
  helperElementPadding: 10,
248
  autoPosition: true,
249
  positionPrecedence: ["bottom", "top", "right", "left"],
250
  tooltipRenderAsHtml: true
251
}
252
```
253

254
### Hint Options Usage
255

256
**Basic Hint Configuration:**
257

258
```javascript
259
import introJs from "intro.js";
260

261
const hint = introJs.hint();
262

263
// Set comprehensive hint options
264
hint.setOptions({
265
  // Appearance
266
  tooltipPosition: "top",
267
  tooltipClass: "custom-hint-tooltip",
268
  hintPosition: "bottom-right",
269
  
270
  // Behavior
271
  hintAnimation: true,
272
  hintAutoRefreshInterval: 100,
273
  autoPosition: true,
274
  positionPrecedence: ["top", "bottom", "left", "right"],
275
  
276
  // Button configuration
277
  hintShowButton: true,
278
  hintButtonLabel: "Understood",
279
  buttonClass: "custom-hint-button",
280
  
281
  // Styling
282
  helperElementPadding: 15,
283
  tooltipRenderAsHtml: true
284
});
285
```
286

287
### Position Configuration
288

289
Detailed configuration for tooltip and hint positioning.
290

291
```typescript { .api }
292
/**
293
 * Tooltip position options for tours and hints
294
 */
295
type TooltipPosition = 
296
  | "floating"           // Centered on screen, no target element
297
  | "top"               // Above the target element
298
  | "bottom"            // Below the target element  
299
  | "left"              // Left of the target element
300
  | "right"             // Right of the target element
301
  | "top-right-aligned"    // Above, aligned to right edge
302
  | "top-left-aligned"     // Above, aligned to left edge
303
  | "top-middle-aligned"   // Above, centered horizontally
304
  | "bottom-right-aligned" // Below, aligned to right edge
305
  | "bottom-left-aligned"  // Below, aligned to left edge
306
  | "bottom-middle-aligned"; // Below, centered horizontally
307

308
/**
309
 * Hint icon position options (relative to target element)
310
 */
311
type HintPosition = 
312
  | "top-left"       // Top-left corner
313
  | "top-right"      // Top-right corner
314
  | "top-middle"     // Top edge, centered
315
  | "bottom-left"    // Bottom-left corner
316
  | "bottom-right"   // Bottom-right corner
317
  | "bottom-middle"  // Bottom edge, centered
318
  | "middle-left"    // Left edge, vertically centered
319
  | "middle-right"   // Right edge, vertically centered
320
  | "middle-middle"; // Center of element
321

322
/**
323
 * Scroll behavior options for tours
324
 */
325
type ScrollTo = 
326
  | "off"      // No automatic scrolling
327
  | "element"  // Scroll to bring target element into view
328
  | "tooltip"; // Scroll to bring tooltip into view
329
```
330

331
### Advanced Configuration Examples
332

333
**Tour with Advanced Positioning:**
334

335
```javascript
336
import introJs from "intro.js";
337

338
const tour = introJs.tour()
339
  .setOptions({
340
    // Auto-positioning with custom precedence
341
    autoPosition: true,
342
    positionPrecedence: ["top", "right", "bottom", "left"],
343
    
344
    // Custom scroll behavior
345
    scrollToElement: true,
346
    scrollTo: "tooltip",
347
    scrollPadding: 100,
348
    
349
    // Fine-tuned appearance
350
    overlayOpacity: 0.3,
351
    helperElementPadding: 20,
352
    
353
    // Step-specific overrides will still work
354
    tooltipPosition: "bottom-middle-aligned"
355
  })
356
  .addStep({
357
    title: "Special Element",
358
    intro: "This step uses custom positioning",
359
    element: "#special-element",
360
    position: "top-left-aligned" // Overrides default
361
  });
362
```
363

364
**Hint with Performance Optimization:**
365

366
```javascript
367
import introJs from "intro.js";
368

369
const hint = introJs.hint()
370
  .setOptions({
371
    // Optimize for performance
372
    hintAutoRefreshInterval: 500, // Less frequent updates
373
    hintAnimation: false,         // Disable animations
374
    
375
    // Custom positioning for mobile
376
    hintPosition: "top-middle",
377
    autoPosition: true,
378
    positionPrecedence: ["top", "bottom"], // Prefer vertical positions
379
    
380
    // Minimal UI
381
    hintShowButton: false,
382
    helperElementPadding: 5
383
  });
384
```
385

386
### Option Validation and Type Safety
387

388
All options are fully typed and validated:
389

390
```javascript
391
import introJs from "intro.js";
392

393
const tour = introJs.tour();
394

395
// TypeScript will catch invalid option keys
396
tour.setOption("invalidOption", "value"); // ❌ Type error
397

398
// Valid option setting
399
tour.setOption("nextLabel", "Proceed"); // ✅ Valid
400

401
// Get option with type safety  
402
const isActive: boolean = tour.getOption("isActive"); // ✅ Typed return
403
```