Skip to content
awesome-tour

Type to search every page.

    BStylingContents

    Styling

    Style tours with your own CSS — data attributes, CSS variables, asChild and z-index.

    awesome-tour ships no CSS. Every part renders a plain element you style with classes, Tailwind, CSS-in-JS or anything else. The demo below is one tour with five different stylesheets.

    Styling
    Theme
    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%
    StylingDemo.tsx
    import { createTour, Tour } from '@awesome-tour/react';
    import { LoopworkApp, parts } from '@loopwork';
    import { useState } from 'react';
    import {
    TourCard,
    TourCardContents,
    TourOverlay,
    TourSpotlight,
    } from '@/components/awesome-tour/tour';
    import { DemoFrame, StartButton, worldButton } from './ui';
    const $ = parts('styled');
    const tour = createTour({
    id: 'docs-styling',
    steps: [
    {
    id: 'transport',
    target: $('transport'),
    title: 'Same tour',
    description: 'Only class names change between these themes.',
    },
    {
    id: 'beat',
    target: $('sequencer'),
    title: 'Your design system',
    description: 'Style with data-state, data-side and CSS variables.',
    },
    {
    id: 'mixer',
    target: $('mixer'),
    side: 'left',
    title: 'No CSS shipped',
    description: 'Nothing to override, nothing to fight.',
    },
    ],
    });
    /** Each theme is just a different set of Tailwind classes on the same parts. */
    const themes = {
    default: { card: '', overlay: true },
    glass: {
    card: 'border-white/20 bg-popover/60 shadow-2xl backdrop-blur-xl [&_[data-tour-arrow]]:hidden',
    overlay: true,
    },
    brutal: {
    card: 'rounded-none border-2 border-foreground shadow-[6px_6px_0_0_var(--color-foreground)] [&_[data-slot=tour-card-frame]]:rounded-none [&_[data-tour-arrow]]:hidden',
    overlay: true,
    },
    lcd: {
    card: 'rounded-sm border-[#2b3324] bg-[#141a10] font-mono text-[#c6f07c] [&_*]:text-inherit [&_[data-slot=tour-card-frame]]:rounded-sm [&_[data-tour-arrow]]:fill-[#141a10] [&_button]:rounded-sm [&_button]:border [&_button]:border-[#c6f07c]/40 [&_button]:bg-transparent [&_[data-state=active]]:bg-[#c6f07c]',
    overlay: true,
    },
    spotlight: { card: '', overlay: false },
    // Same card, docked to the bottom like a mobile hint (`layout="auto"` does it below 640px).
    sheet: { card: '', overlay: true, layout: 'sheet' },
    } as const;
    type Theme = keyof typeof themes;
    export function StylingDemo() {
    const [theme, setTheme] = useState<Theme>('glass');
    const t = themes[theme];
    return (
    <Tour.Root tour={tour}>
    <DemoFrame
    title="Styling"
    actions={
    <>
    <fieldset className="flex items-center gap-0 rounded-sm border-2 border-ink">
    <legend className="sr-only">Theme</legend>
    {(Object.keys(themes) as Theme[]).map((k) => (
    <button
    type="button"
    key={k}
    aria-pressed={theme === k}
    onClick={() => setTheme(k)}
    className={`${worldButton.secondary} h-8 rounded-none border-0 ${k === 'lcd' ? 'uppercase' : 'capitalize'}`}
    >
    {k}
    </button>
    ))}
    </fieldset>
    <StartButton />
    </>
    }
    >
    <LoopworkApp scope="styled" layout="compact" />
    </DemoFrame>
    <Tour.Portal>
    {t.overlay ? <TourOverlay /> : <TourSpotlight />}
    <TourCard className={t.card} layout={'layout' in t ? t.layout : 'auto'}>
    <TourCardContents />
    </TourCard>
    </Tour.Portal>
    </Tour.Root>
    );
    }

    Data attributes

    Style states without JavaScript:

    Attribute On Values
    data-state Overlay, Spotlight, Content open · closed (during exit animations)
    data-side / data-align Content placed side / alignment after collisions
    data-placement Content anchored · center
    data-step Content current step id
    data-phase Content transitioning · resolving · ready
    data-direction Content forward · backward · jump
    data-target-missing Content present when the step fell back to center
    data-disabled / data-last Prev / Next first step / last step
    data-tour-target highlighted elements present while highlighted
    .tour-card[data-placement='center'] {
    width: 420px; /* centered steps get a roomier card */
    }
    .tour-card[data-direction='backward'] {
    --slide-from: -8px;
    }
    [data-tour-target] {
    position: relative; /* useful for z-index tricks on targets */
    }

    CSS variables

    Variable Set on Meaning
    --tour-overlay-color Overlay Read by the overlay for its fill. Set it.
    --tour-content-transform-origin Content wrapper¹ Origin for scale animations, from the arrow side.
    --tour-content-available-width / -height Content wrapper¹ Space available before colliding.
    --tour-target-width / -height Content wrapper¹ Size of the highlighted area.
    --tour-spotlight-x / -y / -width / -height Spotlight Geometry of the highlighted area.
    --tour-progress Progress 0–1, for progress bars.

    ¹ Set on the positioned wrapper (data-tour-content-wrapper) and inherited by Tour.Content.

    .tour-card {
    max-height: var(--tour-content-available-height);
    transform-origin: var(--tour-content-transform-origin);
    }
    .tour-progress-bar {
    background: linear-gradient(to right, var(--accent) calc(var(--tour-progress) * 100%), #ddd 0);
    }

    Overlay or spotlight

    • Tour.Overlay is an SVG covering the viewport with a cutout around the target (padding, radius). It blocks clicks outside the target.
    • Tour.Spotlight is a plain div sized and positioned over the target — style it as a ring, a glow, or a huge box-shadow that dims the page. Combine it with modal={false} for tours that leave the page usable:
    Declarative · non-modal
    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%
    NonModalDemo.tsx
    import { Tour } from '@awesome-tour/react';
    import { LoopworkApp, parts } from '@loopwork';
    import {
    TourCard,
    TourCardFooter,
    TourCardNext,
    TourCardPrev,
    TourCardTitle,
    TourDots,
    TourSpotlight,
    } from '@/components/awesome-tour/tour';
    import { DemoFrame, StartButton } from './ui';
    const $ = parts('jam');
    /** Inline tour declared in JSX, non-modal: coach marks you read while you keep playing. */
    export function NonModalDemo() {
    return (
    <Tour.Root id="docs-declarative" modal={false}>
    <Tour.Step id="play" target={$('play')} title="Keep it playing">
    <p>These tips don’t block anything. Hit play and keep editing while you read.</p>
    </Tour.Step>
    <Tour.Step id="hats" target={$('row-hat')} title="Hats on the off-beats">
    <p>Add hats on steps 3, 7, 11 and 15 and listen to the groove open up.</p>
    </Tour.Step>
    <Tour.Step id="bass" target={$('knob-bass')} side="left" title="Bring the bass up">
    <p>Around 60% sits under the kick without fighting it.</p>
    </Tour.Step>
    <DemoFrame title="Declarative · non-modal" actions={<StartButton />}>
    <LoopworkApp scope="jam" layout="compact" />
    </DemoFrame>
    <Tour.Portal>
    <TourSpotlight />
    <TourCard size="sm">
    <TourCardTitle />
    <div className="text-muted-foreground">
    <Tour.StepContent />
    </div>
    <TourCardFooter>
    <TourDots />
    <div className="flex gap-1">
    <TourCardPrev />
    <TourCardNext />
    </div>
    </TourCardFooter>
    </TourCard>
    </Tour.Portal>
    </Tour.Root>
    );
    }
    .spotlight {
    border-radius: 10px;
    box-shadow: 0 0 0 2px var(--accent), 0 0 0 9999px rgb(0 0 0 / 0.3);
    transition: all 250ms ease;
    pointer-events: none;
    }

    asChild

    Every part accepts asChild to render your own component instead of the default element, merging props, refs and event handlers:

    <Tour.Next asChild>
    <Button variant="primary">Continue</Button>
    </Tour.Next>

    CSS animations

    Parts that animate (Overlay, Spotlight, Content) stay mounted until their CSS exit animation ends, so keyframes on data-state just work:

    .tour-card[data-state='open'] { animation: in 180ms ease-out; }
    .tour-card[data-state='closed'] { animation: out 120ms ease-in forwards; }

    For spring physics and a spotlight that morphs between targets, see Animation.

    Stacking

    Give the overlay and content a z-index above your app’s chrome:

    [data-tour-overlay] { z-index: 1000; }
    [data-tour-content-wrapper] { z-index: 1001; } /* the positioned wrapper around Tour.Content */

    Or skip the z-index war entirely: <Tour.Portal strategy="top-layer"> renders the tour in the browser’s top layer, above everything — including modal <dialog>s.

    Cutouts

    Tour.Overlay draws one rounded cutout around all of a step’s targets. cutout="each" cuts one hole per target so the page between them stays dimmed, and shape="circle" draws circles:

    <Tour.Overlay cutout="each" shape="circle" padding={8} />

    Morphing between steps

    viewTransition on Tour.Root wraps every step change in the View Transitions API: the card morphs from one target to the next. Style it like any view transition:

    ::view-transition-group(tour-content) {
    animation-duration: 280ms;
    animation-timing-function: cubic-bezier(0.22, 1, 0.36, 1);
    }