🎯 Tourlite

Ultra-lightweight, framework-agnostic user onboarding, product tour, interactive walkthrough, and step-by-step tutorial library for web applications

✨ 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

npm install @raj-dev/tourlite

🚀 Quick Start

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

Basic Usage

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();
});

Using CSS Selectors

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"
    }
  ]
});

Using DOM Elements

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"
    }
  ]
});

Programmatic Control

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");
}

Theme Customization

Customize the tour appearance to match your brand:

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.

Lifecycle Callbacks

Track tour events with optional callbacks:

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

Constructor

new Tourlite(options)

Creates a new tour instance.

Parameters:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | options | Object | Yes | Configuration object | | options.steps | Array<Step> | 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") |

Methods

tour.start()

Starts the tour from the first step.

tour.start();

tour.end()

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

tour.end();

tour.next()

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

tour.next();

tour.prev()

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

tour.prev();

tour.destroy()

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

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)

Animations

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.

Theme Customization

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

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

CSS Override

You can also override styles using CSS if needed:

.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.

vs. Other Libraries

| 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 |

Use Cases

• 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

Design Philosophy

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

# Clone the repository
git clone <repository-url>
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

☕ Support This Project

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