[](https://www.npmjs.com/package/@tour-kit/react)
[](https://www.npmjs.com/package/@tour-kit/core)
[](https://bundlephobia.com/package/@tour-kit/core)
[](./NOTICE.md)
[](./tsconfig.json)
[](apps/docs/content/docs/guides/accessibility.mdx)
**Tour Kit is a headless React library for building product tours, onboarding flows, hints, checklists, in-app announcements, and microsurveys.** It ships as 17 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, source-available primitive instead of a hosted SaaS.
- 🌐 Website & docs:
- 📦 npm scope: [`@tour-kit/*`](https://www.npmjs.com/org/tour-kit)
- 💬 Issues & discussions:
---
## Table of contents
- [Why Tour Kit](#why-tour-kit)
- [Packages](#packages)
- [Installation](#installation)
- [Quick start](#quick-start)
- [Headless usage](#headless-usage)
- [Multi-tour registry](#multi-tour-registry)
- [Framework guides](#framework-guides)
- [Comparison with alternatives](#comparison-with-alternatives)
- [Use cases](#use-cases)
- [FAQ](#faq)
- [Licensing](#licensing)
- [Development](#development)
- [For AI assistants](#for-ai-assistants)
---
## Why Tour Kit
| Need | What Tour Kit gives you |
| --- | --- |
| **Product tours** | Declarative `` + `` components, focus trap, keyboard nav, route awareness |
| **Persistent hints** | Beacon hotspots and tooltips that survive across sessions — unique in the shadcn ecosystem |
| **Onboarding checklists** | Task dependencies, progress tracking, persistence, and tour hand-off in one provider |
| **Announcements** | 5 variants (modal, slideout, banner, toast, spotlight) with frequency rules and audience targeting |
| **Microsurveys** | NPS, CSAT, CES with built-in fatigue prevention and context awareness |
| **Feature adoption** | Track usage, compute adoption status, and trigger nudges automatically |
| **Analytics** | Plugin interface for PostHog, Mixpanel, Amplitude, GA4 — or roll your own |
| **AI Q&A widget** | Drop-in RAG chat for in-app help |
**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 17 packages. Five are source-available under BUSL-1.1, three are MIT-licensed utilities, and nine are commercial (see [Licensing](#licensing)).
### Source-available packages (BUSL-1.1: free in development, licence key in production)
| Package | Purpose | Bundle (gzip) |
| --- | --- | --- |
| [`@tour-kit/core`](packages/core) | Framework-agnostic hooks, types, position engine, storage adapters | < 8 KB |
| [`@tour-kit/react`](packages/react) | Tour, TourStep, TourCard, TourOverlay, router adapters, multi-tour registry | < 12 KB |
| [`@tour-kit/hints`](packages/hints) | Persistent hint beacons, hotspots, tooltips | < 5 KB |
| [`@tour-kit/vue`](packages/vue) | Headless Vue 3 binding for the Tour Kit engine | — |
| [`@tour-kit/svelte`](packages/svelte) | Headless Svelte 5 binding for the Tour Kit engine | — |
### MIT-licensed utilities (free, no key)
| Package | Purpose |
| --- | --- |
| [`@tour-kit/codemods`](packages/codemods) | Codemods to migrate from Joyride, Shepherd, and Driver.js to Tour Kit |
| [`@tour-kit/testing-library`](packages/testing-library) | React Testing Library helpers for Tour Kit |
| [`@tour-kit/playwright`](packages/playwright) | Playwright fixtures for Tour Kit |
### Commercial packages
| Package | Purpose |
| --- | --- |
| [`@tour-kit/adoption`](packages/adoption) | Feature usage tracking, adoption status, nudges, dashboard components |
| [`@tour-kit/ai`](packages/ai) | RAG-powered in-app Q&A chat widget |
| [`@tour-kit/analytics`](packages/analytics) | Plugin-based analytics: PostHog, Mixpanel, Amplitude, GA4, console |
| [`@tour-kit/announcements`](packages/announcements) | Modal, slideout, banner, toast, spotlight + queue & frequency rules |
| [`@tour-kit/checklists`](packages/checklists) | Onboarding checklists with task dependencies and tour integration |
| [`@tour-kit/license`](packages/license) | License-key validation for premium features |
| [`@tour-kit/media`](packages/media) | YouTube, Vimeo, Loom, Wistia, GIF, and Lottie embeds |
| [`@tour-kit/scheduling`](packages/scheduling) | Time-based scheduling with timezone, business hours, and blackout support |
| [`@tour-kit/surveys`](packages/surveys) | NPS, CSAT, CES, and custom microsurveys with fatigue prevention |
Buy a commercial license at .
## Installation
```bash
# Source-available (BUSL-1.1: free in dev, licence key in prod)
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
# MIT utilities, dev-only (free, no key)
pnpm add -D @tour-kit/codemods @tour-kit/testing-library @tour-kit/playwright
```
`bun add` and `npm install` work too. Tour Kit requires **React 18 or 19** and **Node 18+**.
## Quick start
```tsx
import { Tour, TourStep } from '@tour-kit/react'
export function App() {
return (
)
}
```
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.
```tsx
import { TourCardHeadless, TourOverlayHeadless } from '@tour-kit/react'
{({ step, next, prev, close, isFirst, isLast }) => (
{step.title}
{step.content}
)}
```
## Multi-tour registry
For apps with several tours triggered from different pages or buttons:
```tsx
import {
MultiTourKitProvider,
Tour,
TourStep,
TourOverlay,
TourCard,
useTours,
} from '@tour-kit/react'
function Triggers() {
const { start } = useTours()
return
}
export function App() {
return (
)
}
```
## Framework guides
- **Next.js (App Router)** — `useNextAppRouter()` adapter handles route awareness. See [`apps/docs/content/docs/guides/nextjs.mdx`](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`](examples/vite-app).
- **Plain React** — no router adapter needed.
Full demos: [`examples/`](examples).
## Comparison with alternatives
| Feature | **Tour Kit** | Driver.js | React Joyride | Intro.js | Shepherd.js |
| --- | --- | --- | --- | --- | --- |
| Headless API | ✅ | ❌ | Partial | ❌ | ❌ |
| TypeScript-first | ✅ | ✅ | ✅ | Types only | Types only |
| shadcn/ui native | ✅ | ❌ | ❌ | ❌ | ❌ |
| Persistent hints | ✅ | ❌ | ❌ | ❌ | ❌ |
| Checklists | ✅ | ❌ | ❌ | ❌ | ❌ |
| Announcements (5 variants) | ✅ | ❌ | ❌ | ❌ | ❌ |
| Microsurveys (NPS/CSAT/CES) | ✅ | ❌ | ❌ | ❌ | ❌ |
| Feature adoption tracking | ✅ | ❌ | ❌ | ❌ | ❌ |
| Analytics plugin system | ✅ | ❌ | ❌ | ❌ | ❌ |
| Multi-tour registry | ✅ | ❌ | Partial | ❌ | Partial |
| WCAG 2.1 AA | ✅ | Partial | ✅ | Partial | Partial |
| Tree-shakeable ESM | ✅ | ✅ | Partial | ❌ | ✅ |
| Source-available core | ✅ BUSL-1.1 | ✅ MIT | ✅ MIT | ✅ AGPL/Commercial | ✅ MIT |
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 source-available.
## 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 17 composable packages.
**Is Tour Kit free?**
The core experience — `@tour-kit/core`, `@tour-kit/react`, `@tour-kit/hints`, plus the `@tour-kit/vue` and `@tour-kit/svelte` bindings — is **source-available under BUSL-1.1: free in development, evaluation, testing, CI, and any non-production environment, with a licence key required in production**. The `@tour-kit/codemods`, `@tour-kit/testing-library`, and `@tour-kit/playwright` utilities are **MIT-licensed and free everywhere**. The other 9 packages are commercial; see [Licensing](#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 source-available 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](https://usertourkit.com/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 **three-tier licensing model** — see [`NOTICE.md`](./NOTICE.md) for the per-package breakdown.
- **BUSL-1.1 (source-available):** `@tour-kit/core`, `@tour-kit/react`, `@tour-kit/hints`, `@tour-kit/vue`, `@tour-kit/svelte` — free in dev, licence key in production. Each version converts to MIT on its Change Date, four years after release. Terms in each package's `LICENSE.md`.
- **MIT (free, open-source):** `@tour-kit/codemods`, `@tour-kit/testing-library`, `@tour-kit/playwright` — no key in any environment.
- **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](https://pnpm.io) + [Turborepo](https://turbo.build) monorepo.
```bash
# 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](./CONTRIBUTING.md) for contribution guidelines.
## For AI assistants
Tour Kit publishes machine-readable documentation for LLMs and coding agents:
- [`llms.txt`](https://usertourkit.com/llms.txt) — concise curated index ([llmstxt.org](https://llmstxt.org) spec)
- [`llms-full.txt`](https://usertourkit.com/llms-full.txt) — full documentation corpus
- [Context7](https://context7.com/) — indexed for Claude Code, Cursor, Windsurf, and other MCP-compatible agents (query: `use context7 with /domidex/tour-kit`)
- [`context7.json`](./context7.json) — repo-root config steering Context7's indexer
---
Built by [@domidex01](https://github.com/domidex01). Star the repo if Tour Kit saves you a sprint.
---
_Source: https://npm.io/package/@tour-kit/svelte · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
