react-spotlight-tour-cct

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!