Intro.js: a data-attribute tour library with an AGPLv3 boundary

The onboarding problem Intro.js targets

Most onboarding libraries want to own your component tree. You wrap the page in a provider, mark elements with a component, and the tour state lives inside the framework. Intro.js takes the opposite position. It is a DOM library: you annotate existing HTML with attributes, include a stylesheet, and call one function. The README describes it as a "User Onboarding and Product Walkthrough Library", and the repository topics list cdn, guide, html, introjs, javascript, minify, tour and ux. That set of topics is a fair summary of the scope. There is no server component, no analytics layer, no backend.

The audience follows from that. Teams with server-rendered pages, static sites, or a mix of frameworks on one codebase can add a tour without rewriting anything. If your marketing pages are plain HTML and your app is a single-page framework, the same attribute approach works on both. The cost is that anything dynamic needs care: an element that does not exist when the tour starts cannot be highlighted, and the repository ships an example directory named example/dynamic-start and another named example/withoutElement, which tells you those cases come up often enough to deserve their own samples.

How Intro.js walks a page: attributes, steps and hints

The mechanism is a scan of the document for annotated elements. The README's three-step usage is the whole model: include intro.js and introjs.css, add data-intro and data-step to your elements, then call introJs().start(). data-step carries the order, data-intro carries the tooltip text. A third attribute, data-hint, produces hints rather than a linear tour.

Because ordering comes from an attribute value rather than from source order, you can renumber steps without moving markup, and you can scope a tour to a subset of the page. The README gives this example: introJs(".introduction-farm").start() runs the introduction only for elements with class='introduction-farm'. That selector argument is the main lever for building more than one tour on the same page.

The repository layout shows where the rest lives. src/ holds the implementation, themes/ holds alternate styling, docs/ holds documentation sources, and example/ holds the runnable samples. The example directory names double as a feature list: RTL, auto-position, bootstrap, callbacks, custom-class, disable-interaction, dynamic-start, groups, hello-world, hint, html-tooltip, multi-page, programmatic and svg. If you want to know whether a behaviour is supported, that list is a faster check than reading the README, which defers to introjs.com/docs for anything beyond the basics.

Installing Intro.js and running a first tour

The README lists four ways to obtain a copy: clone the GitHub repository, yarn add intro.js, npm install intro.js --save, or download from CDN through jsDelivr or cdnjs. The npm route is the one most projects will take, and the package ships intro.js as the main entry, intro.module.js as the module entry, and src/index.d.ts for types, so TypeScript consumers get declarations without a separate @types package.

Start with the install:

npm install intro.js --save

Next, include the script and the stylesheet in your page. The minified files are the production choice, and introjs-rtl.min.css is the variant for right-to-left languages. Then annotate the elements you want to point at. The README's own example is a single anchor:

<a href='http://google.com/' data-intro='Hello step one!'></a>

Finally, start the tour from JavaScript. With no argument, every annotated element on the page is included:

introJs().start();

What you should see is a sequence of tooltips attached to the annotated elements, in the order given by data-step. If nothing appears, the two usual causes are a missing stylesheet or attributes on elements that are not in the DOM at the moment start() runs. The README does not document a rollback or teardown API, so plan for the tour as a one-way interaction unless you read further into the docs site.

The licence split is the real adoption decision

Intro.js is dual-licensed, and the README states both halves plainly. The open-source license is GNU AGPLv3. The commercial license is described as the appropriate option "If you want to use Intro.js for a commercial application, theme or plugin", and the README adds that with this option your source code is kept proprietary. Purchase happens through introjs.com.

This is not a footnote. AGPLv3 carries network-copyleft obligations that many proprietary products cannot accept, which is why the project sells the alternative rather than offering a permissive fallback. The repository's license field is reported as NOASSERTION, so automated licence scanners may not classify it cleanly; read license.md in the repository and the licence section of the README rather than trusting a tool's summary. Nothing here is legal advice, and the practical question is simple: does your distribution model fit AGPLv3, or does it require the paid licence? Answer that before you write the first data-intro attribute, because retrofitting a tour library out of a shipped product is more work than choosing a different one up front.

Where Intro.js is the wrong tool

The attribute model is also its main limitation. A tour is defined in markup, so it does not participate in your framework's rendering, state or lifecycle. In a React, Vue or Angular application where the elements you want to highlight are conditionally rendered, you end up coordinating two systems: the framework decides what exists, Intro.js decides what is highlighted, and nothing in the library mediates between them. The example/dynamic-start and example/withoutElement samples exist precisely because that coordination is not free.

The README also does not document a teardown or rollback path, nor does it describe persistence of tour completion. If you need a tour that resumes across sessions, or one that is replayed on demand with stored progress, that logic is yours to build. And the documentation is thin by design: the README defers to introjs.com/docs for attributes, wrappers and everything else, so the repository alone is not a complete reference. Teams that want an API surface documented in the repository, rather than on a separate site, will find that split annoying.

Alternatives and how their approach differs

The README itself links a usage-trends comparison against @reactour/tour, driver.js and vue-tour, which is a useful map of the field. The difference is architectural rather than cosmetic.

@reactour/tour and vue-tour are framework components. You mount a provider, and the tour becomes part of the component tree, which means tour state, conditional rendering and lifecycle hooks all live in the same place as the rest of your UI. That is a real advantage in a framework application and a real disadvantage if your pages are server-rendered or if you run more than one framework.

driver.js is the closer comparison in spirit: a standalone DOM library in the same family as Intro.js, which is why the two are frequently weighed against each other. Choosing between them is mostly about licensing posture and API preference rather than capability, since both avoid the framework-provider model. If AGPLv3 is the blocker for Intro.js, the permissive-licence options in that comparison list are where to look next.

There is no wrapper for every framework in the core repository. The README says Intro.js "has many wrappers for different purposes" and points to the documentation site for the list, so confirm the wrapper you need exists and is current before assuming a first-class integration.

Maintenance, build and upgrade cost

The repository is not archived, and the last push was on 2026-09-18, three days before this writing, so it is under current development. Releases are frequent enough to matter: v8.5.0 on 2026-07-21 and v8.4.0 on 2026-07-20, a day apart, with v8.3.2 before them on 2025-07-13. A one-day gap between minor releases suggests fixes land quickly, and also that pinning a version is wise if you ship on a schedule.

Building from source is documented and short. The README says to install nodejs and npm, run npm install, then npm run build to minify all static resources. The package also exposes a test script that runs prettier, Jest and Cypress in parallel, and the Cypress jobs run through Docker images pinned to specific browser versions, which is a heavier setup than a typical library and worth knowing if you intend to contribute rather than consume.

The upgrade cost is mostly the markup contract. Your data-intro and data-step attributes are the interface, and major versions are the point where that interface can move. The README does not publish a migration guide, so read the release notes for each major before bumping. On licence: dual licensing means a version upgrade does not change your obligations, but a change in how you distribute the product can.

Editorial conclusion

Adopt Intro.js when your product can live with AGPLv3 or you are prepared to buy the commercial license, and when tours are defined on existing DOM elements rather than inside a framework's component tree. Do not adopt it if you need a permissive license for a closed-source product and will not pay, or if you want tour state to live in React, Vue or Angular state management. Before committing, open the license section of the README, confirm which of the two licenses applies to your distribution, and check that the attributes you plan to use are listed on introjs.com/docs/intro/attributes, since the README points there rather than enumerating them.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. usablica/intro.js on GitHub