Skip to content
awesome-tour

Type to search every page.

    DTourContents

    Tour

    A styled product tour — overlay, spotlight and a composable card built on the Tour primitives.

    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>
    );
    }

    Installation

    Terminal window
    pnpm dlx shadcn@latest add @awesome-tour/tour
    Terminal window
    npx shadcn@latest add @awesome-tour/tour

    Usage

    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:

    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>
    );
    }

    Source

    components/awesome-tour/tour.tsx
    '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,
    };