Skip to content
awesome-tour

Type to search every page.

    BWithout ReactContents

    Without React

    Use awesome-tour from Vue, Svelte, Angular or plain HTML with a DOM renderer and an <awesome-tour> custom element.

    The engine (@awesome-tour/core) has no framework in it. @awesome-tour/elements adds a renderer that needs none either: overlay, card, keyboard, focus trap, inert, RTL and screen-reader announcements in plain DOM, inside a shadow root.

    @awesome-tour/elements
    Loopworknight-drive.lwp
    001.1.1

    Beat A

    16 steps · drums
    Kick
    Snare
    Hat
    Clap

    Mixer

    4 channels
    Drums
    80%
    Bass
    35%
    Keys
    60%
    Vox
    50%
    VanillaDemo.tsx
    import { createTour } from '@awesome-tour/core';
    import { mountTour } from '@awesome-tour/elements';
    import { LoopworkApp, parts } from '@loopwork';
    import { Play } from 'lucide-react';
    import { useEffect } from 'react';
    import { DemoFrame, worldButton } from './ui';
    const $ = parts('plain');
    // A tour from @awesome-tour/core, rendered by @awesome-tour/elements: no React in the tour UI.
    // (The page itself is React here; the same code runs in Vue, Svelte or a plain <script>.)
    const tour = createTour({
    id: 'docs-vanilla',
    steps: [
    {
    id: 'transport',
    target: $('transport'),
    title: 'No React in this card',
    description: 'mountTour() draws it with plain DOM in a shadow root.',
    },
    {
    id: 'grid',
    target: $('sequencer'),
    side: 'top',
    title: 'Themed with CSS variables',
    description: 'This page sets --tour-bg, --tour-accent… on awesome-tour-layer.',
    },
    {
    id: 'mixer',
    target: $('mixer'),
    side: 'start',
    title: 'Same engine, same keys',
    description: 'Arrows, Escape, focus trap and announcements come built in.',
    },
    ],
    });
    export function VanillaDemo() {
    useEffect(() => mountTour(tour), []);
    return (
    <DemoFrame
    title="@awesome-tour/elements"
    actions={
    <button
    type="button"
    className={worldButton.primary}
    onClick={() => void tour.start({ force: true })}
    >
    <Play aria-hidden="true" />
    Start tour
    </button>
    }
    >
    <LoopworkApp scope="plain" layout="compact" />
    </DemoFrame>
    );
    }
    Terminal window
    pnpm add @awesome-tour/core @awesome-tour/elements

    The <awesome-tour> element

    For a page that has no build step, or a CMS that serves tours as JSON:

    <script type="module">
    import '@awesome-tour/elements/define';
    </script>
    <awesome-tour src="/tours/first-session.json" autostart persist locale="pt-BR"></awesome-tour>
    Attribute Effect
    src URL of a tour JSON document (validated by fromJSON).
    autostart Start once loaded.
    persist Remember progress in localStorage (resume, don’t show again).
    locale Language for text per locale.
    modal "false" for a non-blocking tour.

    Properties: tour (hand it a tour instead of src) and actions (the functions the JSON names). Methods: start(), close(). Events, bubbling: tour-start, tour-step (detail.stepId), tour-complete, tour-close, tour-skip, tour-error.

    const el = document.querySelector('awesome-tour');
    el.actions = { isPro: () => user.plan === 'pro' };
    el.addEventListener('tour-complete', () => analytics.track('tour_completed'));

    From code: mountTour

    import { createTour } from '@awesome-tour/core';
    import { mountTour } from '@awesome-tour/elements';
    const tour = createTour({ id: 'first-session', steps });
    const unmount = mountTour(tour, { modal: true, locale: 'pt-BR', labels: { next: 'Próximo' } });
    tour.start();

    In Vue, call it in onMounted and the returned function in onUnmounted; in Svelte, in onMount (return the function). Everything else — rules, persistence, analytics, goals, the manager — is the same core API.

    Theming

    The card lives in a shadow root, so page CSS can’t break it by accident. Style it on purpose:

    awesome-tour-layer {
    --tour-bg: #0f0f12;
    --tour-fg: #f4f4f5;
    --tour-accent: #8b7dff;
    --tour-radius: 16px;
    --tour-overlay: rgb(0 0 0 / 0.6);
    }
    awesome-tour-layer::part(title) { font-family: 'Your Display', sans-serif; }

    Parts: overlay, card, header, progress, close, title, description, footer, back, next. mountTour(tour, { unstyled: true }) leaves out the built-in look entirely.