SpotlightJS is a JavaScript module that helps generate step-by-step instructions and demos in an easy way. It spotlights elements adding small commentary on them. See a demo working on CodePen.

It uses borders to create a spotlight area that will highlight a specific element, displaying commentary text, and animating from one step to another using CSS transitions. It is highly customizable, works on desktop and mobile, and users can opt to use the default controls or create their own using the plugin API.

Initially, it was a CSS-only animation for a Snake & Ladders (a.k.a. as Chutes & Ladders) game. Then it was ported into JavaScript and this module was created.

This is a simple 4-step way to start SpotlightJS:

1. Download an import the JS library and CSS file into your project

   <link rel="stylesheet" href="/css/spotlight.css" />
   <script src="/js/spotlight.js"></script>
   

2. Add data-sp-next data-attribute to the elements that you want to highlight as part of your instructions.

   There are more data-attributes that can be added, but only the data-sp-next is essential to create the list of steps for the instructions.

3. Initialize SpotlightJS with the selector of the initial element of the instructions:

   <script>
   let spotlight = new SpotlightJS({
     init: "#step1"
   });
   </script>
   

4. With JavaScript, trigger the beginning of the instructions/demo using the start method:

   spotlight.start();
   

For more examples on how to start, check the repository demos.

The structure of the steps list will be as follows:

[
  {
    selector: "selector-of-the-element-to-be-highglighted-(mandatory)",
    text: "text-to-be-displayed-(optional)",
    shape: "shape-of-the-element-(optional)"
  },
  ...
]

So, for example, the following ways of initializing SpolightJS would be equivalent:

Method 1:

<div id="step-1" data-sp-next="#step-2" data-sp-text="This is the first step.">Hello!</div>
<div id="step-2" data-sp-next="#step-3" data-sp-text="This is the last steop." data-sp-shape="round">Good Bye!</div>

<script>
let spotlight = new SpotlightJS({ init: "#step-1" });
</script>

Method 2:

<div id="step-1">Hello!</div>
<div id="step-2">Good Bye!</div>

<script>
let spotlight = new SpotlightJS({ 
                      steps:[
                              { selector: "#step-1", text: "This is the first step." },
                              { selector: "#step-2", text: "This is the last step.", shape: "round" }
                            ]
                    });
</script>

In order to customize the instructions, you could hide all the controls (next, previous, skip) and use your own using the methods from the provided API, or you could also hide the text associated to each step (via CSS) and design your own instruction text. For some examples of the possibilities, see the demos page.