TourGuide React Component

TourGuide is a customizable and interactive step-by-step guide for your web application. It allows developers to create guided tours for users, highlighting specific elements on the page, displaying contextual information, and providing voice assistance.

Features

• Step-by-Step Guide: Create a sequence of steps to guide users through your application.
• Customizable Placement: Position the popover on top, bottom, left, or right of the target element.
• Voice Assistance: Option to start and stop a voice agent that reads out the content of each step.
• Highlighting: Automatically highlights the target element for better user focus.
• Dynamic Updates: Adjusts the popover position and content dynamically as the user navigates through the steps.
• Flexible Controls: Provides controls for navigating between steps, closing the tour, and toggling voice narration.
• Theme Customization: Adjust the appearance of the popover and buttons using the theme prop.
• Tour Start: Custom button used by the developer to start tour.

Installation

Install the package using npm:

npm install react-tour-guide-cct

Usage

Basic Setup

1. Import the TourGuide component into your project:

import "react-tour-guide-cct/dist/react-tour-guide-cct.css";
import { TourGuide } from "react-tour-guide-cct";

2. Define the steps for your tour:

const steps = [
  {
    target: "#element1",
    content: "This is the first step of the tour.",
  },
  {
    target: "#element2",
    content: "This is the second step of the tour.",
  },
  {
    target: "#element3",
    content: (
      <div>
        <h1>Demo</h1>
        <img src="demo.jpg" alt="demo" />
      </div>
    ),
  },
];

3. Use the TourGuide component in your application:

<TourGuide
  steps={steps}
  placement="bottom"
  onComplete={() => alert("Tour Completed")} //define your own function and use it here
  onStepChange={() => alert("Please carry on...")} //define your own function and use it here
  showCloseButton={true}
  highlightClass="tour-highlight"
  theme={{
    popoverBackgroundColor: "#fff",
    popoverTextColor: "#000",
    popoverBorderRadius: "20px",
    buttonBackgroundColor: "blue",
    buttonTextColor: "#fff",
    animation: "slide-in",
  }}
  startButton={<button className="start-tour-button">Start Tour</button>}
/>

Props

TourGuide Props

| Prop | Type | Default | Description | | ----------------- | -------------- | ---------------- | -------------------------------------------------------------------- | | steps | Array | [] | Array of steps for the tour, each containing target and content. | | placement | string | bottom | Placement of the popover (top, bottom, left, right). | | onComplete | Function | () => {} | Callback function triggered when the tour is completed. | | onStepChange | Function | () => {} | Callback function triggered when the step changes. | | showCloseButton | boolean | true | Determines whether to show the close button on the popover. | | highlightClass | string | tour-highlight | Custom CSS class for highlighting the target element. | | theme | object | {} | CSS properties to add the theme to a popover as per developer. | | startButton | ReactElement | React | Custom button used by the developer to start tour. |

Popover Props

| Prop | Type | Description | | ------------------ | ------------- | ------------------------------------------------------------------ | | content | string, JSX | Content to display inside the popover. | | position | object | Position of the popover (top and left coordinates). | | onClose | Function | Callback function triggered when the popover is closed. | | onNext | Function | Callback function triggered when the "Next" button is clicked. | | onPrev | Function | Callback function triggered when the "Previous" button is clicked. | | isFirst | boolean | Determines if the current step is the first step. | | isLast | boolean | Determines if the current step is the last step. | | stepInfo | string | Displays the current step information (e.g., "Step 1 of 3"). | | showCloseButton | boolean | Determines whether to show the close button on the popover. | | highlightClass | string | Custom CSS class for highlighting the target element. | | theme | object | CSS properties to add the theme to a popover as per developer. | | voiceAgent | boolean | Determines if the voice agent is active. | | toggleVoiceAgent | Function | Function to toggle the voice agent on or off. |

Example

Complete Implementation

import React from "react";
import TourGuide from "react-tour-guide-cct";

const App = () => {
  const steps = [
    {
      target: "#step1",
      content: "This is step 1 of the tour.",
    },
    {
      target: "#step2",
      content: "This is step 2 of the tour.",
    },
    {
      target: "#step3",
      content: "This is the final step of the tour.",
    },
  ];

  return (
    <div>
      <h1 id="step1">Welcome to the Tour!</h1>
      <p id="step2">This is the second step.</p>
      <button id="step3">Finish the tour here.</button>

      <TourGuide
        steps={steps}
        placement="bottom"
        onComplete={() => alert("Tour completed!")}
        onStepChange={() => console.log("Step changed")}
        showCloseButton={true}
        highlightClass="tour-highlight"
        startButton={<button className="start-tour-button">Start Tour</button>}
        theme={{
          popoverBackgroundColor: "#fff",
          popoverTextColor: "#000",
          popoverBorderRadius: "20px",
          buttonBackgroundColor: "blue",
          buttonTextColor: "#fff",
          animation: "slide-in",
        }}
      />
    </div>
  );
};

export default App;

License

This project is licensed under the MIT License.

Author

[Rehan Shah]