Tour
A styled product tour — overlay, spotlight and a composable card built on the Tour primitives.
Loopworknight-drive.lwp
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
Drums
Beat A
Beat B
Bass
Sub line
Keys
Rhodes
Vox
Hook (dry)
Beat A
16 steps · drumsKick
Snare
Hat
Clap
Mixer
4 channelsDrums
80%
Bass
35%
Keys
60%
Vox
50%
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> );}Installation
pnpm dlx shadcn@latest add @awesome-tour/tournpx shadcn@latest add @awesome-tour/tourUsage
TourPopover is the whole UI in one component — put it inside Tour.Root:
import { createTour, Tour } from '@awesome-tour/react';import { TourPopover } from '@/components/awesome-tour/tour';
const tour = createTour({ id: 'onboarding', steps: [/* … */] });
export function Onboarding() { return ( <Tour.Root tour={tour}> <Tour.Trigger>Start tour</Tour.Trigger> <TourPopover /> </Tour.Root> );}| Prop | Type | Default | |
|---|---|---|---|
overlay |
boolean |
true |
Dim the page around the target. |
progress |
boolean |
true |
“Step 2 of 5” header with a progress bar. |
dots |
boolean |
false |
Clickable step dots in the footer. |
skip |
boolean |
false |
A “Skip tour” link in the footer. |
size |
'sm' | 'default' | 'lg' |
'default' |
Card width and spacing. |
children |
ReactNode |
Extra content under every step. |
…plus every Tour.Content prop (side, align, sideOffset…).
Composition
Need a different layout? Compose the parts — they’re thin, styled wrappers over the primitives:
<Tour.Portal> <TourSpotlight /> <TourCard size="sm"> <TourCardMedia> <img src="/feature.png" alt="" /> </TourCardMedia> <TourCardTitle /> <TourCardDescription /> <TourCardFooter> <TourDots /> <TourCardNext finish="Got it" /> </TourCardFooter> </TourCard></Tour.Portal>| Part | Wraps |
|---|---|
TourOverlay · TourSpotlight |
Tour.Overlay · Tour.Spotlight |
TourCard (+ tourCardVariants) |
Tour.Content + Tour.Arrow |
TourCardHeader · TourCardFooter · TourCardMedia |
layout |
TourCardProgress |
Tour.Progress |
TourCardTitle · TourCardDescription · TourCardBody |
Tour.Title · Tour.Description · Tour.StepContent |
TourCardPrev · TourCardNext · TourCardSkip · TourCardClose |
Tour.Prev · Tour.Next · Tour.Skip · Tour.Close |
TourDots |
Tour.Indicators |
Restyling
It’s your code — but plain classNames go a long way too:
Loopworknight-drive.lwp
Beat A
16 steps · drumsKick
Snare
Hat
Clap
Mixer
4 channelsDrums
80%
Bass
35%
Keys
60%
Vox
50%
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> );}Source
'use client';
import { Tour, type TourContentProps, type TourIndicatorsProps, type TourOverlayProps, type TourSpotlightProps, useTour, useTourMessages, useTourState,} from '@awesome-tour/react';import { cva, type VariantProps } from 'class-variance-authority';import { ArrowLeft, ArrowRight, Check, X } from 'lucide-react';import type * as React from 'react';import { Button } from '@/components/ui/button';import { cn } from '@/lib/utils';
/* ------------------------------------------------------------------------------------------------- * Layers * -----------------------------------------------------------------------------------------------*/
/** Dims the page with a rounded cutout around the target. Color: `--tour-overlay-color`. */function TourOverlay({ className, padding = 6, radius = 10, ...props }: TourOverlayProps) { return ( <Tour.Overlay data-slot="tour-overlay" padding={padding} radius={radius} className={cn( 'z-50 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:animate-in data-[state=open]:fade-in-0', className, )} {...props} /> );}
/** A ring around the target — use instead of (or on top of) the overlay for non-modal tours. */function TourSpotlight({ className, padding = 6, ...props }: TourSpotlightProps) { return ( <Tour.Spotlight data-slot="tour-spotlight" padding={padding} className={cn( 'z-50 rounded-lg ring-2 ring-primary ring-offset-2 ring-offset-background transition-all duration-300 ease-out', 'shadow-[0_0_0_6px_color-mix(in_oklab,var(--color-primary)_20%,transparent)]', 'data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:animate-in data-[state=open]:fade-in-0', className, )} {...props} /> );}
/* ------------------------------------------------------------------------------------------------- * Card * -----------------------------------------------------------------------------------------------*/
const tourCardVariants = cva( [ 'relative rounded-xl border bg-popover text-popover-foreground shadow-xl outline-hidden origin-(--tour-content-transform-origin)', // Docked to the bottom on small screens (`layout="auto"`): full width, square bottom edge. 'data-[layout=sheet]:w-full data-[layout=sheet]:rounded-b-none data-[layout=sheet]:border-x-0 data-[layout=sheet]:border-b-0 data-[layout=sheet]:pb-[env(safe-area-inset-bottom)]', ], { variants: { size: { default: 'w-[min(22rem,calc(100vw-2rem))] text-sm', sm: 'w-[min(18rem,calc(100vw-2rem))] text-sm', lg: 'w-[min(28rem,calc(100vw-2rem))] text-sm', }, animated: { true: [ 'data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95', 'data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95', 'data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2', 'data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2', 'data-[layout=sheet]:slide-in-from-bottom-4 data-[layout=sheet]:zoom-in-100', ], false: '', }, }, defaultVariants: { size: 'default', animated: true }, },);
const tourCardInner = { default: 'gap-3 p-5 [--tour-card-padding:calc(var(--spacing)*5)]', sm: 'gap-2 p-4 [--tour-card-padding:calc(var(--spacing)*4)]', lg: 'gap-4 p-6 [--tour-card-padding:calc(var(--spacing)*6)]',} as const;
export interface TourCardProps extends TourContentProps, VariantProps<typeof tourCardVariants> { /** Render the pointer arrow. Default: true. */ arrow?: boolean;}
/** The positioned dialog. Compose it with the `TourCard*` parts, or use `<TourPopover />`. */function TourCard({ className, size, animated, arrow = true, sideOffset = 12, collisionPadding = 16, layout = 'auto', children, ...props}: TourCardProps) { return ( <Tour.Content data-slot="tour-card" layout={layout} sideOffset={sideOffset} collisionPadding={collisionPadding} className={cn(tourCardVariants({ size, animated }), className)} {...props} > <TourCardFrame size={size} arrow={arrow}> {children} </TourCardFrame> </Tour.Content> );}
/** * The card's inside: arrow + a padded column that scrolls within the available height (so the * arrow, outside the box, is never clipped). Use it inside custom contents such as `MotionContent`. */function TourCardFrame({ size, arrow = true, className, children,}: { size?: TourCardProps['size']; arrow?: boolean; className?: string; children?: React.ReactNode;}) { return ( <> {arrow && <TourCardArrow />} <div data-slot="tour-card-frame" className={cn( 'flex max-h-(--tour-content-available-height) flex-col overflow-y-auto rounded-[inherit]', tourCardInner[size ?? 'default'], className, )} > {children} </div> </> );}
function TourCardArrow({ className }: { className?: string }) { return ( <Tour.Arrow data-slot="tour-card-arrow" width={16} height={8} className={cn('text-popover drop-shadow-[0_1px_0_var(--color-border)]', className)} /> );}
function TourCardHeader({ className, ...props }: React.ComponentProps<'div'>) { return ( <div data-slot="tour-card-header" className={cn('flex items-center justify-between gap-3', className)} {...props} /> );}
/** A "Preview" pill on drafts opened with `?tour-preview=` (nothing is saved or tracked). */function TourCardPreviewBadge({ className, children = 'Preview',}: { className?: string; children?: React.ReactNode;}) { const { tour } = useTour(); if (!tour.preview) return null; return ( <span data-slot="tour-card-preview" className={cn( 'rounded-full border border-dashed px-2 py-0.5 text-[11px] font-medium text-muted-foreground', className, )} > {children} </span> );}
/** "Step 2 of 5" with a thin progress bar. Pass a render function to customize the label. */function TourCardProgress({ className, label,}: { className?: string; /** Default: the `stepOf` message ("Step 2 of 5", translatable via `messages`). */ label?: (current: number, total: number) => React.ReactNode;}) { const { stepOf } = useTourMessages(); const format = label ?? stepOf; return ( <Tour.Progress data-slot="tour-card-progress" className={cn('flex min-w-0 flex-1 flex-col gap-1.5', className)} > {({ current, total }) => ( <> <span className="text-xs font-medium text-muted-foreground tabular-nums"> {format(current, total)} </span> <span aria-hidden="true" className="h-1 w-full overflow-hidden rounded-full bg-muted"> <span className="block h-full w-[calc(var(--tour-progress)*100%)] rounded-full bg-primary transition-[width] duration-300 ease-out" /> </span> </> )} </Tour.Progress> );}
function TourCardClose({ className, label,}: { className?: string; /** Default: the `closeTour` message. */ label?: string;}) { const { closeTour } = useTourMessages(); return ( <Tour.Close asChild> <Button data-slot="tour-card-close" variant="ghost" size="icon-sm" aria-label={label ?? closeTour} className={cn('-mt-1 -mr-2 shrink-0 text-muted-foreground', className)} > <X /> </Button> </Tour.Close> );}
function TourCardMedia({ className, ...props }: React.ComponentProps<'div'>) { return ( <div data-slot="tour-card-media" className={cn( '-mx-(--tour-card-padding) -mt-(--tour-card-padding) mb-1 overflow-hidden rounded-t-[inherit] border-b bg-muted [&_img]:w-full [&_video]:w-full', className, )} {...props} /> );}
function TourCardTitle({ className, ...props }: React.ComponentProps<typeof Tour.Title>) { return ( <Tour.Title data-slot="tour-card-title" className={cn('text-base leading-snug font-semibold tracking-tight', className)} {...props} /> );}
function TourCardDescription({ className, ...props}: React.ComponentProps<typeof Tour.Description>) { return ( <Tour.Description data-slot="tour-card-description" className={cn('leading-relaxed text-muted-foreground', className)} {...props} /> );}
function TourCardBody({ className, children }: { className?: string; children?: React.ReactNode }) { return ( <div data-slot="tour-card-body" className={cn('text-muted-foreground empty:hidden', className)}> <Tour.StepContent /> {children} </div> );}
function TourCardFooter({ className, ...props }: React.ComponentProps<'div'>) { return ( <div data-slot="tour-card-footer" className={cn('mt-1 flex items-center justify-between gap-2', className)} {...props} /> );}
function TourCardPrev({ className, children = 'Back',}: { className?: string; children?: React.ReactNode;}) { return ( <Tour.Prev asChild> <Button data-slot="tour-card-prev" variant="ghost" size="sm" className={cn('data-disabled:invisible', className)} > <ArrowLeft /> {children} </Button> </Tour.Prev> );}
/** "Next", or "Finish" on the last visible step. */function TourCardNext({ className, children = 'Next', finish = 'Finish',}: { className?: string; children?: React.ReactNode; finish?: React.ReactNode;}) { const isLast = useTourState((s) => s.progress.current >= s.progress.total); return ( <Tour.Next asChild> <Button data-slot="tour-card-next" size="sm" className={className}> {isLast ? ( <> {finish} <Check /> </> ) : ( <> {children} <ArrowRight /> </> )} </Button> </Tour.Next> );}
function TourCardSkip({ className, children = 'Skip tour',}: { className?: string; children?: React.ReactNode;}) { return ( <Tour.Skip asChild> <Button data-slot="tour-card-skip" variant="link" size="sm" className={cn('px-0 text-muted-foreground', className)} > {children} </Button> </Tour.Skip> );}
/** Clickable step dots. */function TourDots({ className, ...props }: TourIndicatorsProps) { return ( <Tour.Indicators data-slot="tour-dots" className={cn( 'flex items-center gap-1.5', '[&>button]:size-2 [&>button]:cursor-pointer [&>button]:rounded-full [&>button]:bg-muted-foreground/30 [&>button]:transition-all [&>button]:duration-300', '[&>button:hover]:bg-muted-foreground/60 [&>button:focus-visible]:outline-2 [&>button:focus-visible]:outline-offset-2 [&>button:focus-visible]:outline-ring', '[&>button[data-state=active]]:w-5 [&>button[data-state=active]]:bg-primary [&>button[data-state=complete]]:bg-primary/50', className, )} {...props} /> );}
/* ------------------------------------------------------------------------------------------------- * Batteries included * -----------------------------------------------------------------------------------------------*/
export interface TourPopoverProps extends Omit<TourCardProps, 'children'> { /** Dim the page around the target. Default: true. */ overlay?: boolean; /** Show the progress header. Default: true. */ progress?: boolean; /** Show step dots in the footer instead of the skip link. Default: false. */ dots?: boolean; /** Show a "Skip tour" link in the footer. Default: false. */ skip?: boolean; /** Extra content rendered under the step content (e.g. step-specific actions). */ children?: React.ReactNode;}
export interface TourCardContentsProps { progress?: boolean; dots?: boolean; skip?: boolean; children?: React.ReactNode;}
/** The standard layout: progress + close, title, description, step content, navigation. */function TourCardContents({ progress = true, dots = false, skip = false, children,}: TourCardContentsProps) { return ( <> <TourCardHeader> {progress ? <TourCardProgress /> : <span />} <span className="flex items-center gap-1"> <TourCardPreviewBadge /> <TourCardClose /> </span> </TourCardHeader> <TourCardTitle /> <TourCardDescription /> <TourCardBody>{children}</TourCardBody> <TourCardFooter> {dots ? <TourDots /> : skip ? <TourCardSkip /> : <TourCardPrev />} <div className="flex items-center gap-1"> {(dots || skip) && <TourCardPrev />} <TourCardNext /> </div> </TourCardFooter> </> );}
/** A complete tour UI: overlay + card with progress, title, description, content and navigation. */function TourPopover({ overlay = true, progress = true, dots = false, skip = false, children, ...props}: TourPopoverProps) { return ( <Tour.Portal> {overlay && <TourOverlay />} <TourCard {...props}> <TourCardContents progress={progress} dots={dots} skip={skip}> {children} </TourCardContents> </TourCard> </Tour.Portal> );}
export { TourCard, TourCardArrow, TourCardBody, TourCardClose, TourCardContents, TourCardDescription, TourCardFooter, TourCardFrame, TourCardHeader, TourCardMedia, TourCardNext, TourCardPrev, TourCardPreviewBadge, TourCardProgress, TourCardSkip, TourCardTitle, TourDots, TourOverlay, TourPopover, TourSpotlight, tourCardVariants,};