🎯 Tourlite

---

✨ Features

- 🪶 Ultra-lightweight - Only 5.2 KB minified, < 2 KB gzipped - perfect for performance-critical applications
- 🚀 Zero dependencies - Pure JavaScript, no runtime dependencies - reduces bundle size and complexity
- 🎨 Framework-agnostic - Works seamlessly with React, Vue, Angular, Svelte, or vanilla JavaScript
- 🎯 Minimal DOM footprint - Uses only 2 DOM nodes (overlay + tooltip) reused across all steps - optimized for performance
- ⌨️ Keyboard navigation - Full keyboard support (Esc, Arrow keys) - accessible and user-friendly
- 🎭 Smart positioning - Automatically positions tooltips to stay in viewport - responsive and adaptive
- 🎨 Theme customization - Optional theme support to match your brand - fully customizable colors and fonts
- 🎬 Smooth animations - CSS-only fade and slide animations - lightweight and performant
- 🔔 Lifecycle callbacks - Track tour start, completion, and early exits - perfect for analytics and user tracking
- 🎪 Simple API - Clean, intuitive interface - easy to learn and implement
- 🔧 No build required - Works out of the box - ready to use immediately
- 🌐 Universal compatibility - Works in all modern browsers - Chrome, Firefox, Safari, Edge
- ⚡ Fast performance - Optimized for speed with minimal reflows and efficient DOM manipulation

📦 Installation

``bash
npm install @raj-dev/tourlite
`

🚀 Quick Start

`javascript
import Tourlite from "@raj-dev/tourlite";

const tour = new Tourlite({
steps: [
{
element: "#create-btn",
content: "Click here to create your first item"
},
{
element: ".settings",
content: "Manage preferences here"
},
{
element: document.querySelector(".profile"),
content: "View your profile"
}
]
});

tour.start();
`

📖 Usage Examples

$3

`javascript
import Tourlite from "@raj-dev/tourlite";

const tour = new Tourlite({
steps: [
{
element: "#welcome-card",
content: "Welcome! This is your dashboard."
},
{
element: "#create-button",
content: "Click here to create a new item."
},
{
element: ".settings-icon",
content: "Access your settings from here."
}
]
});

// Start the tour
document.getElementById("start-tour-btn").addEventListener("click", () => {
tour.start();
});
`

$3

`javascript
const tour = new Tourlite({
steps: [
{
element: "#header", // ID selector
content: "This is the header"
},
{
element: ".nav-item", // Class selector
content: "Navigation items"
},
{
element: "[data-tour='step3']", // Attribute selector
content: "Custom attribute selector"
}
]
});
`

$3

`javascript
const button = document.querySelector("#my-button");
const card = document.getElementById("feature-card");

const tour = new Tourlite({
steps: [
{
element: button, // Direct DOM element reference
content: "This button does something special"
},
{
element: card,
content: "This card contains important information"
}
]
});
`

$3

`javascript
const tour = new Tourlite({ steps: [...] });

// Start tour
tour.start();

// Navigate programmatically
tour.next(); // Go to next step
tour.prev(); // Go to previous step
tour.end(); // End the tour
tour.destroy(); // Alias for end()

// Check if tour is active
if (tour.isActive) {
console.log("Tour is running");
}
`

$3

Customize the tour appearance to match your brand:

`javascript
const tour = new Tourlite({
steps: [
{
element: "#feature-1",
content: "This is a custom themed tour!"
},
{
element: "#feature-2",
content: "Notice the custom colors and styling."
}
],
theme: {
primaryColor: "#ff5722", // Orange primary buttons
primaryTextColor: "#ffffff", // White text on primary
secondaryColor: "#f5f5f5", // Light gray secondary buttons
secondaryTextColor: "#333333", // Dark text on secondary
tooltipBg: "#1e1e1e", // Dark tooltip background
tooltipTextColor: "#ffffff", // White tooltip text
fontFamily: "Inter, sans-serif" // Custom font
}
});

tour.start();
`

Theme is optional - If no theme is provided, Tourlite uses beautiful defaults (white tooltip, blue buttons). You can customize any or all theme properties.

$3

Track tour events with optional callbacks:

`javascript
const tour = new Tourlite({
steps: [
{
element: "#welcome",
content: "Welcome to the tour!"
},
{
element: "#feature",
content: "This is a key feature."
}
],
onStart() {
console.log("Tour started");
// Track analytics, show welcome message, etc.
},
onDone() {
console.log("Tour completed!");
localStorage.setItem("tour_seen", "true");
// Mark tour as completed, show completion message, etc.
},
onClose() {
console.log("Tour closed early");
localStorage.setItem("tour_seen", "true");
// Handle early exit, track abandonment, etc.
}
});

tour.start();
`

Callback behavior:
- onStart() - Fired when tour.start() is called
- onDone() - Fired only when user completes the last step (clicks "Finish")
- onClose() - Fired when user exits early (close button, Esc key, or overlay click)

🎮 API Reference

$3

#### new Tourlite(options)

Creates a new tour instance.

Parameters:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| options | Object | Yes | Configuration object |
| options.steps | Array | Yes | Array of tour steps |
| options.theme | Object | No | Optional theme customization object |
| options.onStart | Function | No | Callback fired when tour starts |
| options.onDone | Function | No | Callback fired when user completes the last step |
| options.onClose | Function | No | Callback fired when user exits early (close button or Esc) |

Step Object:

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| element | String \| HTMLElement | Yes | CSS selector or DOM element to highlight |
| content | String | Yes | Text content to display in tooltip |

Theme Object (Optional):

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| theme.primaryColor | String | No | Primary button background color (e.g., "#007bff") |
| theme.primaryTextColor | String | No | Primary button text color (e.g., "#ffffff") |
| theme.secondaryColor | String | No | Secondary button background color (e.g., "#ffffff") |
| theme.secondaryTextColor | String | No | Secondary button text color (e.g., "#333333") |
| theme.tooltipBg | String | No | Tooltip background color (e.g., "#ffffff") |
| theme.tooltipTextColor | String | No | Tooltip text color (e.g., "#333333") |
| theme.fontFamily | String | No | Font family for tooltip (e.g., "Inter, sans-serif") |

$3

#### tour.start()

Starts the tour from the first step.

`javascript
tour.start();
`

#### tour.end()

Ends the tour and cleans up all DOM elements and event listeners.

`javascript
tour.end();
`

#### tour.next()

Advances to the next step. If already on the last step, ends the tour.

`javascript
tour.next();
`

#### tour.prev()

Goes back to the previous step. Does nothing if already on the first step.

`javascript
tour.prev();
`

#### tour.destroy()

Alias for end(). Ends the tour and cleans up all resources.

`javascript
tour.destroy();
`

⌨️ Keyboard Navigation

Tourlite includes full keyboard support:

| Key | Action |
|-----|--------|
| Esc | Close/end the tour |
| → (Arrow Right) | Next step |
| ← (Arrow Left) | Previous step |

🎨 Styling & Theming

Tourlite injects minimal CSS automatically. All styles use the ut-* prefix to avoid conflicts:

- .ut-overlay - The dark overlay background (fades in)
- .ut-tooltip - The tooltip container (slides up and fades in)
- .ut-content - Tooltip text content
- .ut-btn - Navigation buttons
- .ut-highlight - Highlighted element (z-index boost)

$3

Tourlite includes lightweight CSS-only animations:
- Overlay: Smooth fade-in (150ms)
- Tooltip: Slide-up and fade-in (150ms)

Animations are subtle and performant, using CSS @keyframes with no JavaScript overhead.

$3

The recommended way to customize Tourlite is through the theme option, which uses CSS variables:

`javascript
const tour = new Tourlite({
steps: [...],
theme: {
primaryColor: "#ff5722",
primaryTextColor: "#ffffff",
tooltipBg: "#1e1e1e",
tooltipTextColor: "#ffffff",
fontFamily: "Inter, sans-serif"
}
});
`

$3

You can also override styles using CSS if needed:

`css
.ut-tooltip {
background: #your-color !important;
border-radius: 12px !important;
}

.ut-btn-primary {
background: #your-brand-color !important;
}
`

Note: Theme customization via the theme option is preferred as it's more maintainable and doesn't require !important flags.

🌐 Browser Support

Tourlite works in all modern browsers that support:

- ES2020+ features
- ES Modules
- getBoundingClientRect()
- classList API

Tested in:
- ✅ Chrome 90+
- ✅ Firefox 88+
- ✅ Safari 14+
- ✅ Edge 90+

📊 Bundle Size

| Format | Size | Gzipped |
|--------|------|---------|
| ESM | 5.2 KB | ~1.8 KB |
| UMD | 5.4 KB | ~1.9 KB |

🎯 Why Tourlite?

Tourlite is the perfect solution for adding interactive product tours, user onboarding flows, step-by-step tutorials, feature highlights, and contextual help to your web application. Whether you're building a SaaS product, web app, dashboard, or any interactive website, Tourlite provides a lightweight, performant way to guide users through your interface.

$3

| Feature | Tourlite | Intro.js | Shepherd | UserGuiding |
|---------|----------|----------|----------|-------------|
| Bundle Size | 5.2 KB | ~10 KB | ~45 KB | ~50+ KB |
| Dependencies | 0 | 0 | 2+ | Multiple |
| Framework Support | All | All | All | Limited |
| DOM Nodes | 2 | Multiple | Multiple | Multiple |
| API Complexity | Simple | Medium | Complex | Complex |
| Performance | Excellent | Good | Good | Good |
| Customization | Easy | Medium | Complex | Limited |

$3

- Product Tours - Introduce new features and guide users through your application
- User Onboarding - Welcome new users and help them get started
- Feature Highlights - Draw attention to important features and updates
- Interactive Tutorials - Create step-by-step guides for complex workflows
- Contextual Help - Provide in-app assistance and tooltips
- Product Walkthroughs - Showcase your product's capabilities
- User Journey Mapping - Guide users through specific user flows
- In-App Training - Train users on how to use your application

$3

1. Minimalism - Only essential features, no bloat
2. Performance - Reuses DOM nodes, no unnecessary reflows
3. Simplicity - Easy to understand and customize
4. Compatibility - Works everywhere, no framework lock-in
5. Accessibility - Keyboard navigation and semantic HTML
6. Developer Experience - Clean API, comprehensive documentation

🛠️ Development

`bash

Clone the repository

git clone
cd ppp

Install dependencies

npm install

Build the library

npm run build

Watch mode for development

npm run dev
``

📝 License

MIT License

Copyright (c) 2025 Raj

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

---

Made with ❤️ for lightweight web experiences

Report Bug · Request Feature

---

$3

If Tourlite has been helpful to you, consider supporting its development: