https://github.com/ronanarm/walkthroughjs
Walkthrough.js is a lightweight, dependency-free JavaScript library for creating interactive tutorials, product tours, and onboarding experiences. It features smart positioning, progress tracking, customizable templates, and works seamlessly across browsers and devices.
https://github.com/ronanarm/walkthroughjs
frontend guide javascript onboarding product-tour react reactjs tutorial ui ux vue vuejs walkthrough
Last synced: 7 months ago
JSON representation
Walkthrough.js is a lightweight, dependency-free JavaScript library for creating interactive tutorials, product tours, and onboarding experiences. It features smart positioning, progress tracking, customizable templates, and works seamlessly across browsers and devices.
- Host: GitHub
- URL: https://github.com/ronanarm/walkthroughjs
- Owner: ronanarm
- License: lgpl-3.0
- Created: 2025-09-30T18:32:53.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-09-30T19:26:07.000Z (7 months ago)
- Last Synced: 2025-09-30T19:28:52.530Z (7 months ago)
- Topics: frontend, guide, javascript, onboarding, product-tour, react, reactjs, tutorial, ui, ux, vue, vuejs, walkthrough
- Language: JavaScript
- Homepage:
- Size: 0 Bytes
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Walkthrough.js
Create beautiful, interactive tutorials and onboarding experiences for your web applications with zero dependencies.
[Live Demo](https://ronanarm.github.io/WalkthroughJS/demo/)
  
## ✨ 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
#### A\. Local
```html
```
#### B\. UNPKG CDN
```html
```
#### C\. jsDelivr CDN
```html
```
#### D\. NPM (Preferred)
```bash
npm install @ronanarm/walkthroughjs
```
### 2\. Add Data Attributes (Easiest Method)
```HTML
Content to highlight
Action Button
```
### 3\. Start the Walkthrough
```javascript
// 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:
```HTML
Dashboard Content
const tour = walkthrough.fromAttributes({
progressColor: '#667eea',
rememberProgress: true
});
tour.start();
```
### Method 2: JSON Configuration
Use JavaScript objects for programmatic control:
```javascript
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:
```javascript
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:
```javascript
const tour = walkthrough.fromJSON({
steps: [...],
templates: {
popup: (step, index, total) => {
const isLast = index === total - 1;
return `
${step.title}
${step.text}
`;
}
}
});
```
## 🔌 Event Callbacks
```javascript
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
```javascript
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](/src/demo-quickstart.html)
- [demo-attributes.html](/src/demo-attributes.html)
- [demo-json.html](/src/demo-json.html)
- [demo-custom-template.html](/src/demo-custom-template.html)
## 📄 License
LGPL License - see [LICENSE](LICENSE.md) file for details.
## 🤝 Contributing
Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.
## 📞 Support
- 🐛 Issues: [GitHub Issues](https://github.com/yourusername/walkthrough-js/issues)
- 💬 Discussions: [GitHub Discussions](https://github.com/yourusername/walkthrough-js/discussions)