Create walkthroughs and guided tours for your apps
npm install react-joyride-with-nextReact Joyride
===
   !Join the chat at https://gitter.im/gilbarbara/react-joyride


``javascript`
npm install --save react-joyride
Include Joyride in the parent component.
`javascript
var react = require('react');
var Joyride = require('react-joyride');
var App = React.createClass({
render: function () {
return (
Don't forget to pass a ref to the component.$3
If your are using SCSS (and you should):`scss
@import '../path/to/node-modules/react-joyride/lib/styles/react-joyride'`Or include this directly in your html:
`html
`
Getting Started
Add a custom function to include steps to your state in your own component
`javascript
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.
`javascript
componentDidMount: function () {
this.addSteps({...}); // or this.addTooltip({...});
this.joyride.start();
// or using props in your child components
this.props.addSteps({...});
}
...
render: function () {
return (
);
}
`Or you can start the tour after a criteria is met
`javascript
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
falsekeyboardNavigation {bool}: Toggle keyboard navigation (esc, space bar, return). Defaults to
truelocale {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
falseresizeDebounceDelay {number}: The amount of delay for the
resizeDebounce callback. Defaults to 200scrollOffset {number}: The scrollTop offset used in
scrollToSteps. Defaults to 20scrollToSteps {bool}: Scroll the page to the next step if needed. Defaults to
truescrollToFirstStep {bool}: Scroll the page for the first step. Defaults to
falseshowBackButton {bool}: Display a back button. Defaults to
trueshowOverlay {bool}: Display an overlay with holes above your steps (for tours only). Defaults to
trueshowSkipButton {bool}: Display a link to skip the tour. Defaults to
falseshowStepsProgress {bool}: Display the tour progress in the next button e.g. 2/5 in
continuous tours. Defaults to falsesteps {array}: The tour's steps. Defaults to
[]tooltipOffset {number}: The tooltip offset from the target. Defaults to
30type {string}: The type of your presentation. It can be
continuous (played sequencially with the Next button) or single. Defaults to singledisableOverlay {bool}: Don't close the tooltip on clicking the overlay. Defaults to
falsecallback {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$3
~~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 undefinedExample:
`javascript
ref="joyride"
steps={this.state.steps}
debug={true}
type="single"
callback={this.callback}
...
/>
`API
$3
Add tooltips in your elements.
-
data {object} - A step object (check the syntax below)$3
Call this method to start the tour.
-
autorun {boolean} - Starts the tour with the first tooltip opened.$3
Call this method to programmatically advance to the next step of the tour.
$3
Call this method to stop/pause the tour. Call
this.joyride.start(true) to restart.$3
Call this method to reset the tour iteration back to 0
-
restart {boolean} - Starts the new tour right away$3
Retrieve the current progress of your tour. The object returned looks like this:`javascript
{
index: 2,
percentageComplete: 50,
step: {
title: "...",
text: "...",
selector: "...",
position: "...",
...
}
}}
`$3
Parse the incoming steps, check if it's already rendered and returns an array with valid items
-
steps {array|object}`javascript
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'
}]
`$3
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 clickExtra option for standalone tooltips
-
trigger: The DOM element that will trigger the tooltipYou 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:
`javascript
{
title: 'First Step',
text: 'Start using the joyride', // 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`;Copyright © 2016 Gil Barbara - MIT License
---
Inspired by react-tour-guide and jquery joyride tour