Skip to content
awesome-tour

Type to search every page.

    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
    Quick start
    • MIT licensed
    • React 18 & 19
    • SSR-safe
    • Targets in 3D scenes
    Six parts, all unstyled primitives.

    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.
    1. A

      @awesome-tour/coreincl.

      The headless engine: steps, branching, routes, persistence, analytics. No dependencies; comes with B.

      ≤10kB
    2. B

      @awesome-tour/react1×

      Compound components and hooks, plus checklists and hotspots.

      ≤18kB
    3. C

      @awesome-tour/motion0–1×

      A spring spotlight that glides between targets; animated content.

      ≤4kB
    4. D

      @awesome-tour/router0–1×

      React Router, Next.js and TanStack Router adapters for multi-page tours.

      ≤1kB
    5. E

      @awesome-tour/three0–1×

      Point steps at objects inside react-three-fiber scenes.

      ≤3kB
    6. F

      @awesome-tour/devtools0–1×

      Inspect and drive every tour while you develop.

      ≤7kB

    Assembly in four steps

    1. Install one package

      The React layer re-exports the engine. Nothing else is required.

      Terminal window
      pnpm add @awesome-tour/react
    2. Describe 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 } },
      ],
      });
    3. 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>
    4. 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.

    ABackdrop
    BCard size
    DProgress
    EFooter
    MMotion
    Loopworknight-drive.lwp
    001.1.1
    1. 1
    2. 2
    3. 3
    4. 4
    5. 5
    6. 6
    7. 7
    8. 8
    Drums
    Beat A
    Beat B
    Bass
    Sub line
    Keys
    Rhodes
    Vox
    Hook (dry)

    Beat A

    16 steps · drums
    Kick
    Snare
    Hat
    Clap

    Mixer

    4 channels
    Drums
    80%
    Bass
    35%
    Keys
    60%
    Vox
    50%
    Onboarding.tsx
    // 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.

    EPart E, enlarged: focus lands on the step’s controls with a visible ring, and goes back when the tour closes.
    • 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.

    Everything you need is in the box.