honeycombio/react-joyride

Name: react-joyride

Owner: Honeycomb

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

Forked from: gilbarbara/react-joyride

Created: 2016-11-23 23:15:07.0

Updated: 2016-11-23 23:15:08.0

Pushed: 2017-12-23 00:59:22.0

Homepage: http://gilbarbara.github.io/react-joyride/

Size: 2618

Language: JavaScript

GitHub Committers

UserMost Recent Commit# Commits

Other Committers

UserEmailMost Recent Commit# Commits

README

React Joyride

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

View the demo here. [source]

Support via Gratipay

Setup
install --save react-joyride

Include Joyride in the parent component.

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

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):

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

Or include this directly in your html:

k 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

teps: 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;
});


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

Add steps/tooltips after your components are mounted.

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


// or using props in your child components
this.props.addSteps({...});

  
er: 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

onentDidUpdate (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:

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:

ride
ref="joyride"
steps={this.state.steps}
debug={true}
type="single"
callback={this.callback}
...
API
this.joyride.addTooltip(data)

Add tooltips in your elements.

this.joyride.start(autorun)

Call this method to start the tour.

this.joyride.next()

Call this method to programmatically advance to the next step of the tour.

this.joyride.stop()

Call this method to stop/pause the tour. Call this.joyride.start(true) to restart.

this.joyride.reset(restart)

Call this method to reset the tour iteration back to 0

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 = this.joyride.parseSteps({
title: 'Title',
text: 'description',
selector: 'my-super-class',
position: 'top'


teps

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.

Extra option for standalone tooltips

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 Tooltip
License

Copyright © 2016 Gil Barbara - MIT License

Inspired by react-tour-guide and jquery joyride tour

This work is supported by the National Institutes of Health's National Center for Advancing Translational Sciences, Grant Number U24TR002306. This work is solely the responsibility of the creators and does not necessarily represent the official views of the National Institutes of Health.