@rocketsoftware/walktour

walktour

Guided tour/walkthrough component for react projects.

npm | GitHub

Options via Storybook

Installation

• npm i @rocketsoftware/walktour

or, if you prefer yarn:

• yarn add @rocketsoftware/walktour

How To Use

Import the Walktour component:

import { Walktour } from '@rocketsoftware/walktour'

And then include it somewhere in your render function:

<Walktour 
   steps={mySteps}
/>

Props

Attribute	Type	Description
steps	Array<Step>	All the Step objects defining stops along the tour.
isOpen	boolean	Determines whether the tour should be shown or not. If this is set, the tour will become controlled, and the user needs to manually handle closing the tour with customCloseFunc.
initialStepIndex	number	Start the tour on a particular step when opened. Default is 0.
zIndex	number	z-index value to give the tour components.
rootSelector	string	CSS selector string specifying the container element that the tour should be injected into. Only necessary if trying to constrain the scope of the tour and it's masking/scrolling to a particular element which is distinct from where the tour is instantiated.
identifier	string	An id string to be suffixed to the default Walktour IDs. Only necessary if multiple tours are running on the same page. More commonly, this means different tours in different components who are active on the same page.
setUpdateListener	(update: () => void) => void	Callback that is passed the tour's recalculate/update function. Can be used to set a window listener, or subscribe to some other event that needs to trigger a tour update.
removeUpdateListener	(update: () => void) => void	Callback that is passed the tour's recalculate/update function. This is the exact same function that is passed to setUpdateListener, so it can be used with the Window's add and removeEventListener functions.
disableListeners	boolean	Disables all intervals/listeners created by the tour. Should only use if performance on (really) slow machines is more important than watching for window resize/custom listener events. This will squash options like movingTarget, setUpdateListener, etc.
debug	boolean	If true, prints the logic used by Walktour (including props, state, calculated variables, etc.) to the console.
...	WalktourOptions	Any of the optional WalktourOptions attributes can be included as props.

Step Shape

Each step of the tour is defined by a Step object.

Attribute	Type	Description
selector	string	CSS selector string used to identify a particular element on the page.
description	string	Tooltip body text.
title	string	Tooltip heading text.
...	WalktourOptions	Any of the optional WalktourOptions attributes can be included as part of a Step object.

Options

These options can be provided at a tour level or applied to a single step along the tour.

Step-level options will take precedence over global options, so take care when using both in the same tour.

Attribute	Type	Description
disableMaskInteraction	boolean	Controls whether or not the user can use the mouse to interact with elements behind the mask. Default is false.
orientationPreferences	Array<CardinalOrientation>	A subset of all tooltip alignments from which to automatically select the tooltip position. Manual positioning can be achieved by providing an array with only a single orientation.
maskPadding	number	Distance between the targeted element and the mask (determines the size of the cutout).
tooltipSeparation	number	Distance between the targeted element and the tooltip.
transition	string	String representing the value of CSS transition shorthand property.
nextLabel	string	Text to be injected into the next button in the tooltip footer. Default is "next".
prevLabel	string	Text to be injected into the back button in the tooltip footer. Default is "prev".
closeLabel	string	Text to be injected into the close button in the tooltip footer. Default is "skip".
disableNext	boolean	Determines whether the next() operation is allowed.
disablePrev	boolean	Determines whether the prev() operation is allowed.
disableClose	boolean	Determines whether the close() operation is allowed.
customTooltipRenderer	(tourLogic: WalktourLogic) => JSX.Element	Callback function to generate an entirely custom tooltip component. Some exposed tour logic is provided as an argument to the callback to allow such a tooltip to fully control navigation, rendering, and other functions provided by the default tooltip. WARNING: Using position: absolute or fixed may break positioning of the tooltip and is not recommended.
customTitleRenderer	(title: string, tourLogic: WalktourLogic) => JSX.Element	Optional callback to generate custom title content. The function is passed the specified title string, as well as some exposed tour logic.
customDescriptionRenderer	(description: string, tourLogic: WalktourLogic) => JSX.Element	Optional callback to generate custom description content. The function is passed the specified description string, as well as some exposed tour logic.
customFooterRenderer	(tourLogic: WalktourLogic) => JSX.Element	Optional callback to generate custom footer content. The function is passed some exposed tour logic to allow for navigation control.
customNextFunc	(tourLogic: WalktourLogic, fromTarget: boolean) => void	Callback function to replace the default 'next' function. This is called each time that next() would normally be called. The 'fromTarget' flag is true iff this function gets called by clicking on the highlighted element.
customPrevFunc	(tourLogic: WalktourLogic) => void	Callback function to replace the default 'prev' function. This is called each time that prev() would normally be called.
customCloseFunc	(tourLogic: WalktourLogic) => void	Callback function to replace the default 'close' function. This is called each time that close() would normally be called.
disableAutoScroll	boolean	Disable automatically scrolling elements into view. Default is false.
getPositionFromCandidates	(candidates: OrientationCoords[]) => Coords	Optional callback to specify how the tooltip position is chosen. Only use if positioning is more complex than can be achieved with orientationPreferences; for instance, the tooltip position could be based on proximity to the cursor position or some other factor that's not known ahead of time.
movingTarget	boolean	If true, the tour will watch the target element for position changes. If the position is sufficiently different (as specified by renderTolerance) from its initial position or size, the tooltip and mask will adjust themselves accordingly. This can also be used if a particular target element is hidden or does not yet exist at the time the tour arrives to it.
renderTolerance	number	Distance, in pixels, for the target element to have moved/resized before triggering an update. Applies to the movingTarget option as well as the default window resize recalculation. Default is 2.
updateInterval	number	Duration, in milliseconds, between polling for changes to a target's positioning. For use with movingTarget option. Default is 500.
disableMask	boolean	Disable the overlay and cutout. Default is false.
disableSmoothScroll	boolean	Disable supporting browsers scrolling smoothly to offscreen elements. Default is false.
allowForeignTarget	boolean	Allows the tour to target elements outside of it's root container. The tour and its elements will still be bound to that container, so it's best used for elements that are immediately bordering the container, like a menu shell. Foreign targets cannot be highlighted.
nextOnTargetClick	boolean	Determines whether interacting with the target should advance the tour. Currently only supports clickable targets (buttons).
validateNextOnTargetClick	() => Promise<boolean>	If specified, the output of this function will determine whether or not the tour will actually advance after having clicked the target element. To be used in conjunction with nextOnTargetClick

WalktourLogic

The WalktourLogic object aims to provide custom renderers with as much functionality as possible by exposing basic functions and data that the tour uses to operate. All custom renderers are responsible for implementing the various WalktourOptions to their desired degree. For instance, a customFooterRenderer might choose to ignore the disableClose option, or to always display "back" instead of the specified prevLabel.

Attribute	Type	Description
goToStep	(stepNumber: number) => void	Tells the tour to jump to the specified step index.
next*	() => void	Advances the tour by a single step.
prev*	() => void	Returns the tour to the previous step.
close*	(reset: boolean) => void	Closes the tour. The optional reset argument controls whether or not the tour should be set back to its initial state, or remain on the current step.
stepContent**	Step	Step object associated with the current step index.
stepIndex	number	Current step index.
allSteps	Array<Step>	Collection of every Step in the tour.

*If any customFunc is specified, that custom function will replace the respective function in the WalktourLogic object, with the default logic passed as arguments to the custom functions. This means that a customNextFunc could look like this:

function myCustomNext(logic: WalktourLogic): void {
  loadNextStepPromise().then(val => {
    console.log(val);
    //advance tour on promise fulfillment
    logic.next();
  }, rej => {
    console.log(rej);
    //don't advance tour
  });
}

It's especially important to call close() if providing customCloseFunc, since there are cleanup events which are handled by the default close() call.

**All options available for a Step object will be provided in the WalktourLogic object, even if those options haven't been specified for a particular step. For instance, if the maskPadding option is passed to Walktour itself, but not to any individual step, each step's WalktourObject will still have the most relevant value for maskPadding as part of its stepContent.

Orientation And Alignment

The tooltip can be positioned at various locations around the targeted element. There are five simple positions:

Enum	String
East	"east"
South	"south"
West	"west"
North	"north"
Center*	"center"

and 8 more specific positions, which are just combinations of the simple ones:

Enum	String
EastNorth	"east-north"
EastSouth	"east-south"
SouthEast	"south-east"
SouthWest	"south-west"
WestSouth	"west-south"
WestNorth	"west-north"
NorthWest	"north-west"
NorthEast	"north-east"

The general format is [Position][Alignment], so a WestNorth-positioned tooltip is located on the left side of the target element, with their top edges aligned.

Each of these positions exists in the CardinalOrientation enum, and can be specified with the optional orientationPreferences like so:

Tour Level:

<Walktour 
  ...
  orientationPreferences={[CardinalOrientation.NORTH, CardinalOrientation.WESTNORTH]}
  ... 
/>

Step Level:

{... title: "Manual Positioning", orientationPreferences: [CardinalOrientation.EAST], ...}

An orientation can also be specified at either level with its corresponding string, like this:

{... orientationPreferences: ["south-east", "east-south", "south", "east"] ...}

*CENTER centers the tooltip relative to the target. Because it's placed on top of the target element (and thus obscures content, particularly with large tooltips and/or small targets), this position is usually ignored when choosing where to place the tooltip. If this behavior is desired, specify an orientationPreferences that only includes CardinalOrientation.CENTER and no other values, or implement a custom getPositionFromCandidates function.

If a content agnostic, centered tooltip is desired instead, specifiy that Step's selector property value to null or undefined, or simply omit the property altogether.

Examples

Minimal

import * as React from 'react';
import { Walktour } from 'walktour';

class App extends Component<> {
  render() {
    return (
      <div>
        <div id="step-one">My first step</div>
        <Walktour
          steps={[
            {selector: "#step-one", title: "First Steps", description: "One foot in front of the other"}
          ]}
        />
      </div>)
  }
}

Development / Demo

Clone the repo with:

git clone https://github.com/RocketSoftware/walktour.git

Navigate to the new directory and install the necessary development dependencies:

cd walktour && yarn install

Launch the development server:

yarn start

Once the server is running, it will specify a URL (typically http://localhost:1234). Navigate there in your browser to see your changes and interact with the demo app!