npm package: @raj-dev/tourlite
Description: Ultra-lightweight, framework-agnostic user onboarding, guided tour, product walkthrough, interactive tutorial, and step-by-step help library for web applications
Author: Raj
Latest version: 1.0.5

# 🎯 Tourlite

<div align="center">

**Ultra-lightweight, framework-agnostic user onboarding, product tour, interactive walkthrough, and step-by-step tutorial library for web applications**

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Bundle Size](https://img.shields.io/badge/bundle%20size-5.2KB-brightgreen)](https://bundlephobia.com/package/@raj-dev/tourlite)
[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](package.json)

[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-FFDD00?style=flat&logo=buy-me-a-coffee&logoColor=black)](https://buymeacoffee.com/rajappar412)
[![GitHub Sponsors](https://img.shields.io/badge/GitHub%20Sponsors-EA4AAA?style=flat&logo=github&logoColor=white)](https://github.com/sponsors/RajappaR)

</div>

---

## ✨ 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

### Basic Usage

```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();
});
```

### Using CSS Selectors

```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"
    }
  ]
});
```

### Using DOM Elements

```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"
    }
  ]
});
```

### Programmatic Control

```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");
}
```

### Theme Customization

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.

### Lifecycle Callbacks

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

### 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.

```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)

### 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:

```javascript
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:

```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.

### 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

```bash
# 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.

---

<div align="center">

**Made with ❤️ for lightweight web experiences**

[Report Bug](https://github.com/yourusername/tourlite/issues) · [Request Feature](https://github.com/yourusername/tourlite/issues)

---

### ☕ Support This Project

If Tourlite has been helpful to you, consider supporting its development:

[![Buy Me A Coffee](https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png)](https://buymeacoffee.com/rajappar412)

<a href="https://github.com/sponsors/RajappaR" target="_blank">
  <img src="https://img.shields.io/badge/Sponsor%20on%20GitHub-EA4AAA?style=for-the-badge&logo=github&logoColor=white" alt="GitHub Sponsors" height="50">
</a>

</div>