At a Glance:
Tour Kit is a headless, TypeScript-first React library for building product tours, onboarding flows, hints, checklists, in-app announcements, and microsurveys, offering shadcn/ui-native components, WCAG 2.1 AA compliance, and a composable 12-package architecture.
Overview:
Tour Kit provides a set of composable, headless primitives for building in-app user guidance experiences directly within a codebase. It addresses common product adoption challenges such as user onboarding, feature discovery, and feedback collection through declarative components like tours, persistent hints, checklists, multi-variant announcements, and microsurveys. The library is designed with a logic-first approach, where all state management, positioning, and accessibility handling reside in a framework-agnostic core. It targets developers who want complete control over the UI layer and need to implement sophisticated, data-driven user flows without embedding a third-party SaaS platform. A dual licensing model applies, with the core packages available under an MIT license.
Key Decision Points:
Headless architecture: All logic is contained in
@tour-kit/core, and the UI packages are swappable wrappers, allowing full control over the rendered DOM if required.Component ecosystem and licensing: The library is split into 12 packages; the core (
@tour-kit/core,@tour-kit/react,@tour-kit/hints) are MIT-licensed, while advanced features like adoption tracking, analytics, and AI are in separate commercial packages.Native shadcn/ui compatibility: The UI layer is designed to integrate seamlessly with shadcn/ui but is documented to work with any component library.
Scope beyond tours: Unlike simpler drivers, Tour Kit bundles in-app announcements, NPS/CSAT/CES microsurveys with fatigue prevention, and a multi-tour registry into a single provider model.
Framework routing support: Dedicated router adapters are available for Next.js (App and Pages routers) and React Router (v6 and v7) to enable route-aware tours.
Core Features:
Declarative tours: Uses a
<TourProvider>and<TourStep>component model with built-in focus trapping, keyboard navigation, and route awareness for building product walkthroughs.Persistent hints: Provides beacon hotspots and tooltips that can persist their state across user sessions.
Onboarding checklists: Supports task dependencies, progress tracking, and state persistence, with the ability to hand off from a tour to a checklist within the same provider.
In-app announcements: Includes five delivery variants (modal, slideout, banner, toast, spotlight) governed by configurable frequency rules and audience targeting logic.
Microsurveys: Delivers NPS, CSAT, and CES surveys with context awareness and built-in fatigue prevention to avoid over-surveying users.
Analytics plugin interface: Offers a pluggable system for integrating with analytics platforms like PostHog, Mixpanel, Amplitude, and GA4, or for creating custom adapters.
Headless usage mode: Exposes headless variants that allow developers to manage the state, positioning, focus, and ARIA live regions while maintaining complete control over the markup.
AI Q&A widget: Includes a drop-in, RAG-powered chat widget designed to answer user questions in-app using provided documentation.
Use Cases:
SaaS onboarding: Guiding new users through an initial setup flow with a product tour, then transitioning them to a persistent onboarding checklist on the dashboard.
Feature launches: Announcing a new feature to a targeted user segment using a modal or banner that is scheduled to appear only during specific hours.
Adoption nudges: Detecting that a user has not interacted with a specific feature and programmatically displaying a contextual hint to encourage trial.
Feedback loops: Triggering an NPS survey after a user's third session, with built-in fatigue rules preventing the survey from being shown again for a defined period.
Open-Source Alternative Value:
Tour Kit’s value as an open-source alternative lies in delivering a code-owned, embeddable library that mirrors the feature scope of hosted platforms like Userpilot or Appcues. The core packages, which handle the state engine, React bindings, and hint primitives, are MIT-licensed, providing a foundation for building guided experiences without a SaaS dependency. The headless, composable architecture ensures that the logic is decoupled from the presentation, giving developers control over the entire UI and data flow. This model serves as an alternative to both simpler, UI-focused libraries like Driver.js and React Joyride, and to more comprehensive but fully proprietary SaaS products, by offering an in-house primitive that can be customized and scaled by the development team.
