Interactive Tutorial

The interactive-tutorial plugin will allow for you to create an interactive tutorial on any page/app. It's easily configured and supports both highlighting areas and adding text in specific directions.

How to use

First, install the package:

npm install --save interactive-tutorial

Now, given the following html:

<div data-id="tutorial-navigation">...</div>
<div data-id="tutorial-signup">...</div>
<div data-id="tutorial-information">...</div>
<div data-id="tutorial-footer">...</div>

Call the package like this:

import InteractiveTutorial from "interactive-tutorial";

InteractiveTutorial({
  options: [
    {
      elementSelector: '[data-id="tutorial-navigation"]',
      text: "This is the main navigation",
      preferredPosition: "bottom",
    },
    {
      elementSelector: '[data-id="tutorial-signup"]',
      text: "This is a signup with a <strong>robot check</strong>",
      preferredPosition: "right",
    },
    {
      elementSelector: '[data-id="tutorial-information"]',
      text: "This is some informative information",
      preferredPosition: "left",
    },
    {
      elementSelector: '[data-id="tutorial-footer"]',
      text: "This is a boring footer",
      preferredPosition: "top",
    },
  ],
  padding: 10,
  textOffsetX: 20,
  textOffsetY: 20,
});

You can use a template as well, if you need some, or all, of your textbox to follow a common design pattern. You declare you template as a general argument (called template) and then use the property templateArgs for the options that wants to use the template. In the example below you can see that an argument is described as {arg} in the template, or {arg?} if you want it to be optional. The arguments can be called anything as long as they are matched by the templateArgs.

Example using a template:

import InteractiveTutorial from "interactive-tutorial";

InteractiveTutorial({
  options: [
    {
      elementSelector: '[data-id="tutorial-footer-link1"]',
      text: "This is a small link",
      preferredPosition: "top",
    },
    {
      elementSelector: '[data-id="tutorial-footer-link2"]',
      preferredPosition: "top",
      templateArgs: { text: "This one uses a template." },
    },
    {
      elementSelector: '[data-id="tutorial-footer-link3"]',
      preferredPosition: "top",
      templateArgs: {
        text: "This one <b>also</b> uses a template.",
        optional: "This one also uses the optional argument.",
      },
  ],
  template: `<p>This is the general template!<p><br /><p>{text}</p><br /><p>It is sometimes useful.</p><br /><p><em>{optional?}</em></p>`,
});

Available options are:

Option name	Type	Description
options	object	An array of options, each describing an individual step of the tutorial. See the type definition below.
option.elementSelector	string	Any valid selector for the element to highlight/focus on.
option.text	string | undefined	The text to show (optional).
option.preferredPosition	"top" | "right" | "bottom" | "left" | undefined	If you want to select where the text is going to show, select a preferred position.
option.padding	number | undefined	The padding for this particular segment.
option.textOffsetX	number | undefined	The specific X offset for this particular text segment
option.textOffsetY	number | undefined	The specific Y offset for this particular text segment
options.templateArgs	object | undefined	Arguments for the tmplate, if you are using it
padding	number | undefined	The general padding of all tutorial areas.
textOffsetX	number | undefined	The general X offset for all text baloons.
textOffsetY	number | undefined	The general Y offset for all text baloons.
template	string | undefined	A template that can be used for all, or some, textboxes.

And to style it using the available class selectors:

Selector	Description
.interactive-tutorial-overlay	The main overlay ontop of which the tutorial is placed.
.interactive-tutorial-element-overlay	The overlay ontop of the currently showing section.
.interactive-tutorial-cloaking-rectangle-top	The top cloaking rectangle.
.interactive-tutorial-cloaking-rectangle-right	The right cloaking rectangle.
.interactive-tutorial-cloaking-rectangle-bottom	The bottom cloaking rectangle.
.interactive-tutorial-cloaking-rectangle-left	The left cloaking rectangle.
.interactive-tutorial-text	The text element.
.interactive-tutorial-text-top	The text element whenever it is positioned at the top.
.interactive-tutorial-text-right	The text element whenever it is positioned at the right.
.interactive-tutorial-text-bottom	The text element whenever it is positioned at the bottom.
.interactive-tutorial-text-left	The text element whenever it is positioned at the left.
.interactive-tutorial-text-top-right	The text element whenever it is positioned above an element but starts from the right.
.interactive-tutorial-text-bottom-right	The text element whenever it is positioned below an element but starts from the right.

There is a stylesheet available (which is used in the above demo) which you can import from inside the npm package.

import "./node_modules/interactive-tutorial/build/styles.css";

Working with the code

If you want to contribute or just play around with the code, just download or fork the repository.

To build the project, simply run:

npm install
npm run watch
// or
npm run build

To run the demo project to test your changes you must install the dependencies within the package.

cd demo/
npm install
npm start