Walkthrough.js

Create beautiful, interactive tutorials and onboarding experiences for your web applications with zero dependencies.

✨ Features

• 🎨 Beautiful Design - Modern, polished UI with smooth animations
• ⌨️ Keyboard Navigation - Full support for arrow keys, Enter, and Escape
• 📱 Responsive - Works perfectly on all screen sizes and devices
• 🎯 Smart Positioning - Automatic popup positioning to stay visible
• 💾 Progress Tracking - Remember where users left off
• 🔌 Event Callbacks - Hook into lifecycle events for custom behavior
• 🎨 Customizable - Colors, positions, templates, and styling options
• ⚡ Multiple Setup Methods - HTML attributes, JSON config, or quick start
• 🧩 Custom Templates - Complete control over popup HTML structure

🚀 Quick Start

1. Include the Library

<script src="walkthrough.js"></script>  

2. Add Data Attributes (Easiest Method)

<div data-wt-step="1"   
     data-wt-title="Welcome!"   
     data-wt-text="This is your first step."   
     data-wt-position="bottom">  
  Content to highlight  
</div>  
  
<button data-wt-step="2"   
        data-wt-title="Click Here"   
        data-wt-text="This button does something important.">  
  Action Button  
</button>  

3. Start the Walkthrough

// Start from HTML attributes  
const tour = walkthrough.fromAttributes();  
tour.start();  
  
// Or use the quick start method  
walkthrough.start([  
  {  
    element: '.my-element',  
    title: 'Step 1',  
    text: 'This is the first step',  
    position: 'bottom'  
  },  
  {  
    element: '#my-button',  
    title: 'Step 2',   
    text: 'Click this button to continue',  
    position: 'top'  
  }  
]);  

📖 Usage Methods

Method 1: HTML Data Attributes

The simplest way to add walkthroughs. Just add data attributes to your HTML elements:

<div data-wt-step="1"   
     data-wt-title="Welcome"   
     data-wt-text="This is your dashboard"   
     data-wt-position="bottom">  
  Dashboard Content  
</div>  
  
<script>  
const tour = walkthrough.fromAttributes({  
  progressColor: '#667eea',  
  rememberProgress: true  
});  
tour.start();  
</script>  

Method 2: JSON Configuration

Use JavaScript objects for programmatic control:

const tour = walkthrough.fromJSON({  
  steps: [  
    {  
      element: '.header',  
      title: 'Navigation',  
      text: 'This is your main navigation area',  
      position: 'bottom'  
    },  
    {  
      element: '#sidebar',  
      title: 'Sidebar',  
      text: 'Access tools and settings here',  
      position: 'right',  
      nextText: 'Got it! →'  
    }  
  ],  
  options: {  
    progressColor: '#764ba2',  
    highlightPadding: 15,  
    animationDuration: 400  
  },  
  callbacks: {  
    onStart: () => console.log('Tour started'),  
    onFinish: () => console.log('Tour completed')  
  }  
});  
  
tour.start();  

Method 3: Quick Start

Perfect for rapid prototyping:

walkthrough.start([  
  {  
    element: '.feature',  
    title: 'New Feature',  
    text: 'Check out this new feature!',  
    position: 'bottom'  
  }  
], {  
  progressColor: '#28a745',  
  onFinish: () => alert('Tour complete!')  
});  

🎛️ Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | progressColor | string | '#007bff' | Color of the progress indicator | | highlightPadding | number | 10 | Padding around highlighted elements | | animationDuration | number | 300 | Animation duration in milliseconds | | rememberProgress | boolean | true | Remember user's progress in localStorage | | showProgress | boolean | true | Show step progress indicator | | allowClose | boolean | true | Allow users to close the walkthrough | | backdrop | boolean | true | Show backdrop overlay | | backdropColor | string | 'rgba(0,0,0,0.5)' | Backdrop overlay color |

📍 Position Options

• 'top' - Above the element
• 'bottom' - Below the element
• 'left' - To the left of the element
• 'right' - To the right of the element
• 'center' - Centered on screen

🎨 Custom Templates

Take full control of the popup HTML:

const tour = walkthrough.fromJSON({  
  steps: [...],  
  templates: {  
    popup: (step, index, total) => {  
      const isLast = index === total - 1;  
      return `  
        <div class="my-custom-popup">  
          <h2>${step.title}</h2>  
          <p>${step.text}</p>  
          <div class="buttons">  
            ${index > 0 ? `<button onclick="currentWalkthrough.prev()">Back</button>` : ''}  
            <button onclick="currentWalkthrough.${isLast ? 'finish' : 'next'}()">  
              ${isLast ? 'Finish' : 'Next'}  
            </button>  
          </div>  
        </div>  
      `;  
    }  
  }  
});  

🔌 Event Callbacks

const tour = walkthrough.fromJSON({  
  steps: [...],  
  callbacks: {  
    onStart: () => {  
      console.log('Walkthrough started');  
    },  
    onStep: (step, index) => {  
      console.log(`Now on step ${index + 1}: ${step.title}`);  
    },  
    onNext: (step, index) => {  
      console.log('Moving to next step');  
    },  
    onPrev: (step, index) => {  
      console.log('Moving to previous step');  
    },  
    onFinish: () => {  
      console.log('Walkthrough completed');  
    },  
    onClose: () => {  
      console.log('Walkthrough closed');  
    }  
  }  
});  

🎮 API Methods

	const tour = walkthrough.fromJSON({...});  
  
// Control methods  
tour.start();           // Start the walkthrough  
tour.next();            // Go to next step  
tour.prev();            // Go to previous step  
tour.goTo(stepIndex);   // Jump to specific step  
tour.finish();          // Complete the walkthrough  
tour.close();           // Close without completing  
tour.destroy();         // Clean up and remove  
  
// State methods  
tour.getCurrentStep();  // Get current step object  
tour.getCurrentIndex(); // Get current step index  
tour.getTotalSteps();   // Get total number of steps  
tour.isActive();        // Check if walkthrough is running  

⌨️ Keyboard Navigation

• → / ↓ - Next step
• ← / ↑ - Previous step
• Enter - Next step
• Escape - Close walkthrough
• Home - Go to first step
• End - Go to last step

🎯 HTML Data Attributes Reference

| Attribute | Description | Example | |-----------|-------------|---------| | data-wt-step | Step number (required) | data-wt-step="1" | | data-wt-title | Step title | data-wt-title="Welcome" | | data-wt-text | Step description | data-wt-text="This is the main menu" | | data-wt-position | Popup position | data-wt-position="bottom" | | data-wt-next-text | Custom next button text | data-wt-next-text="Continue →" | | data-wt-prev-text | Custom previous button text | data-wt-prev-text="← Back" |

🌟 Examples

Check out the demo files for comprehensive examples of all features and configuration methods.

• demo-quickstart.html
• demo-attributes.html
• demo-json.html
• demo-custom-template.html

📄 License

LGPL License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

📞 Support

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions