WebTour

A flexible and framework-agnostic web tour library for creating interactive guided tours on any website. Works seamlessly with React, Vue, Angular, or vanilla JavaScript.

Features

✨ Framework Agnostic - Works with any JavaScript framework or library
🎨 Custom Tooltips - Full control over tooltip design and rendering
⌨️ Keyboard Navigation - Support for arrow keys and ESC
📱 Responsive - Automatically adjusts to different screen sizes
🎯 Smart Positioning - Auto-positions tooltips to stay in viewport
🔄 Event Callbacks - Extensive callback system for custom behavior
🎭 Overlay & Highlighting - Beautiful overlay with element highlighting
📊 Progress Tracking - Built-in progress indicators and bullets
⚙️ Highly Configurable - 30+ options to customize behavior

Installation

npm install @webtour/core

Or include directly in HTML:

<script src="path/to/index.js"></script>

Quick Start

const tour = new WebTour({
  steps: [
    {
      title: 'Welcome!',
      content: 'Let me show you around.',
      element: '#my-element'
    },
    {
      title: 'Step 2',
      content: 'This is another feature.',
      element: '.my-class',
      position: 'bottom'
    }
  ]
});

tour.start();

Usage Examples

Basic Tour

const tour = new WebTour({
  steps: [
    {
      title: 'Dashboard',
      content: 'This is your main dashboard.',
      element: '#dashboard'
    },
    {
      title: 'Settings',
      content: 'Click here to access settings.',
      element: '#settings-btn',
      position: 'left'
    }
  ],
  onEnd: () => {
    console.log('Tour completed!');
  }
});

tour.start();

With Callbacks

const tour = new WebTour({
  steps: [...],
  
  // Lifecycle callbacks
  onStart: (tour) => {
    console.log('Tour started');
  },
  onEnd: (tour) => {
    localStorage.setItem('tourCompleted', 'true');
  },
  onChange: (tour, oldIndex, newIndex) => {
    console.log(`Step ${oldIndex} -> ${newIndex}`);
  },
  onShow: (tour, index) => {
    console.log(`Showing step ${index}`);
  },
  onSkip: (tour, currentIndex) => {
    console.log(`Tour skipped at step ${currentIndex}`);
  }
});

Custom Tooltip Renderer

const tour = new WebTour({
  steps: [
    {
      title: 'Custom Design',
      content: 'This uses a custom tooltip!',
      element: '#element',
      customData: { icon: '🎨', color: '#667eea' }
    }
  ],
  
  customTooltipRenderer: (step, index, tour) => {
    // Return HTML string
    return `
      <div style="background: ${step.customData.color}; padding: 20px;">
        <div style="font-size: 32px;">${step.customData.icon}</div>
        <h3>${step.title}</h3>
        <p>${step.content}</p>
        <button onclick="tour.next()">Next</button>
      </div>
    `;
    
    // OR return DOM element
    const container = document.createElement('div');
    // ... build your custom tooltip
    return container;
  }
});

React Integration

import { useEffect, useRef } from 'react';
import WebTour from '@webtour/core';

function MyComponent() {
  const tourRef = useRef(null);

  useEffect(() => {
    tourRef.current = new WebTour({
      steps: [
        {
          title: 'Welcome to React App',
          content: 'This is a guided tour.',
          element: '#app-header'
        }
      ],
      onEnd: () => {
        console.log('Tour finished');
      }
    });

    return () => {
      if (tourRef.current && tourRef.current.isRunning()) {
        tourRef.current.end();
      }
    };
  }, []);

  const startTour = () => {
    tourRef.current.start();
  };

  return (
    <div>
      <button onClick={startTour}>Start Tour</button>
    </div>
  );
}

Vue Integration

<template>
  <div>
    <button @click="startTour">Start Tour</button>
  </div>
</template>

<script>
import WebTour from '@webtour/core';

export default {
  data() {
    return {
      tour: null
    };
  },
  
  mounted() {
    this.tour = new WebTour({
      steps: [
        {
          title: 'Welcome',
          content: 'This is a Vue app tour.',
          element: '#app'
        }
      ]
    });
  },
  
  beforeUnmount() {
    if (this.tour && this.tour.isRunning()) {
      this.tour.end();
    }
  },
  
  methods: {
    startTour() {
      this.tour.start();
    }
  }
};
</script>

Configuration Options

Tour Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | steps | Array | [] | Array of step objects | | autoStart | Boolean | false | Start tour automatically | | animationDuration | Number | 300 | Animation duration in ms | | animationEasing | String | 'ease-in-out' | CSS easing function |

Overlay Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | showOverlay | Boolean | true | Show overlay backdrop | | overlayOpacity | Number | 0.7 | Overlay opacity (0-1) | | overlayColor | String | '#000' | Overlay color | | overlayClickSkip | Boolean | false | Skip tour on overlay click |

Navigation Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | showButtons | Boolean | true | Show navigation buttons | | showProgress | Boolean | true | Show progress counter | | showBullets | Boolean | false | Show step bullets | | allowKeyboard | Boolean | true | Enable keyboard navigation |

Button Text

| Option | Type | Default | Description | |--------|------|---------|-------------| | nextBtnText | String | 'Next' | Next button text | | prevBtnText | String | 'Previous' | Previous button text | | doneBtnText | String | 'Done' | Done button text | | skipBtnText | String | 'Skip' | Skip button text |

Highlight Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | highlightPadding | Number | 10 | Padding around highlighted element | | highlightBorderRadius | Number | 4 | Border radius of highlight |

Positioning Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | tooltipPosition | String | 'auto' | Tooltip position: auto, top, bottom, left, right | | tooltipOffset | Number | 10 | Offset from target element |

Scroll Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | scrollToElement | Boolean | true | Scroll to element on step | | scrollBehavior | String | 'smooth' | Scroll behavior: smooth, auto | | scrollOffset | Number | 100 | Scroll offset from element |

Custom Styling

| Option | Type | Default | Description | |--------|------|---------|-------------| | tooltipClass | String | '' | Custom CSS class for tooltip | | highlightClass | String | '' | Custom CSS class for highlight | | customTooltipRenderer | Function | null | Custom tooltip renderer function |

Callbacks

| Callback | Parameters | Description | |----------|------------|-------------| | onStart | (tour) | Called when tour starts | | onEnd | (tour) | Called when tour ends | | onNext | (tour, currentIndex, nextIndex) | Called on next step | | onPrevious | (tour, currentIndex, prevIndex) | Called on previous step | | onShow | (tour, index) | Called when step is shown | | onHide | (tour, index) | Called when step is hidden | | onSkip | (tour, currentIndex) | Called when tour is skipped | | onChange | (tour, oldIndex, newIndex) | Called when step changes |

Step Configuration

Each step object can have the following properties:

{
  title: 'Step Title',              // Step title
  content: 'Step content...',       // Step content (HTML supported)
  element: '#selector',             // Target element (CSS selector or DOM element)
  position: 'auto',                 // Tooltip position (auto, top, bottom, left, right)
  offset: 10,                       // Offset from element
  highlightPadding: 10,            // Padding around highlight
  
  // Custom data (accessible in custom renderer)
  customData: { ... }
}

API Methods

start()

Start the tour from the beginning.

tour.start();

end()

End the tour and cleanup.

tour.end();

next()

Go to the next step.

tour.next();

previous()

Go to the previous step.

tour.previous();

skip()

Skip the tour.

tour.skip();

goToStep(index)

Go to a specific step by index.

tour.goToStep(2); // Go to third step

addStep(step)

Add a new step to the tour.

tour.addStep({
  title: 'New Step',
  content: 'This is a new step',
  element: '#new-element'
});

removeStep(index)

Remove a step by index.

tour.removeStep(2); // Remove third step

getCurrentStep()

Get the current step object.

const step = tour.getCurrentStep();

getTotalSteps()

Get the total number of steps.

const total = tour.getTotalSteps();

isRunning()

Check if the tour is currently active.

if (tour.isRunning()) {
  console.log('Tour is active');
}

Keyboard Shortcuts

When allowKeyboard is enabled:

• → or ↓ - Next step
• ← or ↑ - Previous step
• ESC - Skip tour

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Examples

Check out the example.html file for a complete working example with both basic and custom tooltip implementations.

To run the example:

# Open the example file in your browser
open example.html

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

If you encounter any issues or have questions, please file an issue on the GitHub repository.