Introduction
What awesome-tour is, why it exists and how it is organized.
awesome-tour is a set of unstyled, accessible React primitives for product tours, hints and onboarding checklists — built the way Radix builds dialogs and popovers.
Why another tour library?
Most tour libraries were designed when a tour was a list of selectors and a tooltip with a fixed look. In a modern app that breaks down quickly:
- Styling is a fight. Pre-built tooltips must be overridden, themed and re-themed. awesome-tour ships zero CSS: you compose parts and style them like the rest of your design system.
- Tours are brittle. Selectors break, targets load late, routes change. awesome-tour resolves targets asynchronously (anchors, refs, selectors, virtual elements), waits for them, follows the user across pages and has an explicit policy for when a target is missing.
- Real onboarding is not linear. Steps depend on the user’s role, on what they clicked, on what they typed. awesome-tour has conditional steps, branching, interactive steps and a history-aware “back”.
- Accessibility is an afterthought. Here it is the default: dialog semantics, focus management,
inert, keyboard navigation and screen-reader announcements. - It has to scale. Many tours on one app, saved progress across devices, analytics, checklists, devtools.
Principles
- Headless engine.
@awesome-tour/coreis a framework-agnostic state machine. The React layer only renders its state. - Composition over configuration. Every visual part is a component you can replace, wrap or
render
asChild. - Controlled or uncontrolled. Let the tour manage itself, or drive
openandstepfrom your own state. - Accessible by default, unstyled by default. You can’t forget the ARIA; you can’t be stuck with the look.
- Concurrent-safe. Built on
useSyncExternalStore; SSR-safe and StrictMode-safe.
Packages
| Package | What it does |
|---|---|
@awesome-tour/core |
Headless engine: tours, steps, persistence, analytics, checklists. |
@awesome-tour/react |
React primitives and hooks. Re-exports the core. |
@awesome-tour/motion |
Animated overlay and content built on motion. |
@awesome-tour/three |
Targets inside react-three-fiber scenes. |
@awesome-tour/router |
React Router, Next.js and TanStack Router adapters. |
@awesome-tour/devtools |
A development panel to inspect and drive tours. |