ProjectsSeptember 18, 2025

Just a Walkthrough

Framework‑agnostic, zero‑dependency product tour / onboarding walkthrough with optional React helpers.

Features

Spotlight highlight & darkened backdrop (3 panel overlay + focus ring)
Accessible keyboard navigation (Esc / Enter / ← →) + focus trap
Auto scroll + responsive reposition on scroll/resize/mutations
Step hooks (beforeStep / afterStep) & lifecycle callbacks
Chain multiple tours with persistence-aware skipping
LocalStorage progress persistence & resume support
Optional once‑per‑session logic via orchestrator helper
Custom tooltip renderer + theming (default, tailwind, unstyled)
Works with any DOM (vanilla, React, shadcn, portals)
Tiny, tree‑shakeable (no external deps)

Install

npm i just-a-walkthrough

Quick Start

import { startWalkthrough } from 'just-a-walkthrough';

startWalkthrough([
{ selector: '#hero-cta', title: 'Welcome', content: 'Click here to begin.' },
{ selector: '.nav-settings', title: 'Settings', content: 'Manage preferences.' }
]);

Orchestrator

import { registerTours, startAutoMatches } from 'just-a-walkthrough';

registerTours([
{ id: 'home-tour', match: '/home', steps: [ { selector: '#welcome', title: 'Hi!' } ] },
{ id: 'settings-tour', match: '/settings', steps: [ { selector: '#profile', title: 'Profile' } ], oncePerSession: true }
]);

// Call on route change
startAutoMatches({ pathname: window.location.pathname });

API Surface (Core)

startWalkthrough(steps, options) – convenience wrapper returning a Walkthrough instance. Walkthrough key methods:

start(index?) – begin tour (auto called by helper)
next()/prev()
finish() – mark completed & cleanup
skip(reason?)
destroy() – cleanup without marking completed

Theming

Use theme: 'tailwind' to rely on your Tailwind stack (supply utility classes) or unstyled to supply all styling manually.

Chain Multiple Tours


import { WalkthroughChain } from 'just-a-walkthrough';
new WalkthroughChain([
{ id: 'a', steps: [ { selector: '#x' } ] },
{ id: 'b', steps: [ { selector: '#y' } ], options: { persistProgress: true, tourId: 'b' } }
]).start();

Completed persistent tours are skipped automatically.

Advanced Usage Notes

Use waitMs: 0 (or global stepWaitMs: 0) for elements that are guaranteed to be present to avoid unnecessary polling.
Prefer chaining tours when you have progressive disclosure flows; persistent tours auto-skip if already completed, keeping chains idempotent.
When dynamically removing highlighted elements mid-step (e.g. route transitions), the MutationObserver repositions but if the element disappears the next navigation call will resolve again. Consider guarding with required steps if element is critical.

Accessibility Notes

Focus ring container traps tab order (unless disableFocusTrap: true)
Live region announces step titles (aria-live="polite")
Esc always available (when keyboard: true)

Zero-Wait Configuration

Specify stepWaitMs: 0 and/or per-step waitMs: 0 to disable polling for elements (single lookup). stepPollIntervalMs is clamped to a minimum of 1ms internally when waiting.

Contributions welcome. Open an issue or PR with ideas / improvements.

Recent projects

The Eden Project

What if music wasn't so inaccessible..

Read case study

Run over a Deer

A Silly little game based on the hit movie Over The Hedge

Read case study

Daily Planner App

A simple daily planner with a tasks list. cool onboarding tho. WIP

Read case study

Suvan GSgreeenboiGreenArcadeSuvan GSgreeenboiGreenArcadeSuvan GSgreeenboi