Skip to content
awesome-tour

Type to search every page.

    BAnnouncementsContents

    Announcements

    Banners, toasts, slideouts and modals for what's new — with the same display rules, triggers, snooze and analytics as tours.

    An announcement is a one-step tour with a presentation. Because it is a tour, it gets display rules (audience, schedule, once, snooze…), triggers, impressions, persistence and analytics without anything new to learn.

    Announcements
    Loopworknight-drive.lwp
    001.1.1

    Mixer

    4 channels
    Drums
    80%
    Bass
    35%
    Keys
    60%
    Vox
    50%

    Bounce

    8 bars · 0:21
    Renders the loop to one file.
    Banners render in place; toasts and modals are portalled. Bounce the loop: the app raises the toast itself.
    AnnouncementDemo.tsx
    import { TourProvider, useTourManager } from '@awesome-tour/react';
    import { createAnnouncement } from '@awesome-tour/react/surfaces';
    import { LoopworkApp, useCreateLoopwork, useLoopwork } from '@loopwork';
    import { BellRing, PanelTop, Sparkles } from 'lucide-react';
    import { useEffect } from 'react';
    import {
    AnnouncementBanner,
    AnnouncementModal,
    AnnouncementToast,
    } from '@/components/awesome-tour/announcement';
    import { DemoFrame, worldButton } from './ui';
    const banner = createAnnouncement({
    id: 'docs-banner',
    title: 'Stems export is here',
    description: 'Bounce one file per channel and finish the mix anywhere.',
    });
    const toast = createAnnouncement({
    id: 'docs-toast',
    variant: 'toast',
    title: 'Bounce finished',
    description: 'night-drive.wav is ready to download.',
    autoDismiss: 6000,
    });
    const modal = createAnnouncement({
    id: 'docs-modal',
    variant: 'modal',
    title: 'Loopwork 2.4: swing per row',
    description: 'Give the hats their own shuffle while the kick stays straight.',
    });
    function Controls() {
    const manager = useTourManager();
    const show = (id: string) => void manager.start(id, { force: true });
    return (
    <>
    <button type="button" className={worldButton.secondary} onClick={() => show('docs-banner')}>
    <PanelTop aria-hidden="true" />
    Banner
    </button>
    <button type="button" className={worldButton.secondary} onClick={() => show('docs-toast')}>
    <BellRing aria-hidden="true" />
    Toast
    </button>
    <button type="button" className={worldButton.primary} onClick={() => show('docs-modal')}>
    <Sparkles aria-hidden="true" />
    Modal
    </button>
    </>
    );
    }
    /** Swing preview for the modal's media slot: hats drift late on the off-beats. */
    function SwingArt() {
    return (
    <div className="grid grid-cols-16 gap-1 bg-muted p-4" aria-hidden="true">
    {Array.from({ length: 16 }, (_, i) => (
    <span
    // biome-ignore lint/suspicious/noArrayIndexKey: fixed grid
    key={i}
    className={`h-10 rounded-sm ${i % 2 ? 'translate-x-1 bg-[var(--chart-1)]' : 'bg-foreground/80'}`}
    />
    ))}
    </div>
    );
    }
    /** The app announces a finished bounce itself: the toast is wired to its event. */
    function BounceToast() {
    const manager = useTourManager();
    const status = useLoopwork((s) => s.export.status);
    useEffect(() => {
    if (status === 'done') void manager.start('docs-toast', { force: true });
    }, [status, manager]);
    return null;
    }
    export function AnnouncementDemo() {
    const app = useCreateLoopwork({ route: 'mix' });
    return (
    <TourProvider tours={[banner, toast, modal]}>
    <DemoFrame
    title="Announcements"
    actions={<Controls />}
    footer="Banners render in place; toasts and modals are portalled. Bounce the loop: the app raises the toast itself."
    >
    <LoopworkApp scope="news" app={app} layout="routed">
    <div className="order-first">
    <AnnouncementBanner announcement={banner} actionLabel="Try it" snooze={60_000} />
    </div>
    <BounceToast />
    </LoopworkApp>
    </DemoFrame>
    <AnnouncementToast announcement={toast} />
    <AnnouncementModal announcement={modal} actionLabel="Open the grid" media={<SwingArt />} />
    </TourProvider>
    );
    }

    Create

    import { createAnnouncement } from '@awesome-tour/react/surfaces';
    export const whatsNew = createAnnouncement({
    id: 'dashboards-2',
    variant: 'modal',
    title: 'Loopwork 2.4: swing per row',
    description: 'Drag widgets anywhere and share a live link.',
    rules: { trigger: { route: '/dashboard' }, schedule: { endsAt: '2027-02-01' } },
    });

    Register it on TourProvider with your tours: <TourProvider tours={[onboarding, whatsNew]}>.

    Variant Role Focus Shares the screen
    banner region never moved ambient — alongside anything
    toast status (polite) never moved ambient
    slideout dialog moved in, Esc closes ambient
    modal dialog (modal) trapped, page inert blocking — queues with tours

    autoDismiss: ms closes it by itself (toasts). It counts as completed.

    Render

    The parts are unstyled and not positioned — put the content where it belongs with CSS (a top strip, a corner, a centered dialog):

    import { Announcement } from '@awesome-tour/react/surfaces';
    <Announcement.Root announcement={whatsNew}>
    <Announcement.Portal>
    <Announcement.Content className="toast">
    <Announcement.Title />
    <Announcement.Description />
    <Announcement.Snooze duration={86_400_000}>Later</Announcement.Snooze>
    <Announcement.Action>Show me</Announcement.Action>
    <Announcement.Dismiss />
    </Announcement.Content>
    </Announcement.Portal>
    </Announcement.Root>
    Part Does
    Root Connects the announcement (and registers it on the provider).
    Content The element: role, focus and Escape follow the variant. data-variant, data-state.
    Title / Description / Body Title, description, and the step’s content.
    Action The call to action. outcome: complete (default), close or none. asChild for links.
    Snooze “Remind me later” — duration in ms (default: a day).
    Dismiss Closes it (counts as dismissed for once).