Assemble your own tour.
Unstyled, accessible React primitives for product tours and onboarding. Fit the parts into your design system — or copy styled ones from the shadcn registry.
pnpm add @awesome-tour/react- MIT licensed
- React 18 & 19
- SSR-safe
- Targets in 3D scenes
Bounce your first loop
Export renders the loop to one file. Click it to continue.
What’s in the box
Start with one package. Add the others only when a tour needs them — each one has a size budget (minified + brotli), checked on every pull request.
Styled parts, sold separatelyThe shadcn registry copies Tailwind-styled tour, checklist and hotspot components into your codebase. Every demo on this site uses them.- A
@awesome-tour/coreincl.
The headless engine: steps, branching, routes, persistence, analytics. No dependencies; comes with B.
≤10kB - B
@awesome-tour/react1×
Compound components and hooks, plus checklists and hotspots.
≤18kB - C
@awesome-tour/motion0–1×
A spring spotlight that glides between targets; animated content.
≤4kB - D
@awesome-tour/router0–1×
React Router, Next.js and TanStack Router adapters for multi-page tours.
≤1kB - E
@awesome-tour/three0–1×
Point steps at objects inside react-three-fiber scenes.
≤3kB - F
@awesome-tour/devtools0–1×
Inspect and drive every tour while you develop.
≤7kB
Assembly in four steps
Install one package
The React layer re-exports the engine. Nothing else is required.
Terminal window pnpm add @awesome-tour/reactDescribe the steps
A tour is data: targets as selectors, refs or anchors; steps that wait for a click; branches as plain functions.
tours.ts import { anchor, createTour } from '@awesome-tour/react';export const onboarding = createTour({id: 'first-session',steps: [{ id: 'welcome', title: 'Your first session' },{ id: 'transport', target: '#transport', title: 'Press play' },{ id: 'kick', target: anchor('kick-row'), title: 'Lay down four kicks',advanceOn: { when: () => kicks() >= 4 } },],});Fit the parts
Every part is an unstyled element with
asChild, data attributes and CSS variables. Use only the parts you want.Onboarding.tsx <Tour.Root tour={onboarding}><Tour.Trigger>Start tour</Tour.Trigger><Tour.Portal><Tour.Overlay /><Tour.Content className="card"><Tour.Arrow /><Tour.Progress /><Tour.Title /><Tour.Description /><Tour.Prev>Back</Tour.Prev><Tour.Next>Next</Tour.Next></Tour.Content></Tour.Portal></Tour.Root>Or skip to styled
One command copies a finished, Tailwind-styled tour into your components — yours to edit.
Terminal window npx shadcn@latest add @awesome-tour/tour
The workbench
A live step runs while the bench is on screen. Swap a part and watch it change — the code underneath follows along, ready to copy.
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
Beat A
16 steps · drumsMixer
4 channels// npx shadcn add @awesome-tour/tour-motion
import { Tour } from '@awesome-tour/react';
import { TourMotionPopover } from '@/components/awesome-tour/tour-motion';
<Tour.Root tour={tour}>
<TourMotionPopover backdrop="spotlight" dots />
</Tour.Root>Accessible before you touch it
The primitives handle the parts people get wrong. Every demo on this site is checked with axe, in light and dark themes, on every change.
Does: Focus moves into each step and returns to where it was when the tour closes.
Avoids: A dimmed page that still takes Tab focus behind the overlay.
Does: Everything outside the step is inert while a modal step is open; the target stays usable.
Avoids: Clicks leaking through to the page, or a highlighted button that can’t be clicked.
Does: Each step is a labelled dialog, and step changes are announced to screen readers.
Avoids: A tooltip that changes silently.
Does: Arrow keys and Escape work out of the box; reduced-motion users get instant transitions.
Avoids: Springs and slides forced on everyone.
Fits the app you already have
The cases that break other tour libraries each have a guide and a live demo.
- B·05Multi-page toursTours that cross routes, with adapters for your router.
- B·03Interactive stepsSteps that wait for a click, an input, or your own signal.
- B·173D scenesHighlight a mesh inside a 3D scene, with a camera shot per step.
- B·06PersistenceResume after a reload, sync across tabs, never show twice.
- B·10Onboarding checklistAn onboarding checklist whose items complete themselves.
- B·08Multiple toursSeveral tours on one page, queued by priority.