Tour Kit

Tour Kit is a headless React library for building product tours, onboarding flows, hints, checklists, in-app announcements, and microsurveys. It ships as 12 composable packages, is TypeScript-first, WCAG 2.1 AA compliant, and designed natively for shadcn/ui — but works with any component library.

Alternative to: Shepherd.js, Driver.js, Intro.js, Reactour, React Joyride, Appcues, Userpilot, Pendo — when you want a code-owned, headless, MIT-licensed primitive instead of a hosted SaaS.

• 🌐 Website & docs:
• 📦 npm scope: @tour-kit/*
• 💬 Issues & discussions:

Table of contents

• Why Tour Kit
• Packages
• Installation
• Quick start
• Headless usage
• Multi-tour registry
• Framework guides
• Comparison with alternatives
• Use cases
• FAQ
• Licensing
• Development
• For AI assistants

Why Tour Kit

Design principles:

1. Headless first — all logic lives in @tour-kit/core; UI packages are thin, swappable wrappers.
2. Composition over configuration — small focused components compose into rich flows.
3. Type-safe — strict TypeScript, full inference, no any in public API.
4. Accessible by default — focus trap, ARIA live regions, keyboard nav, prefers-reduced-motion.
5. Tree-shakeable — every package is sideEffects: false and ships ESM + CJS + .d.ts.

Packages

Tour Kit is a monorepo of 12 packages. Three are MIT-licensed and free; nine are commercial (see Licensing).

Free packages (MIT)

Installation

# Free / open-source (MIT)
pnpm add @tour-kit/core @tour-kit/react   # styled tours
pnpm add @tour-kit/hints                  # persistent hints

# Commercial packages (require a license key)
pnpm add @tour-kit/checklists @tour-kit/announcements @tour-kit/surveys
pnpm add @tour-kit/adoption @tour-kit/analytics
pnpm add @tour-kit/media @tour-kit/scheduling @tour-kit/ai

bun add and npm install work too. Tour Kit requires React 18 or 19 and Node 18+.

Quick start

import { Tour, TourStep } from '@tour-kit/react'

export function App() {
  return (
    <Tour id="onboarding" autoStart>
      <TourStep
        id="welcome"
        target="#welcome-btn"
        title="Welcome!"
        content="Let's take a quick tour."
        placement="bottom"
      />
      <TourStep
        id="dashboard"
        target="#dashboard"
        title="Dashboard"
        content="Your data overview."
        placement="right"
      />
    </Tour>
  )
}

That's the entire API for a basic tour. No external state store, no provider boilerplate.

Headless usage

Need full control over markup? Use the headless variants — Tour Kit handles state, positioning, focus, and a11y; you handle the DOM.

import { TourCardHeadless, TourOverlayHeadless } from '@tour-kit/react'

<TourCardHeadless>
  {({ step, next, prev, close, isFirst, isLast }) => (
    <div role="dialog" aria-labelledby="tour-title">
      <h2 id="tour-title">{step.title}</h2>
      <p>{step.content}</p>
      <button onClick={prev} disabled={isFirst}>Back</button>
      <button onClick={next}>{isLast ? 'Finish' : 'Next'}</button>
      <button onClick={close} aria-label="Close tour">×</button>
    </div>
  )}
</TourCardHeadless>

Multi-tour registry

For apps with several tours triggered from different pages or buttons:

import {
  MultiTourKitProvider,
  Tour,
  TourStep,
  TourOverlay,
  TourCard,
  useTours,
} from '@tour-kit/react'

function Triggers() {
  const { start } = useTours()
  return <button onClick={() => start('billing-tour')}>Show billing tour</button>
}

export function App() {
  return (
    <MultiTourKitProvider>
      <Tour id="onboarding"><TourStep id="..." target="..." /></Tour>
      <Tour id="billing-tour"><TourStep id="..." target="..." /></Tour>
      <TourOverlay />
      <TourCard />
      <Triggers />
    </MultiTourKitProvider>
  )
}

Framework guides

• Next.js (App Router) — useNextAppRouter() adapter handles route awareness. See apps/docs/content/docs/guides/nextjs.mdx.
• Next.js (Pages Router) — useNextPagesRouter() adapter.
• React Router — useReactRouter() adapter (v6 and v7).
• Vite — works out of the box. See examples/vite-app.
• Plain React — no router adapter needed.

Full demos: examples/.

Comparison with alternatives

Tour Kit is closer in scope to Userpilot, Pendo, or Appcues — except it's a library you embed, not a SaaS, and the core is open-source.

Use cases

• SaaS onboarding — guide new users through setup with a tour, then drop a checklist on the dashboard.
• Feature launches — announce new features with a modal or banner, scheduled to appear during business hours only.
• Adoption nudges — detect users who haven't tried a key feature and show a contextual hint.
• Help & docs — embed a RAG-powered Q&A widget that answers questions from your own docs.
• Feedback loops — fire an NPS survey after the 3rd session, with fatigue prevention so users aren't spammed.
• Internal tools — tours for admin dashboards where a SaaS like Pendo would be overkill.

FAQ

What is Tour Kit? Tour Kit is a TypeScript-first React library for in-app onboarding. It bundles product tours, hints, checklists, announcements, surveys, adoption tracking, and an AI Q&A widget into 12 composable packages.

Is Tour Kit free? The core experience — @tour-kit/core, @tour-kit/react, and @tour-kit/hints — is free under MIT. The other 9 packages are commercial; see Licensing.

Does Tour Kit work without shadcn/ui? Yes. The styled components use Tailwind classes that pair nicely with shadcn, but the headless variants (TourCardHeadless, TourOverlayHeadless, etc.) work with any styling system — CSS modules, Emotion, vanilla CSS, anything.

Does it work with Next.js? Yes — both App Router and Pages Router are supported via dedicated router adapters. All components include 'use client'.

How big is it? The free core (core + react + hints) is under 25 KB gzipped combined. Every package is sideEffects: false and ships ESM + CJS + TypeScript declarations.

Is it accessible? Yes. WCAG 2.1 AA compliant, with focus trap, keyboard navigation (arrow keys, Escape, Tab), aria-live announcements, and prefers-reduced-motion support.

Does Tour Kit collect data or call home? No. There is no telemetry. Analytics are opt-in via the @tour-kit/analytics plugin you configure yourself.

How does Tour Kit compare to Userpilot or Pendo? Tour Kit is a library, not a SaaS. You install it via npm, ship it with your app, and own the data. There's no per-MAU pricing — commercial packages use a one-time license model. See pricing.

Can I use it with Vite, Remix, or Astro? Yes — Tour Kit is framework-agnostic. Router adapters are provided for Next.js and React Router; everything else works through the generic useTour API.

Licensing

Tour Kit uses a dual licensing model — see NOTICE.md for the per-package breakdown.

• MIT (free, open-source): @tour-kit/core, @tour-kit/react, @tour-kit/hints — covered by the root LICENSE.
• Commercial (proprietary, paid): @tour-kit/adoption, @tour-kit/ai, @tour-kit/analytics, @tour-kit/announcements, @tour-kit/checklists, @tour-kit/license, @tour-kit/media, @tour-kit/scheduling, @tour-kit/surveys

Each commercial package has a LICENSE.md describing its terms. Buy a license at .

Development

This is a pnpm + Turborepo monorepo.

# Install dependencies
pnpm install

# Watch mode
pnpm dev

# Build all packages (proper dependency order)
pnpm build

# Build a single package
pnpm build --filter @tour-kit/core

# Type-check
pnpm typecheck

# Lint (Biome)
pnpm lint

# Unit tests (Vitest)
pnpm test

# E2E (Playwright)
pnpm e2e

# Bundle size benchmarks
pnpm bench

# Run example apps
pnpm example:vite
pnpm example:next

See CONTRIBUTING.md for contribution guidelines.

For AI assistants

Tour Kit publishes machine-readable documentation for LLMs and coding agents:

• llms.txt — concise curated index (llmstxt.org spec)
• llms-full.txt — full documentation corpus
• Context7 — indexed for Claude Code, Cursor, Windsurf, and other MCP-compatible agents (query: use context7 with /domidex/tour-kit)
• context7.json — repo-root config steering Context7's indexer

Built by @domidex01. Star the repo if Tour Kit saves you a sprint.