react-joyride

What is react-joyride?

react-joyride is a React component that helps you create guided tours for your web applications. It allows you to highlight elements, provide step-by-step instructions, and enhance user onboarding experiences.

What are react-joyride's main functionalities?

Creating a Basic Tour

This code demonstrates how to create a basic tour with react-joyride. It defines a series of steps, each with a target element and content, and then renders the Joyride component with these steps.

import React from 'react';
import Joyride from 'react-joyride';

const App = () => {
  const steps = [
    {
      target: '.my-first-step',
      content: 'This is my first step!'
    },
    {
      target: '.my-second-step',
      content: 'This is my second step!'
    }
  ];

  return (
    <div>
      <Joyride steps={steps} />
      <div className="my-first-step">First Step</div>
      <div className="my-second-step">Second Step</div>
    </div>
  );
};

export default App;

Customizing Tour Appearance

This code shows how to customize the appearance of the tour. You can change the primary color, z-index, and other styles to match your application's design.

import React from 'react';
import Joyride, { STATUS } from 'react-joyride';

const App = () => {
  const steps = [
    {
      target: '.my-first-step',
      content: 'This is my first step!',
      styles: {
        options: {
          zIndex: 10000,
        }
      }
    }
  ];

  return (
    <div>
      <Joyride
        steps={steps}
        styles={{
          options: {
            primaryColor: '#e91e63',
            zIndex: 10000,
          }
        }}
      />
      <div className="my-first-step">First Step</div>
    </div>
  );
};

export default App;

Controlling Tour Programmatically

This code demonstrates how to control the tour programmatically. You can start the tour with a button click and handle the tour's status changes using a callback function.

import React, { useState } from 'react';
import Joyride, { STATUS } from 'react-joyride';

const App = () => {
  const [run, setRun] = useState(false);
  const steps = [
    {
      target: '.my-first-step',
      content: 'This is my first step!'
    }
  ];

  const handleJoyrideCallback = (data) => {
    const { status } = data;
    if ([STATUS.FINISHED, STATUS.SKIPPED].includes(status)) {
      setRun(false);
    }
  };

  return (
    <div>
      <button onClick={() => setRun(true)}>Start Tour</button>
      <Joyride
        steps={steps}
        run={run}
        callback={handleJoyrideCallback}
      />
      <div className="my-first-step">First Step</div>
    </div>
  );
};

export default App;

Other packages similar to react-joyride

reactour

reactour is another React library for creating guided tours. It offers a simple API and is highly customizable. Compared to react-joyride, reactour is more lightweight but may lack some advanced features.

shepherd.js

shepherd.js is a JavaScript library for creating guided tours that can be used with React. It provides a more flexible and powerful API compared to react-joyride, but it requires more setup and configuration.

intro.js

intro.js is a standalone JavaScript library for creating step-by-step guides and feature introductions. It can be integrated with React and offers a wide range of customization options. It is more feature-rich but also more complex to use compared to react-joyride.

README

React Joyride

View the demo here.

Install

npm install --save react-joyride

var react = require('react/addons');
var joyride = require('react-joyride').Mixin;

var App = React.createClass({
  mixins: [React.addons.PureRenderMixin, joyride],
  ...
});

This mixin changes state often so you should use React.addons.PureRenderMixin in your components as well.

Styles

If your are using SCSS:

@include 'react-joyride/lib/styles/react-joyride'

Or include this directly in your html:

<link rel="stylesheet" href="react-joyride/lib/styles/react-joyride.css" type="text/css">

Getting Started

Add steps to your tour after your component is mounted.

	componentDidMount: function () {
		this.joyrideAddSteps([{...}])]
	}

Start the tour with:

this.joyrideStart()

API

this.joyrideSetOptions(options)

Change the initial options during componentWillMount. All optional

• options {object} - One or more of the options below.

keyboardNavigation {bool}: Toggle keyboard navigation (esc, space bar, return). Defaults to true

locale {object}: The strings used in the tooltip. Defaults to { back: 'Back', close: 'Close', last: 'Last', next: 'Next', skip: 'Skip' }

scrollOffset {number}: The scrollTop offset used in scrollToSteps. Defaults to 20

scrollToSteps {bool}: Scroll the page to the next step if needed. Defaults to true

showBackButton {bool}: Display a back button. Defaults to true

showOverlay {bool}: Display an overlay with holes above your steps. Defaults to true

showSkipButton {bool}: Display a link to skip the tour. It will trigger the completeCallback if it was defined. Defaults to false

showStepsProgress {bool}: Display the tour progress in the next button e.g. 2/5 in guided tours. Defaults to false

tooltipOffset {number}: The tooltip offset from the target. Defaults to 30

type {string}: The type of your presentation. It can be guided (played sequencially with the Next button) or single. Defaults to guided

completeCallback {function}: It will be called after an user has completed all the steps or skipped the tour completely and passes the steps {array} and if the tour was skipped {boolean}. Defaults to undefined

stepCallback {function}: It will be called after each step and passes the completed step {object}. Defaults to undefined

Example:

componentWillMount: function () {
	this.joyrideSetOptions({
		locale: {
			back: 'Voltar',
			close: 'Fechar',
			last: 'Último',
			next: 'Próximo',
			skip: 'Pular'
		},
		showSkipButton: true,
		tooltipOffset: 10,
		...
		stepCallback: function(step) {
			console.log(step);
		},
		completeCallback: function(steps) {
			console.log(steps);
		}
	});
}

this.joyrideAddSteps(steps, [start])

Add steps to your tour. You can call this method multiple times even after the tour has started.

• steps {object|array} - Steps to add to the tour
• start {boolean} - Starts the tour right away (optional)

this.joyrideAddSteps([
	{
		title: "", //optional
		text: "...",
		selector: "...",
		position: "..."
	},
	...
]);

this.joyrideReplaceSteps(steps, [start])

Add steps to your tour. You can call this method multiple times even after the tour has started.

• steps {object|array} - Steps to replace
• restart {boolean} - Starts the new tour right away. Defaults to true

this.joyrideReplaceSteps([
	{
		title: "", //optional
		text: "...",
		selector: "...",
		position: "..."
	},
	...
], true);

this.joyrideStart(autorun)

Call this method to start the tour if it wasn't already started with this.joyrideAddSteps()

• autorun {boolean} - Starts the tour with the first tooltip opened.

this.joyrideGetProgress()

Retrieve the current progress of your tour. The object returned looks like this:

{
	index: 2,
	percentageComplete: 50,
	step: {
		title: "...",
		text: "...",
		selector: "...",
		position: "..."
	}
}}

Step Syntax

There are 4 usable options but you can pass extra parameters.

• title: The title of the tooltip (optional)
• text: The tooltip's body (required)
• selector: The target DOM selector of your step (required)
• position: Relative position of you beacon and tooltip. It can be one of these: right, left, top, top-left, top-right, bottom, bottom-left, bottom-right and center. This defaults to top.

Example:

{
    title: 'First Step',
    text: 'Start using the joyride',
    selector: '.first-step',
    position: 'bottom-left',
    ...
    name: 'my-first-step',
    parent: 'MyComponentName'
}

SCSS Options

Basic

• $joyride-color: The base color. Defaults to #f04
• $joyride-zindex: Defaults to 1500
• $joyride-overlay-color: Defaults to rgba(#000, 0.5)
• $joyride-beacon-color: Defaults to $joyride-color
• $joyride-beacon-size: Defaults to 36px
• $joyride-hole-border-radius: Defaults to 4px
• $joyride-hole-shadow: Defaults to 0 0 15px rgba(#000, 0.5)

Tooltip

• $joyride-tooltip-arrow-size: You must use even numbers to avoid half-pixel inconsistencies. Defaults to 28px
• $joyride-tooltip-bg-color: Defaults to #fff
• $joyride-tooltip-border-radius: Defaults to 8px
• $joyride-tooltip-color: The header and text color. Defaults to #555
• $joyride-tooltip-font-size: Defaults to 16px
• $joyride-tooltip-padding: Defaults to 20px
• $joyride-tooltip-shadow: Defaults to drop-shadow(2px 4px 4px rgba(#000, 0.5))
• $joyride-tooltip-width: Sass list of Mobile / Tablet / Desktop sizes. Defaults to (290px, 360px, 450px)
• $joyride-header-color: Defaults to $joyride-tooltip-header-color
• $joyride-header-font-size: Defaults to 20px
• $joyride-header-border-color: Defaults to $joyride-color
• $joyride-header-border-width: Defaults to 1px
• $joyride-button-bg-color: Defaults to $joyride-color
• $joyride-button-color: Defaults to #fff
• $joyride-button-border-radius: Defaults to 4px
• $joyride-back-button-color: Defaults to $joyride-color
• $joyride-skip-button-color: Defaults to #ccc

License

Copyright © 2015 Gil Barbara - MIT License

---

Inspired by react-tour-guide and jquery joyride tour