techsemicolon / react-guided-tour

Customizable react package to walk user through guided tours

React Guided Tour

A customizable react package to walk user through guided tours!

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
2. Getting Started
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License

About The Project

You have a great react webapp(or any app in general), where you have worked very hard to build lot of functionalities, widgets, layouts etc for the customer. You spent months and years building it.

Now, lets go into customer's shoes!

We all experience at least one website where there are so many options, buttons widgets and you feel lost! The most common and expected reaction is closing the browser tab, because its not good to visit a website and not know where to start.

Thats a user dropout!

This is why it is important for an app to guide user through the initial steps. Or to put it in simple terms, interact with the customer to let them know that you are here to help, and take them through a Guided Tour of your web app.

This package is built of the same purpose where you can configure a guided tour for the end user, with lot of customizable options to let you set up a tour that is suitable for the app.

(back to top)

Getting Started

This is an example of how you can install, configure the react package up and running.

Installation

npm install --save react-guided-tour

(back to top)

Usage

Simple usage

Wrap the your app components under the GuidedTourProvider and pass the configurations like below :

import React from "react";
import { GuidedTourProvider } from "react-guided-tour";

const App = () => {
  const tourSteps = [
    {
      name: "welcome-user",
      anchor: "welcome",
      component: "Hello, welcome to the app",
    },
    {
      name: "see-off-user",
      anchor: "bye",
      component: "Thank you for browsing",
    },
  ];

  return (
    <GuidedTourProvider tourSteps={tourSteps}>
      <header guided-tour-anchor="welcome">Header</header>
      <div>Some Content</div>
      <footer guided-tour-anchor="bye">Footer</footer>
    </GuidedTourProvider>
  );
};

export default App;

Let's understand how it works :

• When you wrap your component tree inside the GuidedTourProvider, all the children of GuidedTourProvider get access to the utility functions which let you customize the user guided tour. For above example, we are just using default settings so we do not need utility hooks. Further examples will explore those in detail.
• You add an attribute guided-tour-anchor='...' to any element in any of your children component of GuidedTourProvider, which acts as an anchor for the tour popover.
• You create a configuration object, which is a simple json array of TourSteps, which contain name of the step, anchor which is the value of guided-tour-anchor attribute and component which is just a plain text in this example.

And thats it! This will take the user through the guided tour as shown in the screencast below.

Starting the tour manually

You might want to wait for certain user actions before you start the guided tour for the user. For example, waiting for user to click on an action button which says Start Tour or may be wait for certain time before starting the tour. In that case, the utility hooks are handy.

import React from "react";
import { GuidedTourProvider } from "react-guided-tour";

const App = () => {
  const { startTour } = useGuidedTour();

  const tourSteps = [
    {
      name: "welcome-user",
      anchor: "welcome",
      component: "Hello, welcome to the app",
    },
    {
      name: "see-off-user",
      anchor: "bye",
      component: "Thank you for browsing",
    },
  ];

  return (
    <GuidedTourProvider>
      <header guided-tour-anchor="welcome">Header</header>
      <div>Some Content</div>
      <footer guided-tour-anchor="bye">Footer</footer>
      // Manually triggering the tour start
      <button onClick={() => startTour(tourSteps)}>Start Tour</button>
    </GuidedTourProvider>
  );
};

export default App;

Starting the tour manually but skip few steps

You might want to start a tour but skip certain steps. This might be due to certain business logic or you user already went through the initial steps before. In that case, you can pass the second argument to the startTour function wuth the name of the tour step you want to start from.

import React from "react";
import { GuidedTourProvider } from "react-guided-tour";

const App = () => {
  const { startTour } = useGuidedTour();

  const tourSteps = [
    {
      name: "welcome-user",
      anchor: "welcome",
      component: "Hello, welcome to the app",
    },
    {
      name: "explain-user",
      anchor: "explain",
      component: "Explain how something works",
    },
    {
      name: "see-off-user",
      anchor: "bye",
      component: "Thank you for browsing",
    },
  ];

  return (
    <GuidedTourProvider>
      <header guided-tour-anchor="welcome">Header</header>
      <div>Some Content</div>
      <footer guided-tour-anchor="explain">Explain</footer>
      <footer guided-tour-anchor="bye">Footer</footer>
      // Manually triggering the tour start // Skipping initial tour steps and
      starting from step named `explain`
      <button onClick={() => startTour(tourSteps, explain)}>Start Tour</button>
    </GuidedTourProvider>
  );
};

export default App;

Using custom components

If you want to use custom components for the tour guide, you can pass any custom component in the component configuration of the tour step. These component should be a dumb/representational component.

import React from "react";
import { GuidedTourProvider } from "react-guided-tour";

const WelcomeTourComponent = () => <>Hello, welcome to the app</>;
const SeeOffTourComponent = () => <>Thank you for browsing</>;

const App = () => {
  const { startTour } = useGuidedTour();

  const tourSteps = [
    {
      name: "welcome-user",
      anchor: "welcome",
      component: WelcomeTourComponent,
    },
    {
      name: "see-off-user",
      anchor: "bye",
      component: SeeOffTourComponent,
    },
  ];

  return (
    <GuidedTourProvider>
      <header guided-tour-anchor="welcome">Header</header>
      <div>Some Content</div>
      <footer guided-tour-anchor="bye">Footer</footer>
      // Manually triggering the tour start
      <button onClick={() => startTour(tourSteps)}>Start Tour</button>
    </GuidedTourProvider>
  );
};

export default App;

One thing to observer here is that, the tour step custom components do not need to have any buttons to go to next or previous step by default. These will be added for you. If you want to have have custom button, you can do it in 2 ways mentioned below.

Using custom button for next and previous

In this configuration example, you tell the actionButtonComponent which button component you want to use for next and back actions.

import React from "react";
import { GuidedTourProvider } from "react-guided-tour";
import { MyCustomButton } from "my-custom-button";

const App = () => {
  const { startTour } = useGuidedTour();

  const tourSteps = [
    {
      name: "welcome-user",
      anchor: "welcome",
      component: "Hello, welcome to the app",
    },
    {
      name: "see-off-user",
      anchor: "bye",
      component: "Thank you for browsing",
    },
  ];

  return (
    // Custom action button
    <GuidedTourProvider actionButtonComponent={MyCustomButton}>
      <header guided-tour-anchor="welcome">Header</header>
      <div>Some Content</div>
      <footer guided-tour-anchor="bye">Footer</footer>
      // Manually triggering the tour start
      <button onClick={() => startTour(tourSteps)}>Start Tour</button>
    </GuidedTourProvider>
  );
};

export default App;

Disabling default next and back action buttons and handling that yourself in custom component

In this configuration example, you set handleActions to false for the tour steps, telling the package that the custom components will take care of it.

import React from "react";
import { GuidedTourProvider } from "react-guided-tour";

const App = () => {
  const { startTour } = useGuidedTour();

  const WelcomeTourComponent = () => {
    const { goBack, goNext } = useGuidedTour();

    return (
      <>
        Hello, welcome to the app
        <button onClick={() => goBack()}>Back</button>
        <button onClick={() => goNext()}>Next</button>
      </>
    );
  };

  const tourSteps = [
    {
      name: "welcome-user",
      anchor: "welcome",
      component: WelcomeTourComponent,
      handleActions: false, //disabling default action buttons, only works when you define custom component
    },
    {
      name: "see-off-user",
      anchor: "bye",
      component: "Thank you for browsing",
      handleActions: false, //disabling default action buttons, only works when you define custom component
    },
  ];

  return (
    <GuidedTourProvider>
      <header guided-tour-anchor="welcome">Header</header>
      <div>Some Content</div>
      <footer guided-tour-anchor="bye">Footer</footer>
      // Manually triggering the tour start
      <button onClick={() => startTour(tourSteps)}>Start Tour</button>
    </GuidedTourProvider>
  );
};

export default App;

All utility hooks

• startTour: (tour: TourStep[]) => void : Starts the tour with given tour step configurations
• goToTourStep: (name: string) => void : Skips to a specific tour step by tour step name
• skipTour: () => void : Skips entire guided tour
• goNext: () => void : Go to next step in the guided tour
• goBack: () => void : Go to previous step in the guided tour
• getCurrentTourStep: () => string : Get name of the current step

(back to top)

Roadmap

• Add a way to wait for an async action before going to next step
• Compatibiity with react Suspense / Lazy loaded components

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Contact

Mihir Bhende - Tech Blog

(back to top)