guide-it

v1.0.6

Published

7 months ago

A lightweight, customizable tour/onboarding library for web applications

Guide It

A powerful, lightweight tour/onboarding library for web applications. Create beautiful user experiences with minimal setup and maximum flexibility.

✨ Features

🎯 Easy to Use - Simple API with just a few lines of code
🎨 Auto CSS Injection - No need to import CSS files, styles are automatically injected
🚀 Step Actions - Execute API calls, navigation, and DOM manipulation during tours
📱 Responsive Design - Works perfectly on desktop, tablet, and mobile
⌨️ Keyboard Navigation - Full keyboard support for accessibility
🎭 TypeScript Support - Built with TypeScript for better development experience
🎪 Smart Positioning - Intelligent tooltip positioning with bubble pointer
🎨 Customizable - Fully customizable appearance and behavior
🚀 Lightweight - Small bundle size with no external dependencies
🔄 Async Support - Handle asynchronous operations and API calls
🎪 Flexible Positioning - Smart positioning with fallback options

📦 Installation

npm install guide-it

🚀 Quick Start

1. Import and Use (No CSS Import Needed!)

import { Tour } from 'guide-it';

const tour = new Tour({
  steps: [
    {
      id: 'welcome',
      element: '#my-button',
      title: 'Welcome!',
      content: 'This is your first tour step.',
      position: 'bottom'
    }
  ]
});

tour.start(); // CSS is automatically injected!

📖 Basic Usage

HTML Structure (No CSS Import Required!)

<!DOCTYPE html>
<html>
<head>
  <title>Guide It Example</title>
</head>
<body>
  <button id="my-button">Click me!</button>
  <div id="my-content">Some content</div>
  
  <script src="node_modules/guide-it/dist/index.js"></script>
  <script>
    // Your tour code here - CSS is auto-injected!
  </script>
</body>
</html>

JavaScript

const tour = new GuideIt.Tour({
  steps: [
    {
      id: 'step1',
      element: '#my-button',
      title: 'First Step',
      content: 'This is the first step of your tour.',
      position: 'bottom'
    },
    {
      id: 'step2',
      element: '#my-content',
      title: 'Second Step',
      content: 'This is the second step.',
      position: 'top'
    }
  ]
});

// Start the tour
tour.start();

API Reference

Tour Class

Constructor

new Tour(options: TourOptions)

Methods

start() - Start the tour
next() - Go to the next step
previous() - Go to the previous step
complete() - Complete the tour
exit() - Exit the tour

TourStep Interface

interface TourStep {
  id: string;                    // Unique identifier
  element?: string;              // CSS selector for the target element
  title: string;                 // Step title
  content: string;               // Step content (HTML supported)
  position?: 'top' | 'bottom' | 'left' | 'right' | 'auto';
  offset?: number;               // Offset in pixels
  highlight?: boolean;           // Whether to highlight the element
  showSkip?: boolean;            // Show skip button
  showPrevious?: boolean;       // Show previous button
  showNext?: boolean;           // Show next button
  showFinish?: boolean;         // Show finish button
  action?: () => void | Promise<void>; // Action to execute when step is active
}

TourOptions Interface

interface TourOptions {
  steps: TourStep[];            // Array of tour steps
  startAt?: number;             // Starting step index
  showProgress?: boolean;       // Show progress indicator
  showBullets?: boolean;        // Show step bullets
  keyboardNavigation?: boolean;  // Enable keyboard navigation
  exitOnOverlayClick?: boolean; // Exit when clicking overlay
  exitOnEscape?: boolean;       // Exit on Escape key
  onStart?: () => void;         // Called when tour starts
  onComplete?: (index: number) => void; // Called when tour completes
  onStepChange?: (step: TourStep, index: number) => void; // Called on step change
  onExit?: (index: number) => void; // Called when tour exits
}

🚀 Step Actions

Guide It supports powerful step actions that execute when each step becomes active. Perfect for API calls, navigation, DOM manipulation, and more!

Basic Step Actions

const tour = new Tour({
  steps: [
    {
      id: 'api-step',
      element: '#user-data',
      title: 'Load User Data',
      content: 'This will fetch your user information.',
      action: async () => {
        // Fetch user data
        const userData = await fetch('/api/user').then(r => r.json());
        document.getElementById('user-name').textContent = userData.name;
        console.log('User data loaded:', userData);
      }
    },
    {
      id: 'navigation-step',
      element: '#dashboard',
      title: 'Navigate to Dashboard',
      content: 'This will take you to your dashboard.',
      action: () => {
        // Navigate to dashboard
        window.location.href = '/dashboard';
      }
    }
  ]
});

Common Use Cases

1. API Integration

{
  id: 'load-data',
  element: '#data-section',
  title: 'Load Data',
  content: 'Fetching your latest data...',
  action: async () => {
    const response = await fetch('/api/data');
    const data = await response.json();
    updateDataDisplay(data);
  }
}

2. DOM Manipulation

{
  id: 'highlight-feature',
  element: '#new-feature',
  title: 'New Feature',
  content: 'Check out this amazing new feature!',
  action: () => {
    // Highlight the feature
    document.querySelector('#new-feature').classList.add('highlighted');
    // Add animation
    document.querySelector('#new-feature').style.animation = 'pulse 2s infinite';
  }
}

3. Form Preparation

{
  id: 'prepare-form',
  element: '#contact-form',
  title: 'Contact Form',
  content: 'Fill out this form to get in touch.',
  action: () => {
    // Focus first input
    document.querySelector('#name').focus();
    // Pre-fill with user data
    document.querySelector('#email').value = user.email;
  }
}

4. State Management

{
  id: 'open-panel',
  element: '#settings-panel',
  title: 'Settings',
  content: 'Configure your preferences here.',
  action: () => {
    // Open settings panel
    document.querySelector('#settings-toggle').click();
    // Update UI state
    document.body.classList.add('settings-open');
  }
}

Advanced Step Actions

Async Operations with Loading States

{
  id: 'async-data',
  element: '#dashboard',
  title: 'Loading Dashboard',
  content: 'Preparing your dashboard data...',
  action: async () => {
    // Show loading state
    document.querySelector('#dashboard').innerHTML = '<div class="loading">Loading...</div>';
    
    try {
      // Fetch multiple data sources
      const [userData, analytics, notifications] = await Promise.all([
        fetchUserData(),
        fetchAnalytics(),
        fetchNotifications()
      ]);
      
      // Update dashboard
      renderDashboard({ userData, analytics, notifications });
    } catch (error) {
      // Handle errors
      document.querySelector('#dashboard').innerHTML = '<div class="error">Failed to load data</div>';
    }
  }
}

Complex Multi-Step Processes

{
  id: 'complex-process',
  element: '#process-widget',
  title: 'Complex Process',
  content: 'This will run a complex multi-step process.',
  action: async () => {
    const steps = ['Initializing...', 'Processing...', 'Finalizing...'];
    
    for (let i = 0; i < steps.length; i++) {
      updateProcessStatus(steps[i]);
      await new Promise(resolve => setTimeout(resolve, 1000));
    }
    
    completeProcess();
  }
}

Examples

React.js Integration

Guide It works seamlessly with React.js applications. Check out the React.js Example for a comprehensive demonstration:

// React.js-style tour configuration
const tour = new Tour({
  steps: [
    {
      id: 'welcome',
      element: '#header',
      title: '🚀 Welcome to Guide It!',
      content: 'This is a React.js-style tour example.',
      position: 'bottom',
      action: () => {
        // Simulate React state update
        const [userState, setUserState] = useState({ name: 'React User' });
        setUserState({ name: 'React User', tourStarted: true });
      }
    }
  ],
  onStart: () => {
    console.log('🚀 React.js Tour Started');
    // Simulate React component mounting
    const [tourState, setTourState] = useState({ isActive: true });
  }
});

React.js Features Demonstrated:

React-style component lifecycle simulation
useState and useEffect hooks integration
Component state management during tours
Event handling with React patterns
Async operations and data fetching
Component mounting and unmounting

Basic Tour

const tour = new Tour({
  steps: [
    {
      id: 'welcome',
      element: '#header',
      title: 'Welcome!',
      content: 'This is a basic tour step.',
      position: 'bottom'
    }
  ]
});

Tour with Custom Options

const tour = new Tour({
  steps: tourSteps,
  showProgress: true,
  keyboardNavigation: true,
  exitOnEscape: true,
  onStart: () => console.log('Tour started'),
  onComplete: () => console.log('Tour completed')
});

Modal Tour (No Highlighting)

const tour = new Tour({
  steps: [
    {
      id: 'modal',
      title: 'Important Information',
      content: 'This is a modal-style tour without highlighting.',
      highlight: false
    }
  ]
});

Tour with Callbacks

const tour = new Tour({
  steps: steps,
  onStart: () => {
    console.log('Tour started');
    // Track analytics
  },
  onStepChange: (step, index) => {
    console.log(`Step ${index + 1}: ${step.title}`);
    // Update progress bar
  },
  onComplete: (index) => {
    console.log('Tour completed');
    // Show completion message
  },
  onExit: (index) => {
    console.log(`Tour exited at step ${index + 1}`);
    // Track exit analytics
  }
});

Tour with Step Actions

const tour = new Tour({
  steps: [
    {
      id: 'welcome',
      element: '#header',
      title: 'Welcome!',
      content: 'Let\'s start your journey.',
      action: () => {
        // Highlight the header
        document.querySelector('#header').style.border = '2px solid #007bff';
        console.log('Welcome step activated!');
      }
    },
    {
      id: 'api-step',
      element: '#user-data',
      title: 'Load User Data',
      content: 'This will fetch your user information.',
      action: async () => {
        // Fetch user data
        const userData = await fetch('/api/user').then(r => r.json());
        document.getElementById('user-name').textContent = userData.name;
        console.log('User data loaded:', userData);
      }
    },
    {
      id: 'form-step',
      element: '#contact-form',
      title: 'Contact Form',
      content: 'Fill out this form to get started.',
      action: () => {
        // Scroll to form and focus first input
        document.querySelector('#contact-form').scrollIntoView({ behavior: 'smooth' });
        setTimeout(() => {
          document.querySelector('#name').focus();
        }, 500);
      }
    }
  ]
});

Styling

The library comes with default styles, but you can customize them by overriding the CSS classes:

/* Custom overlay */
.guide-it-overlay {
  background: rgba(0, 0, 0, 0.8);
}

/* Custom tooltip */
.guide-it-tooltip {
  background: #your-color;
  border-radius: 12px;
}

/* Custom highlight */
.guide-it-highlight {
  border-color: #your-color;
  box-shadow: 0 0 0 4px rgba(your-color, 0.2);
}

Keyboard Navigation

Escape - Exit the tour
Arrow Right or Enter - Next step
Arrow Left - Previous step

Browser Support

Chrome 60+
Firefox 55+
Safari 12+
Edge 79+

Development

Building from Source

# Clone the repository
git clone https://github.com/zaidhasan1/guide-it.git

# Install dependencies
npm install

# Build the project
npm run build

# Watch for changes
npm run dev

Project Structure

guide-it/
├── dist/                           # Compiled JavaScript output
├── examples/                       # Example files and demonstrations
│   ├── example.html               # Basic example HTML file
│   ├── usage-example.html         # Advanced usage examples
│   ├── action-examples.html       # Step actions demonstration
│   ├── react-example.html         # React.js integration example
│   └── test-injection.html        # CSS injection test
├── index.ts                       # Main entry point
├── Tour.ts                        # Tour class implementation (includes CSS injection)
├── types.ts                       # TypeScript type definitions
├── package.json                   # Package configuration
├── tsconfig.json                  # TypeScript configuration
└── README.md                      # This file

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

License

MIT License - see LICENSE file for details.

Changelog

1.0.2

✨ Step Actions - Execute API calls, navigation, and DOM manipulation during tours
🎨 Auto CSS Injection - No need to import CSS files, styles are automatically injected
🎪 Smart Positioning - Intelligent tooltip positioning with bubble pointer
🔄 Async Support - Handle asynchronous operations and API calls
📱 Enhanced Responsive Design - Better mobile and tablet support
🎯 Improved TypeScript Support - Better type definitions and IntelliSense

1.0.0

Initial release
Basic tour functionality
TypeScript support
Responsive design
Keyboard navigation
Customizable styling

Support

If you encounter any issues or have questions, please:

Check the example files in the examples/ folder:
- Basic Example - Simple tour setup
- Usage Examples - Advanced features
- Action Examples - Step actions demonstration
- React.js Example - React.js integration example
- CSS Injection Test - Auto CSS injection test
Review the API documentation above
Open an issue on GitHub

Roadmap

[x] Step Actions - Execute custom code during tours
[x] Auto CSS Injection - No CSS import required
[x] Smart Positioning - Intelligent tooltip placement
[x] Async Support - Handle asynchronous operations
[x] React.js Integration - Comprehensive React.js example and patterns
[ ] React component wrapper
[ ] Vue.js component wrapper
[ ] Angular directive
[ ] Animation options
[ ] Tour templates
[ ] Analytics integration
[ ] Accessibility improvements
[ ] Tour persistence (save progress)
[ ] Conditional step logic
[ ] Multi-page tour support