{"id":31626512,"url":"https://github.com/ronanarm/walkthroughjs","last_synced_at":"2025-10-06T19:53:11.479Z","repository":{"id":317418808,"uuid":"1067354575","full_name":"ronanarm/WalkthroughJS","owner":"ronanarm","description":"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.","archived":false,"fork":false,"pushed_at":"2025-09-30T19:26:07.000Z","size":0,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-30T19:28:52.530Z","etag":null,"topics":["frontend","guide","javascript","onboarding","product-tour","react","reactjs","tutorial","ui","ux","vue","vuejs","walkthrough"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ronanarm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-30T18:32:53.000Z","updated_at":"2025-09-30T19:26:10.000Z","dependencies_parsed_at":"2025-09-30T19:28:54.941Z","dependency_job_id":null,"html_url":"https://github.com/ronanarm/WalkthroughJS","commit_stats":null,"previous_names":["ronanarm/walkthroughjs"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ronanarm/WalkthroughJS","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ronanarm%2FWalkthroughJS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ronanarm%2FWalkthroughJS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ronanarm%2FWalkthroughJS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ronanarm%2FWalkthroughJS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ronanarm","download_url":"https://codeload.github.com/ronanarm/WalkthroughJS/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ronanarm%2FWalkthroughJS/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278671740,"owners_count":26025743,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-06T02:00:05.630Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["frontend","guide","javascript","onboarding","product-tour","react","reactjs","tutorial","ui","ux","vue","vuejs","walkthrough"],"created_at":"2025-10-06T19:53:10.281Z","updated_at":"2025-10-06T19:53:11.472Z","avatar_url":"https://github.com/ronanarm.png","language":"JavaScript","readme":"# Walkthrough.js\n\nCreate beautiful, interactive tutorials and onboarding experiences for your web applications with zero dependencies.\n\n[Live Demo](https://ronanarm.github.io/WalkthroughJS/demo/)\n\n![Walkthrough.js Demo](https://img.shields.io/badge/demo-live-brightgreen) ![Version](https://img.shields.io/badge/version-1.0.0-blue) ![License](https://img.shields.io/badge/license-LGPL-green)\n\n## ✨ Features\n\n- **🎨 Beautiful Design** - Modern, polished UI with smooth animations\n- **⌨️ Keyboard Navigation** - Full support for arrow keys, Enter, and Escape\n- **📱 Responsive** - Works perfectly on all screen sizes and devices\n- **🎯 Smart Positioning** - Automatic popup positioning to stay visible\n- **💾 Progress Tracking** - Remember where users left off\n- **🔌 Event Callbacks** - Hook into lifecycle events for custom behavior\n- **🎨 Customizable** - Colors, positions, templates, and styling options\n- **⚡ Multiple Setup Methods** - HTML attributes, JSON config, or quick start\n- **🧩 Custom Templates** - Complete control over popup HTML structure\n\n## 🚀 Quick Start\n\n### 1\\. Include the Library\n\n#### A\\. Local\n```html\n\u003cscript src=\"walkthrough.js\"\u003e\u003c/script\u003e  \n```\n\n#### B\\. UNPKG CDN\n```html\n\u003cscript src=\"https://unpkg.com/@ronanarm/walkthroughjs@latest\"\u003e\u003c/script\u003e  \n```\n\n#### C\\. jsDelivr CDN\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/gh/ronanarm/WalkthroughJS@main/src/walkthrough.min.js\"\u003e\u003c/script\u003e  \n```\n\n#### D\\. NPM (Preferred)\n```bash\nnpm install @ronanarm/walkthroughjs\n```\n\n### 2\\. Add Data Attributes (Easiest Method)\n\n```HTML\n\u003cdiv data-wt-step=\"1\"   \n     data-wt-title=\"Welcome!\"   \n     data-wt-text=\"This is your first step.\"   \n     data-wt-position=\"bottom\"\u003e  \n  Content to highlight  \n\u003c/div\u003e  \n  \n\u003cbutton data-wt-step=\"2\"   \n        data-wt-title=\"Click Here\"   \n        data-wt-text=\"This button does something important.\"\u003e  \n  Action Button  \n\u003c/button\u003e  \n```\n\n### 3\\. Start the Walkthrough\n\n```javascript\n// Start from HTML attributes  \nconst tour = walkthrough.fromAttributes();  \ntour.start();  \n  \n// Or use the quick start method  \nwalkthrough.start([  \n  {  \n    element: '.my-element',  \n    title: 'Step 1',  \n    text: 'This is the first step',  \n    position: 'bottom'  \n  },  \n  {  \n    element: '#my-button',  \n    title: 'Step 2',   \n    text: 'Click this button to continue',  \n    position: 'top'  \n  }  \n]);  \n```\n\n## 📖 Usage Methods\n\n### Method 1: HTML Data Attributes\n\nThe simplest way to add walkthroughs. Just add data attributes to your HTML elements:\n\n```HTML\n\u003cdiv data-wt-step=\"1\"   \n     data-wt-title=\"Welcome\"   \n     data-wt-text=\"This is your dashboard\"   \n     data-wt-position=\"bottom\"\u003e  \n  Dashboard Content  \n\u003c/div\u003e  \n  \n\u003cscript\u003e  \nconst tour = walkthrough.fromAttributes({  \n  progressColor: '#667eea',  \n  rememberProgress: true  \n});  \ntour.start();  \n\u003c/script\u003e  \n```\n\n### Method 2: JSON Configuration\n\nUse JavaScript objects for programmatic control:\n\n```javascript\nconst tour = walkthrough.fromJSON({  \n  steps: [  \n    {  \n      element: '.header',  \n      title: 'Navigation',  \n      text: 'This is your main navigation area',  \n      position: 'bottom'  \n    },  \n    {  \n      element: '#sidebar',  \n      title: 'Sidebar',  \n      text: 'Access tools and settings here',  \n      position: 'right',  \n      nextText: 'Got it! →'  \n    }  \n  ],  \n  options: {  \n    progressColor: '#764ba2',  \n    highlightPadding: 15,  \n    animationDuration: 400  \n  },  \n  callbacks: {  \n    onStart: () =\u003e console.log('Tour started'),  \n    onFinish: () =\u003e console.log('Tour completed')  \n  }  \n});  \n  \ntour.start();  \n```\n\n### Method 3: Quick Start\n\nPerfect for rapid prototyping:\n\n```javascript\nwalkthrough.start([  \n  {  \n    element: '.feature',  \n    title: 'New Feature',  \n    text: 'Check out this new feature!',  \n    position: 'bottom'  \n  }  \n], {  \n  progressColor: '#28a745',  \n  onFinish: () =\u003e alert('Tour complete!')  \n});  \n```\n\n## 🎛️ Configuration Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `progressColor` | string | `'#007bff'` | Color of the progress indicator |\n| `highlightPadding` | number | `10` | Padding around highlighted elements |\n| `animationDuration` | number | `300` | Animation duration in milliseconds |\n| `rememberProgress` | boolean | `true` | Remember user's progress in localStorage |\n| `showProgress` | boolean | `true` | Show step progress indicator |\n| `allowClose` | boolean | `true` | Allow users to close the walkthrough |\n| `backdrop` | boolean | `true` | Show backdrop overlay |\n| `backdropColor` | string | `'rgba(0,0,0,0.5)'` | Backdrop overlay color |\n\n## 📍 Position Options\n\n- `'top'` - Above the element\n- `'bottom'` - Below the element\n- `'left'` - To the left of the element\n- `'right'` - To the right of the element\n- `'center'` - Centered on screen\n\n## 🎨 Custom Templates\n\nTake full control of the popup HTML:\n\n```javascript\nconst tour = walkthrough.fromJSON({  \n  steps: [...],  \n  templates: {  \n    popup: (step, index, total) =\u003e {  \n      const isLast = index === total - 1;  \n      return `  \n        \u003cdiv class=\"my-custom-popup\"\u003e  \n          \u003ch2\u003e${step.title}\u003c/h2\u003e  \n          \u003cp\u003e${step.text}\u003c/p\u003e  \n          \u003cdiv class=\"buttons\"\u003e  \n            ${index \u003e 0 ? `\u003cbutton onclick=\"currentWalkthrough.prev()\"\u003eBack\u003c/button\u003e` : ''}  \n            \u003cbutton onclick=\"currentWalkthrough.${isLast ? 'finish' : 'next'}()\"\u003e  \n              ${isLast ? 'Finish' : 'Next'}  \n            \u003c/button\u003e  \n          \u003c/div\u003e  \n        \u003c/div\u003e  \n      `;  \n    }  \n  }  \n});  \n```\n\n## 🔌 Event Callbacks\n\n```javascript\nconst tour = walkthrough.fromJSON({  \n  steps: [...],  \n  callbacks: {  \n    onStart: () =\u003e {  \n      console.log('Walkthrough started');  \n    },  \n    onStep: (step, index) =\u003e {  \n      console.log(`Now on step ${index + 1}: ${step.title}`);  \n    },  \n    onNext: (step, index) =\u003e {  \n      console.log('Moving to next step');  \n    },  \n    onPrev: (step, index) =\u003e {  \n      console.log('Moving to previous step');  \n    },  \n    onFinish: () =\u003e {  \n      console.log('Walkthrough completed');  \n    },  \n    onClose: () =\u003e {  \n      console.log('Walkthrough closed');  \n    }  \n  }  \n});  \n```\n\n## 🎮 API Methods\n\n```javascript\n\tconst tour = walkthrough.fromJSON({...});  \n  \n// Control methods  \ntour.start();           // Start the walkthrough  \ntour.next();            // Go to next step  \ntour.prev();            // Go to previous step  \ntour.goTo(stepIndex);   // Jump to specific step  \ntour.finish();          // Complete the walkthrough  \ntour.close();           // Close without completing  \ntour.destroy();         // Clean up and remove  \n  \n// State methods  \ntour.getCurrentStep();  // Get current step object  \ntour.getCurrentIndex(); // Get current step index  \ntour.getTotalSteps();   // Get total number of steps  \ntour.isActive();        // Check if walkthrough is running  \n```\n\n## ⌨️ Keyboard Navigation\n\n- **→ / ↓** - Next step\n- **← / ↑** - Previous step\n- **Enter** - Next step\n- **Escape** - Close walkthrough\n- **Home** - Go to first step\n- **End** - Go to last step\n\n## 🎯 HTML Data Attributes Reference\n\n| Attribute | Description | Example |\n|-----------|-------------|---------|\n| `data-wt-step` | Step number (required) | `data-wt-step=\"1\"` |\n| `data-wt-title` | Step title | `data-wt-title=\"Welcome\"` |\n| `data-wt-text` | Step description | `data-wt-text=\"This is the main menu\"` |\n| `data-wt-position` | Popup position | `data-wt-position=\"bottom\"` |\n| `data-wt-next-text` | Custom next button text | `data-wt-next-text=\"Continue →\"` |\n| `data-wt-prev-text` | Custom previous button text | `data-wt-prev-text=\"← Back\"` |\n\n## 🌟 Examples\n\nCheck out the demo files for comprehensive examples of all features and configuration methods.\n- [demo-quickstart.html](/src/demo-quickstart.html)\n- [demo-attributes.html](/src/demo-attributes.html)\n- [demo-json.html](/src/demo-json.html)\n- [demo-custom-template.html](/src/demo-custom-template.html)\n\n## 📄 License\n\nLGPL License - see [LICENSE](LICENSE.md) file for details.\n\n## 🤝 Contributing\n\nContributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.\n\n## 📞 Support\n\n- 🐛 Issues: [GitHub Issues](https://github.com/yourusername/walkthrough-js/issues)\n- 💬 Discussions: [GitHub Discussions](https://github.com/yourusername/walkthrough-js/discussions)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fronanarm%2Fwalkthroughjs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fronanarm%2Fwalkthroughjs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fronanarm%2Fwalkthroughjs/lists"}