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.
Beat A
16 steps · drumsMixer
4 channelsimport { 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.Overlayis an SVG covering the viewport with a cutout around the target (padding,radius). It blocks clicks outside the target.Tour.Spotlightis a plaindivsized and positioned over the target — style it as a ring, a glow, or a hugebox-shadowthat dims the page. Combine it withmodal={false}for tours that leave the page usable:
Beat A
16 steps · drumsMixer
4 channelsimport { 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);}