guide

npm install @apollovisionlabs/guide-core @apollovisionlabs/guide-mui

guide builds the way an application greets a new user: the guided tours that show them around, and the first steps checklist that outlives the first session. A checklist item can launch the tour that teaches it, and finishing that tour ticks the item. @apollovisionlabs/guide-core holds the logic and depends only on React. @apollovisionlabs/guide-mui renders it with Material UI. Both packages are MIT; the published versions live on the package page, which does not go stale.

What sets it apart

A step targets a logical key carried by a data-guide attribute rather than a CSS selector, so a tour does not break when markup changes. If a target is not on screen yet, the library waits for it, then follows a policy of skip, wait or error.

A tour can cross several pages, calling a navigation function the application supplies, so the library depends on no router. The highlight is one SVG overlay, measured before the browser paints, so it never lags a step change.

Accessibility lives in the logic layer rather than the rendering one: a focus trap, a screen reader announcement on each step, and respect for the reduced motion preference. A step marked interactive is deliberately not modal, so a user told to click something can actually reach it with the keyboard.

Why we wrote it instead of taking one off the shelf

The two most polished existing libraries are under licences incompatible with a closed product, and no maintained tour library renders natively with Material UI.

An example

import { GuideProvider, type Tour } from '@apollovisionlabs/guide-core';
import { GuideTour } from '@apollovisionlabs/guide-mui';

const tour: Tour = {
  id: 'welcome',
  steps: [
    {
      target: 'sidebar.projects',
      title: 'Your projects',
      body: 'Everything you create is grouped under a project.',
    },
  ],
};

export function App() {
  return (
    <GuideProvider tours={[tour]}>
      <nav data-guide="sidebar.projects">Projects</nav>
      <GuideTour />
    </GuideProvider>
  );
}

How it is verified

Both packages are covered by unit tests and by end to end scenarios played in a real browser, all of them required before a release. Publishing runs from continuous integration, with no stored token, and each version carries a signed provenance attestation that can be checked on the registry.