APOLLO VISION LABS

guide

Product tours and a first steps checklist for React, with a Material UI rendering layer.

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

Demonstration

The application below is fictional and runs inside this page: start the tour and it will change screen on its own.

  • Targets a data-guide attribute

    A step names a key carried by a data-guide attribute, and the library waits for the target when it is not on screen yet.

  • Tours across pages

    A tour changes page by calling the navigation function the application supplies, and depends on no router.

  • Checklist that persists

    A checklist item can start the tour that teaches it, and both share one storage contract.

  • Accessibility in the logic layer

    A focus trap, a screen reader announcement on each step, and respect for reduced motion.

doc

Documentation

9 pages

The package in detail: installation, concepts, reference and migration.

  1. Getting started

    Install the two packages, run a first tour, and wire the provider to a real application.

  2. Tours

    The shape of a tour and its steps, the missing target policy, multi page tours, interactive steps, advancing on a click and manual control.

  3. Checklist

    A list of first steps, what actually completes an item, its link with tours, and the two components that render it.

  4. Hotspots

    A marker on one element that opens a short explanation and can start a tour, what retires it for good, and when it draws nothing at all.

  5. Persistence

    How guide stores tour, checklist and hotspot progress, what the GuideStorage contract requires, and what happens when a read is slow.

  6. Accessibility

    What guide does for a keyboard user and a screen reader, and the deliberate exceptions.

  7. API reference

    Every exported symbol of guide-core and guide-mui, with its signature and what it does.

  8. Migrating to 0.2.0

    What changes for an application on 0.1.x, in order, and what needs no attention at all.

  9. Migrating to 0.3.0

    What changes for an application on guide-core 0.2.0 and guide-mui 0.3.0, in order, and the one thing that needs attention.

Read the documentation

guide builds in-app product tours: the guided walkthrough that shows a new user around an application. The logic sits in one package that depends only on React, the Material UI rendering in a second one.

Installation

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

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>
  );
}

What the library does

A logical key, not a CSS selector

A step targets a key carried by a data-guide attribute, so a tour survives markup changes. If the target is missing, the library waits for it, then applies a policy of your choice: skip, wait or error.

Several screens, no imposed router

A tour crosses pages by calling a navigation function the application supplies. The library depends on no router.

A single SVG overlay

The highlight is one SVG overlay, measured before the browser paints.

Accessibility in the logic layer

A focus trap, a screen reader announcement per step, and respect for reduced motion. A step marked interactive is deliberately not modal, so a keyboard user can reach the element they are told to click.

A checklist beside the tour

A tour teaches one flow. A checklist is what survives the first session: a short list of first steps that persists, shows how far someone got, and gives them somewhere to come back to. An item can carry a tour, so activating it starts the tour that teaches it, and finishing that tour ticks the item.

The two features share one storage contract, so an application that persists tour progress to its own backend persists the checklist through the same code.

Why we wrote it

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

← Back to packages