@rocketsoftware/walktour
TypeScript icon, indicating that this package has built-in type declarations

4.4.4 • Public • Published

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!

Readme

Keywords

none

Package Sidebar

Install

npm i @rocketsoftware/walktour

Weekly Downloads

14

Version

4.4.4

License

MIT

Unpacked Size

148 kB

Total Files

17

Last publish

Collaborators

  • prit-rocket
  • pmaniseth
  • mbhide.rocket
  • hshockley