Skip to content
awesome-tour

Type to search every page.

    AQuick startContents

    Quick start

    Build your first tour in five minutes.

    Live demo
    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%
    BasicDemo.tsx
    import { createTour, Tour } from '@awesome-tour/react';
    import { LoopworkApp, parts } from '@loopwork';
    import { TourPopover } from '@/components/awesome-tour/tour';
    import { DemoFrame, StartButton } from './ui';
    const $ = parts('first-session');
    const tour = createTour({
    id: 'docs-basic',
    steps: [
    {
    id: 'welcome',
    title: 'Your first session',
    description:
    'night-drive is an 8-bar sketch at 92 BPM. Four stops and you know your way around.',
    },
    {
    id: 'transport',
    target: $('transport'),
    title: 'Transport',
    description: 'Play, stop and record. The counter reads bar · beat · step.',
    },
    {
    id: 'arrangement',
    target: $('arrangement'),
    side: 'bottom',
    title: 'Arrangement',
    description: 'One lane per channel. Clips are the parts of your song, laid out bar by bar.',
    },
    {
    id: 'backbone',
    // Several targets in one step: the spotlight covers both rows.
    target: [$('row-kick'), $('row-snare')],
    title: 'Kick and snare',
    description: 'The backbone of the beat. Click a cell to add a hit; each row is one bar.',
    },
    {
    id: 'mixer',
    target: $('mixer'),
    side: 'left',
    title: 'Mixer',
    description: 'Set each channel’s level. Drag a knob up, or focus it and use the arrow keys.',
    },
    ],
    });
    export function BasicDemo() {
    return (
    <Tour.Root tour={tour}>
    <DemoFrame title="Live demo" actions={<StartButton />}>
    <LoopworkApp scope="first-session" />
    </DemoFrame>
    <TourPopover />
    </Tour.Root>
    );
    }
    1. Define the tour. A tour is a list of steps. A step without target is centered; target accepts a selector, an element, a ref, an anchor or an array.

      tours.ts
      import { createTour } from '@awesome-tour/react';
      export const onboarding = createTour({
      id: 'first-session',
      steps: [
      { id: 'welcome', title: 'Your first session', description: 'Four stops, then you’re making music.' },
      { id: 'transport', target: '#transport', title: 'Transport' },
      { id: 'arrangement', target: '#arrangement', title: 'Arrangement' },
      { id: 'mixer', target: '[data-tour="mixer"]', side: 'left', title: 'Mixer' },
      ],
      });
    2. Compose the UI. Tour.Root connects the tour; everything inside Tour.Portal is rendered only while the tour is open. Every part is optional and unstyled.

      Onboarding.tsx
      import { Tour } from '@awesome-tour/react';
      import { onboarding } from './tours';
      export function Onboarding() {
      return (
      <Tour.Root tour={onboarding}>
      <Tour.Trigger className="button">Take the tour</Tour.Trigger>
      <Tour.Portal>
      <Tour.Overlay className="tour-overlay" />
      <Tour.Content className="tour-card" sideOffset={12}>
      <Tour.Arrow className="tour-arrow" />
      <Tour.Progress />
      <Tour.Close aria-label="Close">✕</Tour.Close>
      <Tour.Title />
      <Tour.Description />
      <Tour.StepContent />
      <Tour.Prev>Back</Tour.Prev>
      <Tour.Next>Next</Tour.Next>
      </Tour.Content>
      </Tour.Portal>
      </Tour.Root>
      );
      }
    3. Style it. Parts expose data attributes and CSS variables. A minimal theme:

      tour.css
      [data-tour-overlay] {
      --tour-overlay-color: rgb(0 0 0 / 0.55);
      z-index: 1000;
      }
      [data-tour-content-wrapper] {
      z-index: 1001;
      }
      .tour-card {
      width: 320px;
      padding: 16px;
      border-radius: 12px;
      background: white;
      box-shadow: 0 20px 50px -12px rgb(0 0 0 / 0.35);
      }
      .tour-arrow {
      color: white; /* the arrow is an SVG filled with currentColor */
      }
    4. Start it from anywhere: Tour.Trigger, onboarding.start(), or useTour().start(). Add persistence so it shows once and resumes where the user left off:

      import { createTour, localStorageAdapter, persist } from '@awesome-tour/react';
      export const onboarding = createTour({
      id: 'onboarding',
      version: 1, // bump to show the tour again after meaningful changes
      plugins: [persist(localStorageAdapter())],
      steps: [/* … */],
      });
      // e.g. on first login
      onboarding.start();

    Next steps