@nlo/onboarding-tour

Onboarding tour

A vue plugin for a step by step interactive onboarding tour.

Installation

You can install the package through NPM.

npm install @nlo/onboarding-tour

Usage

Import and register the plugin:

import OnboardingTour from "@nlo/onboarding-tour";

Vue.use(OnboardingTour);

Include the tour component in the template of the page or view you want to use it. This must be in an overarching component which contains all the steps of that specific onboarding. Provide it with a unique name to distinguish it from other onboarding tours in your website.

<onboarding-tour name="myTour1" :steps="onboardingSteps"></onboarding-tour>

Provide an array of onboardingSteps as vue component data:

export default {
	data() {
		return {
			onboardingSteps: [
				{ description: "New feature 1" },
				{ description: "New feature 2" },
			],
		};
	},
};

In your template add data attributes for each step in the same order that you defined your onboardingSteps array:

Parameters:

• data-tour-action-data: Contains a string that is passed to the action that can be set in JS.
• data-tour-description-data: Contains a JSON string that is used as input for making the description of the step dynamic (using {{my-variable}} syntax)

<template>
	<div class="feature-1" data-tour-step="1"></div>
	<div
		class="feature-2"
		data-tour-step="2"
		data-tour-action-data="data that needs to be passed to the action of this step"
		data-tour-description-data='{"my-variable": 12}'
	></div>

	<onboarding-tour name="myTour1" :steps="onboardingSteps"></onboarding-tour>
</template>

Finally start the onboarding when you want to present it to the user, for example in the mounted hook:

mounted() {
  this.$onboarding.start('myTour1', { localStorageKey: 'myTour1' });
}

You can add some optional interface options

mounted() {
  this.$onboarding.start('myTour1', {
    localStorageKey: 'myTour1',
    interfaceOptions: {
      hideSteps: true, // default is false
      hideStop: true, // default is false
      stopText: 'Stop text', // default is 'Stoppen'
      endText: 'The end', // default is 'Ok, klaar!'
      nextText: 'Next' // default is 'Ok, ga verder'
    }
  });
}

A built in local storage mechanism is available if you pass a local storage key as part of the second options object argument. This allows you to easily show the tour to the user once.

Additional configuration

The step object in the steps prop array you provide to the plugin has a few additional options to allow for more useful interaction.

{
  // Description text for inside the tooltip for that step
  description: 'New feature 1',
  // Optional: Title for inside the tooltip fot that step, above the description
  title: 'Title',
  // Optional: See popper.js tooltip placement string options
  tooltipPlacement: 'bottom-start',
  // Optional: Execute code on the action hook to for example open a drawer for that specific feature highlight
  action: () => {
    this.openDrawer();
  },
  // Optional: Delay in milliseconds to for example wait for the action of the previous step to finish first
  delay: 300.
  // Optional: CSS selector to find the target element (overrides data-tour-step feature)
  target: '#feature1-complex-control'
}