react-joyride 0,2,2 editorconfig eslint sass gulp npm

Create walkthroughs and guided tours for your ReactJS apps. Now with standalone tooltips!

2 years after MIT

React Joyride

Join the chat at https://gitter.im/gilbarbara/react-joyride

View the demo here. [source]

Support via Gratipay

Setup

npm install --save react-joyride

Include Joyride in the parent component.

var react = require('react');
var Joyride = require('react-joyride');

var App = React.createClass({
    render: function () {
        return (
            <div className="app">
                <Joyride ref={c => (this.joyride = c)} steps={this.state.steps} debug={true} ... />
                <YourComponents .../>
            </div>
        );
    }
  ...
});

Don't forget to pass a ref to the component.

Styles

If your are using SCSS (and you should):

@import '../path/to/node-modules/react-joyride/lib/styles/react-joyride'

Or include this directly in your html:

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

Getting Started

Add a custom function to include steps to your state in your own component

addSteps: function (steps) {
    let joyride = this.joyride;

    if (!Array.isArray(steps)) {
        steps = [steps];
    }

    if (!steps.length) {
        return false;
    }

    this.setState(function(currentState) {
        currentState.steps = currentState.steps.concat(joyride.parseSteps(steps));
        return currentState;
    });
}

addTooltip(data) {
    this.joyride.addTooltip(data);
}

Add steps/tooltips after your components are mounted.

componentDidMount: function () {
    this.addSteps({...}); // or this.addTooltip({...});
    this.joyride.start();

    // or using props in your child components
    this.props.addSteps({...});
}
...   
render: function () {
    return (
      <div>
          <Joyride ref="joyride" .../>
          <ChildComponent addSteps={this.addSteps} addTooltip={this.addTooltip} />
        </div>
    );
}

Or you can start the tour after a criteria is met

componentDidUpdate (prevProps, prevState) {
    if (!prevState.ready && this.state.ready) {
        this.joyride.start();
    }
},

Please refer to the source code of the demo if you need a practical example.

Options

You can change the initial options passing props to the component. All optional.

debug {bool}: Console.log Joyride's inner actions. Defaults to false

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' }

resizeDebounce {bool}: Delay the reposition of the current step while the window is being resized. Defaults to false

resizeDebounceDelay {number}: The amount of delay for the resizeDebounce callback. Defaults to 200

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

scrollToFirstStep {bool}: Scroll the page for the first step. Defaults to false

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

showOverlay {bool}: Display an overlay with holes above your steps (for tours only). Defaults to true

showSkipButton {bool}: Display a link to skip the tour. Defaults to false

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

steps {array}: The tour's steps. Defaults to []

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

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

disableOverlay {bool}: Don't close the tooltip on clicking the overlay. Defaults to false

callback {function}: It will be called after:

  • clicking the beacon { type: 'step:before', step: {...} }
  • closing a step { type: 'step:after', step: {...} }
  • clicking on the overlay (if not disabled) { type: 'overlay', step: {...} }
  • when the tour ends. { type: 'finished', steps: [{...}], skipped: boolean }

Defaults to undefined

Deprecated

completeCallback {function}: It will be called after an user has completed all the steps or skipped the tour and passes two parameters, 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:

<Joyride
    ref="joyride"
    steps={this.state.steps}
    debug={true}
    type="single"
    callback={this.callback}
    ...
/>

API

this.joyride.addTooltip(data)

Add tooltips in your elements.

  • data {object} - A step object (check the syntax below)

this.joyride.start(autorun)

Call this method to start the tour.

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

this.joyride.stop()

Call this method to stop/pause the tour.

this.joyride.reset(restart)

Call this method to reset the tour iteration back to 0

  • restart {boolean} - Starts the new tour right away

this.joyride.getProgress()

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

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

this.joyride.parseSteps(steps)

Parse the incoming steps, check if it's already rendered and returns an array with valid items

  • steps {array|object}
var steps = this.joyride.parseSteps({
    title: 'Title',
    text: 'description',
    selector: 'my-super-class',
    position: 'top'
});

// steps
[{
    title: 'Title',
    text: 'description',
    selector: '#super-panel',
    position: 'top'
}]

Only start the tour after all target elements (or at least the first step) are rendered in the page.

Tooltip / Step Syntax

There are a few usable options but you can pass custom parameters.

  • title: The title of the tooltip
  • text: The tooltip's body text (required)
  • selector: The target DOM selector of your feature (required)
  • position: Relative position of you beacon and tooltip. It can be one of these:top, top-left, top-right, bottom, bottom-left, bottom-right, right and left. This defaults to top.
  • type: The event type that trigger the tooltip: click or hover. Defaults to click

Extra option for standalone tooltips

  • trigger: The DOM element that will trigger the tooltip

You can style tooltips independently with these options: backgroundColor, borderRadius, color, mainColor, textAlign and width.

Also you can style button, skip, back, close and hole individually using standard style options. And beacon offset, inner and outer colors.

Example:

{
    title: 'First Step',
    text: 'Start using the <strong>joyride</strong>', // supports html tags
    selector: '.first-step',
    position: 'bottom-left',
    type: 'hover',
    style: {
        backgroundColor: 'rgba(0, 0, 0, 0.8)',
        borderRadius: '0',
        color: '#fff',
        mainColor: '#ff4456',
        textAlign: 'center',
        width: '29rem',
        beacon: {
            offsetX: 10,
            offsetY: 10,
            inner: '#000',
            outer: '#000'
        },
        button: {
            display: 'none'
            // or any style attribute
        },
        skip: {
            color: '#f04'
        },
        hole: {
            backgroundColor: 'RGBA(201, 23, 33, 0.2)',
        }
        ...
    },
    // custom params...
    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 4px
  • $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: Sass list for drop-shadow. Defaults to (x: 1px, y: 2px, blur: 3px, color: rgba(#000, 0.3))
  • $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
  • $joyride-close: Sass list for the close button: Defaults to (color: rgba($joyride-tooltip-color, 0.5), size: 30px, top: 10px, right: 10px)
  • $joyride-close-visible: Default to true;

License

Copyright © 2016 Gil Barbara - MIT License


Inspired by react-tour-guide and jquery joyride tour

Related Repositories

awesome-react

awesome-react

A collection of awesome things regarding React ecosystem. ...

awesome-react-components

awesome-react-components

Catalog of React Components & Libraries ...

Oi

Oi

A WYSIWYG Editor to create slides in impress.js. ...

awesome-react-me

awesome-react-me

A collection of awesome things regarding React ecosystem for me. ...

vcash-electron

vcash-electron

Electron UI for Vcash, a decentralized currency for the internet. ...


Top Contributors

gilbarbara jmrog erikthedeveloper evansoderberg dkingman ckknight megapctr littlebigbot josemarluedke Keats

Dependencies

package version
nested-property ^0.0.7
react-autobind ^1.0
scroll ^2.0
dev autoprefixer ^6.7
babel-core ^6.23
babel-eslint ^7.1
babel-jest ^19.0
babel-loader ^6.3
babel-plugin-istanbul ^4.0
babel-plugin-transform-flow-strip-types ^6.22
babel-plugin-transform-react-remove-prop-types ^0.3.2
babel-plugin-transform-runtime ^6.23
babel-preset-latest ^6.22
babel-preset-react ^6.23
babel-preset-stage-1 ^6.22
bootstrap ^4.0.0-alpha
browser-sync ^2.18
browser-sync-webpack-plugin ^1.1
chalk ^1.1.3
clean-webpack-plugin ^0.1
copy-webpack-plugin ^4.0
css-loader ^0.26
date-fns ^1.27
enzyme ^2.7
eslint ^3.16
eslint-config-airbnb ^14.1
eslint-import-resolver-webpack ^0.8
eslint-loader ^1.6
eslint-plugin-babel ^4.0
eslint-plugin-flowtype ^2.30
eslint-plugin-import ^2.2
eslint-plugin-jsx-a11y ^4.0
eslint-plugin-react ^6.10
extract-text-webpack-plugin ^2.0.0-beta
flow-bin ^0.40
html-webpack-plugin ^2.28
husky ^0.13
image-webpack-loader ^3.2
jest-cli ^19.0
jsdom ^9.11
nightwatch ^0.9
node-sass ^4.5
postcss-loader ^1.3
react ^15.4
react-addons-test-utils ^15.4
react-dom ^15.4
react-hot-loader ^3.0.0-beta
sass-loader ^6.0
source-map-support ^0.4
style-loader ^0.13
stylelint ^7.9
stylelint-config-standard ^16.0
stylelint-declaration-strict-value ^1.0
stylelint-order ^0.3
stylelint-scss ^1.4
webpack ^2.2.1
webpack-dev-server ^2.4.1
webpack-merge ^3.0
peer react ^0.14.0 || ^15.0.0
react-dom ^0.14.0 || ^15.0.0

Releases

-   1.5.0 zip tar
-   1.4.8 zip tar
-   1.4.7 zip tar
-   1.4.6 zip tar
-   1.4.5 zip tar
-   1.4.4 zip tar
-   1.4.2 zip tar
-   1.4.1 zip tar
-   1.4.0 zip tar
-   1.3.6 zip tar
-   1.3.5 zip tar
-   1.3.4 zip tar
-   1.3.3 zip tar
-   1.3.2 zip tar
-   1.3.1 zip tar
-   1.3.0 zip tar
-   1.2.0 zip tar
-   1.1.1 zip tar
-   1.1.0 zip tar
-   1.0.5 zip tar
-   1.0.4 zip tar
-   1.0.3 zip tar
-   1.0.2 zip tar
-   1.0.1 zip tar
-   1.0.0 zip tar
-   0.7.6 zip tar
-   0.7.5 zip tar
-   0.7.4 zip tar
-   0.7.3 zip tar
-   0.7.2 zip tar