A customizable react package to walk user through guided tours!
View Demo
·
Report Bug
·
Request Feature
Table of Contents
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.
This is an example of how you can install, configure the react package up and running.
npm install --save react-guided-tour
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 ofGuidedTourProvider
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 ofGuidedTourProvider
, which acts as an anchor for the tour popover. - You create a configuration object, which is a simple json array of
TourSteps
, which containname
of the step,anchor
which is the value ofguided-tour-anchor
attribute andcomponent
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.
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;
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;
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.
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;
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;
startTour: (tour: TourStep[]) => void
: Starts the tour with given tour step configurationsgoToTourStep: (name: string) => void
: Skips to a specific tour step by tour step nameskipTour: () => void
: Skips entire guided tourgoNext: () => void
: Go to next step in the guided tourgoBack: () => void
: Go to previous step in the guided tourgetCurrentTourStep: () => string
: Get name of the current step
- 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).
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!
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature
) - Commit your Changes (
git commit -m 'Add some AmazingFeature'
) - Push to the Branch (
git push origin feature/AmazingFeature
) - Open a Pull Request
Distributed under the MIT License. See LICENSE.txt
for more information.
Mihir Bhende - Tech Blog