React Joyride
Setup
npm install --save react-joyride
Include Joyride
in the parent component.
var react = ;var Joyride = ; var App = React;
Don't forget to pass a ref
to the component.
Styles
If your are using SCSS (and you should):
Or include this directly in your html:
Getting Started
Add a custom function to include steps to your state in your own component
{ let joyride = thisjoyride; if !Array steps = steps; if !stepslength return false; this;} { thisjoyride;}
Add steps/tooltips after your components are mounted.
{ this; // or this.addTooltip({...}); thisjoyridestart; // or using props in your child components thisprops;}... { return <div> <Joyride ref="joyride" .../> <ChildComponent addSteps=thisaddSteps addTooltip=thisaddTooltip /> </div> ;}
Or you can start the tour after a criteria is met
{ if !prevStateready && thisstateready thisjoyridestart; }
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=thisstatesteps debug=true type="single" callback=thiscallback .../>
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.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
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 = thisjoyride; // 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 tooltiptext
: 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
andleft
. This defaults totop
.type
: The event type that trigger the tooltip:click
orhover
. Defaults toclick
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 to1500
$joyride-overlay-color
: Defaults torgba(#000, 0.5)
$joyride-beacon-color
: Defaults to$joyride-color
$joyride-beacon-size
: Defaults to36px
$joyride-hole-border-radius
: Defaults to4px
$joyride-hole-shadow
: Defaults to0 0 15px rgba(#000, 0.5)
Tooltip
$joyride-tooltip-arrow-size
: You must use even numbers to avoid half-pixel inconsistencies. Defaults to28px
$joyride-tooltip-bg-color
: Defaults to#fff
$joyride-tooltip-border-radius
: Defaults to4px
$joyride-tooltip-color
: The header and text color. Defaults to#555
$joyride-tooltip-font-size
: Defaults to16px
$joyride-tooltip-padding
: Defaults to20px
$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 to20px
$joyride-header-border-color
: Defaults to$joyride-color
$joyride-header-border-width
: Defaults to1px
$joyride-button-bg-color
: Defaults to$joyride-color
$joyride-button-color
: Defaults to#fff
$joyride-button-border-radius
: Defaults to4px
$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 totrue
;
License
Copyright © 2016 Gil Barbara - MIT License
Inspired by react-tour-guide and jquery joyride tour