React Tour Guide

A lightweight and customizable React component for creating guided tours in your web applications. Highlight elements and display step-by-step instructions to guide users through your app's features.

Features

• Highlight elements on the page.
• Step-by-step instructions with navigation.
• Keyboard navigation support.
• Customizable styles and positions.
• Progress bar and restart functionality.

Requirements

• Node.js: v16.0.0 or higher
• npm: v7.0.0 or higher

Installation

Install the package using npm:

npm install react-spotlight-tour-cct
# or
yarn add react-spotlight-tour-cct

Usage

This package provides a REACT-TOUR-GUIDE component that you can use to guide the novice user with unique features of our website.

Example

import React from "react";
import { TourGuidePopup } from "react-spotlight-tour-cct";
//import "react-spotlight-tour-cct/dist/react-spotlight-tour-cct.css"; // (Optional)

const App = () => {
  const steps = [
    { id: "step1", content: "This is the first step of the tour." },
    { id: "step2", content: "Highlight another feature in this step." },
    { id: "step3", content: "Final step of the tour!" },
  ];

  return (
    <div>
      <h1 id="step1">Welcome to the App</h1>
      <p id="step2">This paragraph is part of the tour.</p>
      <button id="step3">Click me to finish the tour!</button>

      <TourGuidePopup steps={steps} />
    </div>
  );
};

export default App;

Keyboard Shortcuts -- Right Arrow: Navigate to the next step. -- Left Arrow: Navigate to the previous step. -- Escape: Close the tour.

Props

TourGuidePopup Component

| Prop | Type | Description | Required | |-----------|-------------|----------------------------------------------------------------|----------| | steps | TourStep[]| An array of tour steps with id and content. | Yes |

TourStep Interface

interface TourStep {
  id: string;      // The ID of the element to highlight.
  content: string; // The content to display in the popup for this step.
}

CSS Classes

Below are the CSS classes used in the component and their descriptions:

| Class | Description | |----------------------|---------------------------------------------| | button-restart | Styles the "Restart Tour" button. | | tour-guide-popup | Styles the main popup container. | | popup-arrow | Styles the arrow pointing to the target. | | progress-container | Styles the progress bar container. | | progress-bar | Styles the progress bar itself. | | button-close | Styles the close button inside the popup. |

Minimul style of Restart Button

  position: fixed;
  top: 10px;
  right: 10px;
  background-color: #007bff;
  color: #fff;
  border: none;
  border-radius: 5px;
  padding: 5px 10px;
  font-size: 12px;
  cursor: pointer;
  z-index: 1002;
}

Highlight Component

This component highlights a specific element during the tour by adding a highlighted class to the element identified by its targetId prop.

import React, { useEffect } from "react";
import "./Highlight.css";

interface HighlightProps {
  targetId: string;
}

export const Highlight: React.FC<HighlightProps> = ({ targetId }) => {
  useEffect(() => {
    const targetElement = document.getElementById(targetId);
    if (targetElement) {
      targetElement.classList.add("highlighted");
    }

    return () => {
      const targetElement = document.getElementById(targetId);
      if (targetElement) {
        targetElement.classList.remove("highlighted");
      }
    };
  }, [targetId]);

  return null;
};

Example of highlight element :

Highlight Component

| Prop | Type | Description | Required | |-----------|----------|---------------------------------------------|----------| | targetId| string | The id of the element to highlight. | Yes |

TourGuideButtons Component

This component renders the navigation buttons for the tour, allowing users to move between steps, skip the tour, or finish it. It provides "Previous", "Skip", "Next", and "Finish" buttons based on the current step.

Props

| Prop | Type | Description | Required | |--------------|----------|-------------------------------------------------|----------| | currentStep| number | The current step index in the tour. | Yes | | totalSteps | number | The total number of steps in the tour. | Yes | | onPrevious | function| Function to handle moving to the previous step. | Yes | | onNext | function| Function to handle moving to the next step. | Yes | | onClose | function| Function to handle closing the tour. | Yes |

Example Usage

import React, { useState } from "react";
import { TourGuideButtons } from "react-spotlight-tour-cct";

const TourComponent = () => {
  const [currentStep, setCurrentStep] = useState(0);
  const totalSteps = 3;

  const handlePrevious = () => setCurrentStep((prev) => Math.max(prev - 1, 0));
  const handleNext = () => setCurrentStep((prev) => Math.min(prev + 1, totalSteps - 1));
  const handleClose = () => setCurrentStep(0); // or perform other closing actions

  return (
    <div>
      <h1>Tour Step {currentStep + 1}</h1>
      <TourGuideButtons
        currentStep={currentStep}
        totalSteps={totalSteps}
        onPrevious={handlePrevious}
        onNext={handleNext}
        onClose={handleClose}
      />
    </div>
  );
};

export default TourComponent;

Contributing

Feel free to submit issues or pull requests to improve the package. Contributions are always welcome!