or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration-options.mdevent-handling.mdhint-system.mdindex.mdtour-management.md
tile.json

tessl/npm-intro-js

User Onboarding and Product Walkthrough Library

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/intro.js@8.3.x

To install, run

npx @tessl/cli install tessl/npm-intro-js@8.3.0

index.mddocs/

Intro.js

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.

Package Information

  • Package Name: intro.js
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install intro.js

Core Imports

import introJs from "intro.js";

Modern API (recommended):

import introJs from "intro.js";

// Create tour instance
const tour = introJs.tour();

// Create hint instance  
const hint = introJs.hint();

For CommonJS:

const introJs = require("intro.js");

Basic Usage

Creating a Simple Tour

import introJs from "intro.js";

// Create and start a tour
const tour = introJs.tour()
  .addStep({
    title: "Welcome!",
    intro: "This is the main dashboard.",
    element: "#dashboard"
  })
  .addStep({  
    title: "Navigation",
    intro: "Use this menu to navigate.",
    element: ".nav-menu"
  })
  .start();

Adding Contextual Hints

import introJs from "intro.js";

// Create and render hints
const hint = introJs.hint()
  .addHint({
    element: "#help-button",
    hint: "Click for help and support",
    hintPosition: "top-middle"
  })
  .render();

HTML Data Attributes

<!-- Tour steps using data attributes -->
<div data-intro="Welcome to our app!" data-step="1">Dashboard</div>
<div data-intro="Manage your settings here" data-step="2">Settings</div>

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

<script>
  // Start tour from HTML attributes
  introJs.tour().start();
  
  // Render hints from HTML attributes  
  introJs.hint().render();
</script>

Architecture

Intro.js is built around several key components:

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

Capabilities

Tour Management

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

interface Tour {
  start(): Promise<Tour>;
  exit(force?: boolean): Promise<Tour>;
  nextStep(): Promise<Tour>;
  previousStep(): Promise<Tour>;
  addStep(step: Partial<TourStep>): Tour;
  addSteps(steps: Partial<TourStep>[]): Tour;
}

interface TourStep {
  step: number;
  title: string;
  intro: string;
  element?: Element | HTMLElement | string | null;
  position: TooltipPosition;
  scrollTo: ScrollTo;
  disableInteraction?: boolean;
  tooltipClass?: string;
  highlightClass?: string;
}

Tour Management

Hint System

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

interface Hint {
  render(): Promise<Hint>;
  destroy(): Hint;
  showHint(stepId: number): Hint;
  hideHint(stepId: number): Promise<Hint>;
  addHint(hint: HintItem): Hint;
  showHintDialog(stepId: number): Promise<Hint>;
}

interface HintItem {
  element?: HTMLElement | string | null;
  hint?: string;
  hintPosition: HintPosition;
  position: TooltipPosition;
  tooltipClass?: string;
  hintAnimation?: boolean;
}

Hint System

Configuration Options

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

interface TourOptions {
  steps: Partial<TourStep>[];
  isActive: boolean;
  nextLabel: string;
  prevLabel: string;
  skipLabel: string;
  doneLabel: string;
  tooltipPosition: TooltipPosition;
  exitOnEsc: boolean;
  exitOnOverlayClick: boolean;
  showStepNumbers: boolean;
  keyboardNavigation: boolean;
  showButtons: boolean;
  showBullets: boolean;
  showProgress: boolean;
  scrollToElement: boolean;
  overlayOpacity: number;
  autoPosition: boolean;
  dontShowAgain: boolean;
}

interface HintOptions {
  hints: Partial<HintItem>[];
  isActive: boolean;
  tooltipPosition: string;
  hintPosition: HintPosition;
  hintButtonLabel: string;
  hintShowButton: boolean;
  hintAutoRefreshInterval: number;
  hintAnimation: boolean;
  autoPosition: boolean;
}

Configuration Options

Event Handling

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

interface TourCallbacks {
  onBeforeChange(callback: (targetElement: HTMLElement, currentStep: number, direction: "backward" | "forward") => Promise<boolean> | boolean): Tour;
  onChange(callback: (targetElement: HTMLElement) => void | Promise<void>): Tour;
  onAfterChange(callback: (targetElement: HTMLElement) => void | Promise<void>): Tour;
  onComplete(callback: (currentStep: number, reason: "skip" | "end" | "done") => void | Promise<void>): Tour;
  onStart(callback: (targetElement: HTMLElement) => void | Promise<void>): Tour;
  onExit(callback: () => void | Promise<void>): Tour;
  onSkip(callback: (currentStep: number) => void | Promise<void>): Tour;
  onBeforeExit(callback: (targetElement: HTMLElement) => boolean | Promise<boolean>): Tour;
}

interface HintCallbacks {
  onHintsAdded(callback: () => void | Promise<void>): Hint;
  onHintClick(callback: (item: HintItem) => void | Promise<void>): Hint;
  onHintClose(callback: (item: HintItem) => void | Promise<void>): Hint;
}

Event Handling

Types

Core Types

type TooltipPosition = 
  | "floating" 
  | "top" 
  | "bottom" 
  | "left" 
  | "right" 
  | "top-right-aligned" 
  | "top-left-aligned" 
  | "top-middle-aligned" 
  | "bottom-right-aligned" 
  | "bottom-left-aligned" 
  | "bottom-middle-aligned";

type HintPosition = 
  | "top-left" 
  | "top-right" 
  | "top-middle" 
  | "bottom-left" 
  | "bottom-right" 
  | "bottom-middle" 
  | "middle-left" 
  | "middle-right" 
  | "middle-middle";

type ScrollTo = "off" | "element" | "tooltip";

Main Entry Points

/**
 * Legacy IntroJs class extending Tour with deprecated hint methods
 */
class LegacyIntroJs extends Tour {
  /** @deprecated Use introJs.hint().addHints() instead */
  addHints(...args: any[]): void;
  /** @deprecated Use introJs.hint().addHint() instead */
  addHint(...args: any[]): void;
  /** @deprecated Use introJs.hint().hideHints() instead */
  removeHints(...args: any[]): void;
}

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

declare namespace introJs {
  /**
   * Create new Tour instance for guided walkthroughs
   */
  function tour(elementOrSelector?: string | HTMLElement): Tour;
  
  /**
   * Create new Hint instance for contextual tooltips  
   */
  function hint(elementOrSelector?: string | HTMLElement): Hint;
  
  /**
   * Current package version
   */
  const version: string;
}

export default introJs;