walktour v5.2.0

walktour

Guided tour/walkthrough component for react projects.

npm | GitHub

Try the demo!

Options via Storybook

Installation

• npm i walktour

or, if you prefer yarn:

• yarn add walktour

How To Use

Import the Walktour component:

import { Walktour } from 'walktour'

And then include it somewhere in your render function:

<Walktour 
   steps={mySteps}
/>

Props

Step Shape

Each step of the tour is defined by 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.

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.

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

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

The general format is Position, 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/alfrdmalr/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!

Publishing

Test

npm pack will generate a tarball without actually publishing; this can then be installed via npm install [path-to-tarball] for testing that the package works as intended.

Bump Version

npm version [major | minor | patch]

Publish