UserTourKit (published as Tour Kit) is a headless, TypeScript-first React library for building product tours, onboarding flows, hints, checklists, in-app announcements, and microsurveys, built for React developers who want to own onboarding code rather than rent it from a hosted platform.

What it is

Tour Kit is distributed through npm under the @tour-kit/* scope as a monorepo of 12 packages. It is headless in the strict sense: all tour logic lives in @tour-kit/core, while the UI packages are thin, swappable wrappers. The library is written in strict TypeScript with no any in the public API, and it is designed natively for shadcn/ui while remaining compatible with any component library. It requires React 18 or 19 on Node 18 or later, and every package is tree-shakeable, marked sideEffects: false, and shipped as ESM, CJS, and .d.ts files.

The problem it solves is the split between owning an onboarding experience and paying a vendor to host it. Hosted tools such as Appcues, Userpilot, and Pendo place tour authoring behind a SaaS dashboard, which means the flows, the audience rules, and the resulting user data live with the vendor. Tour Kit replaces that with a code-owned primitive: tours are declarative JSX using the Tour and TourStep components imported from @tour-kit/react, so they live in the same repository, review process, and deployment pipeline as the rest of the product. It also positions itself against client-side tour libraries such as Shepherd.js, Driver.js, Intro.js, Reactour, and React Joyride.

Key capabilities

• Declarative product tours built from Tour and TourStep components, with focus trap, keyboard navigation, and route awareness.
• Persistent hints implemented as beacon hotspots and tooltips that survive across sessions, which the README describes as unique in the shadcn ecosystem.
• Onboarding checklists with task dependencies, progress tracking, persistence, and tour hand-off handled by a single provider.
• In-app announcements in five variants — modal, slideout, banner, toast, and spotlight — with frequency rules and audience targeting.
• Microsurveys covering NPS, CSAT, and CES, with built-in fatigue prevention and context awareness.
• Feature adoption tracking that measures usage, computes adoption status, and triggers nudges automatically.
• An analytics plugin interface for PostHog, Mixpanel, Amplitude, and GA4, plus a drop-in RAG chat widget for in-app help.

Who uses it and how

• React product teams that want onboarding flows reviewed in pull requests rather than edited in a vendor dashboard.
• Teams already on shadcn/ui, which get native styling integration while keeping the option to swap in another component library.
• Applications needing persistent guidance rather than one-off tours, using beacon hotspots and tooltips that reappear for returning users.
• Products measuring activation, combining checklists, adoption tracking, and NPS, CSAT, or CES microsurveys behind one provider.
• Teams with an existing analytics stack that route tour events into PostHog, Mixpanel, Amplitude, or GA4 through the plugin interface.

Getting started

Install the free, MIT-licensed packages with pnpm add @tour-kit/core @tour-kit/react; npm install and bun add work too, and commercial packages install the same way but require a license key. Documentation and framework guides live at https://usertourkit.com/.

How it compares

Against hosted platforms such as Appcues, Userpilot, and Pendo, the difference is where the software and the data live: Tour Kit is a code-owned library rather than a SaaS subscription, so tours ship inside the application, user data stays in your infrastructure, and the free packages carry no vendor bill. That advantage is partial, because the licence is split rather than uniform — only three of the twelve packages are MIT, and the remaining nine require a commercial license key.

When to use it — and when not to

Tour Kit suits React teams comfortable operating their own front-end stack that want onboarding under their own control; the free MIT packages need no extra runtime infrastructure, though checklists, surveys, and analytics sit behind a paid license key. Teams not on React 18 or 19, or those wanting a no-code tour builder maintained entirely by a vendor, should look elsewhere. The project is also small and early — 66 stars, 31 forks, and one open issue — and the mixed MIT-plus-commercial licence means the full feature set is not free.

# 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

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

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>

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