State-machine powered

Product tours that feel native

A state-machine architecture that handles real-world complexity. Navigation changes, async content, and interrupted flows just work.

Get StartedGitHub
flow.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
import { createFlow } from "@flowsterix/core";

const onboardingFlow = createFlow({
  id: "welcome-tour",
  version: { major: 1, minor: 0 },
  steps: [
    {
      id: "welcome",
      target: { selector: "#welcome-banner" },
      advance: [{ type: "manual" }],
    },
    {
      id: "explore-features",
      target: { selector: "#features" },
      advance: [{ type: "delay", ms: 3000 }],
    },
    {
      id: "try-demo",
      target: { selector: "#demo-button" },
      advance: [{
        type: "event",
        event: "click",
        on: "target",
      }],
    },
  ],
});

Why another tour library?

Most tour libraries work great in demos. Then your users start navigating, refreshing, and doing things you didn't expect.

The Problem

  • Tours break when users navigate
  • State lost on page refresh
  • Can't handle async content
  • No graceful error recovery

The Solution

  • Router-aware step transitions
  • Full state persistence built-in
  • Predicate rules wait for content
  • State machine handles edge cases

Features

Built for production

Everything you need to create product tours that survive the real-world chaos of async content, navigation, and interrupted sessions.

Declarative Flows

Define tours as data, not imperative code. Flows are serializable, versionable, and easy to maintain.

5 Advance Rules

Manual, Event, Delay, Predicate, and Route. Mix and match to create exactly the flow you need.

Semantic Versioning

Migrate users gracefully when tours change. Resume interrupted flows from exactly where they left off.

Router Integration

Built-in adapters for TanStack Router, React Router, and Next.js. Route changes don't break your tours.

Accessibility First

Focus trapping, ARIA labels, keyboard navigation, and reduced motion support built-in.

Full Persistence

localStorage, API, or custom adapters. State is automatically saved and restored.

Developer Experience

Expressive, declarative API

Write tours as configuration, not imperative code. Everything is TypeScript-first with full autocompletion.

app.tsx
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
import { TourProvider } from "@flowsterix/react";
import { TourHUD } from "@/components/tour-hud";
import { createFlow } from "@flowsterix/core";

const welcomeFlow = createFlow({
  id: "welcome",
  version: { major: 1, minor: 0 },
  steps: [
    {
      id: "step-1",
      target: { selector: "#welcome-message" },
      advance: [{ type: "manual" }],
    },
    {
      id: "step-2",
      target: { selector: "#main-feature" },
      advance: [{ type: "manual" }],
    },
  ],
});

function App() {
  return (
    <TourProvider flows={[welcomeFlow]}>
      <YourApp />
      <TourHUD />
    </TourProvider>
  );
}

State Machine Architecture

Pause. Navigate. Resume.

Live State Flow

Your tour state survives
anything

Running
Paused
Resumed

Pause Anywhere

Close the browser mid-tour. State persists to localStorage, API, or custom storage.

Handle Chaos

Route changes, refreshes, async content loading. The state machine adapts.

Resume on Any Device

Started a tour on desktop? Continue on mobile. State syncs across devices with custom persistence adapters.

Instant Resume

Pick up exactly where users left off. No lost progress, no confusion.

Zero-latency restore

Developer Tools

Build tours visually

Grab elements, reorder steps, inspect flows, and export configurations — all from a draggable panel that lives in your app.

Ctrl+Shift+G

Element Grabber

Click any element on the page to capture its CSS selector, React component tree, and source file location. Build tour steps visually.

Drag & Drop Reorder

Rearrange captured steps with drag-and-drop. Export the step order as JSON or copy it to your clipboard.

Flow Inspector

View all registered flows, their status (running, paused, completed), current step, and version. Edit flow state as JSON in real time.

Export & Copy

Download captured steps as a versioned JSON file or copy to clipboard. Includes selectors, component hierarchy, and source locations.

Source Tracking

See exactly which file and line number each element comes from. Click to open in VS Code. Traces the full React component hierarchy.

Keyboard Shortcuts

Ctrl+Shift+M to collapse, Ctrl+Shift+G to grab, Escape to cancel. Fully keyboard-navigable with accessibility support.

providers.tsx
1
2
3
4
5
6
7
8
9
10
11
12
import { DevToolsProvider } from '@flowsterix/react/devtools'

function App() {
  return (
    <TourProvider flows={[myFlow]}>
      <DevToolsProvider enabled={process.env.NODE_ENV === 'development'}>
        <YourApp />
        <TourHUD />
      </DevToolsProvider>
    </TourProvider>
  )
}

Zero production overhead

DevTools ship as a separate entry point @flowsterix/react/devtools. If you don't import it, it's not in your bundle. Conditional enabled prop keeps the DOM clean when disabled.

Shadow DOM isolation

The DevTools panel renders in a Shadow DOM so your app's CSS never conflicts with the panel, and the panel's styles never leak into your app.

Keyboard-first workflow

Toggle grab mode with Ctrl+Shift+G, collapse the panel with Ctrl+Shift+M, and save edits with Ctrl+S.

Quick Start

Get started in minutes

Install the packages, add UI components via shadcn, and start building tours.

Step 1

Install the packages

$ pnpm add @flowsterix/core@latest @flowsterix/react@latest motion
Step 2

Add UI components via shadcn

$ npx shadcn@latest add https://flowsterix.com/r/tour-hud.json

Installs overlay, popover, controls, progress, and step content primitives.

Step 3 (Optional)

Add the AI skill

$ npx skills add kvngrf/flowsterix --skill flowsterix-best-practices
$ npx skills add kvngrf/flowsterix --skill studio-sdk

Works with Claude Code, Cursor, and other AI coding assistants. flowsterix-best-practices covers tour patterns, advance rules, and lifecycle hooks. studio-sdk covers Studio analytics integration, event serialization, and batched transport.

Step 4 (Optional)

Add DevTools for development

// Wrap your app with DevToolsProvider import { DevToolsProvider } from '@flowsterix/react/devtools' <TourProvider> <DevToolsProvider> <App /> </DevToolsProvider> </TourProvider>

Element grabber, step reordering, flow inspector, and JSON export. Tree-shakeable — zero bytes in production when not imported.

TypeScript-firstTree-shakeableshadcn compatibleAI-ready

That's it. Start defining flows and watch tours come to life.

View Documentation