Communication

Tour

A guided tour: a spotlight on one thing at a time, with a card explaining it.

import { Tour } from 'omaris'

Examples

Basic

A step names its target with a CSS selector, so a tour is data — it can come from a config file or the server. The scrim is one element with a hole cut in it, so the spotlight travels between steps rather than blinking.

The page stays clickable inside the spotlight.

1<script lang="ts">2	import { Avatar, Button, Input, Text, Tour, type TourStep } from 'omaris';34	let open = $state(false);56	const STEPS: TourStep[] = [7		{8			target: '#tour-new',9			title: 'Start here',10			content: 'Every order begins with this button — the only filled thing on the page.',11			side: 'bottom',12			align: 'start'13		},14		{15			target: '#tour-search',16			title: 'Find anything',17			content: 'Search matches an order number, a phone number or a customer name.',18			side: 'bottom'19		},20		{21			target: '#tour-avatar',22			title: 'Your account',23			content: 'Settings, theme and sign-out live behind your avatar.',24			side: 'left',25			round: true,26			padding: 627		},28		{29			title: 'That is the whole tour',30			content: 'A step with no target is centred — which is how a tour opens and closes.'31		}32	];33</script>3435<div class="flex w-full flex-col gap-4">36	<div class="flex items-center gap-3 rounded-shape-lg border border-border p-3">37		<Button id="tour-new" size="sm">New order</Button>38		<Input id="tour-search" placeholder="Search orders…" class="max-w-56 flex-1" />39		<Avatar id="tour-avatar" name="Omer Chetin" class="ms-auto" />40	</div>4142	<div class="flex items-center gap-3">43		<Button variant="tonal" size="sm" onclick={() => (open = true)}>Take the tour</Button>44		<Text variant="label-sm" tone="muted">The page stays clickable inside the spotlight.</Text>45	</div>46</div>4748<Tour bind:open steps={STEPS} />

Steps that change the page

A step's before runs before its target is looked for — switch a tab, open a menu, await a fetch — so a tour can walk across parts of the UI that are not on screen yet. A step whose target never appears is skipped: the third step here points at #tour-missing, which does not exist, so Next from the second step lands on the fourth and Back walks past it the other way.

14 orders today.

step 1

1<script lang="ts">2	import { Button, Tab, TabList, Tabs, Text, Tour, type TourStep } from 'omaris';34	let open = $state(false);5	let index = $state(0);6	let tab = $state('orders');78	const STEPS: TourStep[] = [9		{10			target: '#tour-tabs',11			title: 'Two views',12			content: 'Orders and menu live behind these tabs.',13			side: 'bottom'14		},15		{16			target: '#tour-menu-panel',17			title: 'The menu',18			content: 'The tour switched the tab for you before pointing here.',19			side: 'top',20			before: () => {21				tab = 'menu';22			}23		},24		{25			target: '#tour-missing',26			title: 'Never rendered',27			content: 'You will not see this — the target is not on the page, so the step is skipped.'28		},29		{30			title: 'Still here',31			content:32				'A step with no target at all is not skipped — it is centred. The one before this was.'33		}34	];35</script>3637<div class="flex w-full flex-col gap-4">38	<div id="tour-tabs" class="rounded-shape-lg border border-border p-3">39		<Tabs bind:value={tab}>40			<TabList label="Sections">41				<Tab value="orders" label="Orders" />42				<Tab value="menu" label="Menu" />43			</TabList>44		</Tabs>4546		{#if tab === 'orders'}47			<Text variant="body-sm" tone="muted" class="mt-3 block">14 orders today.</Text>48		{:else}49			<Text id="tour-menu-panel" variant="body-sm" tone="muted" class="mt-3 block">50				38 items across 6 categories.51			</Text>52		{/if}53	</div>5455	<div class="flex items-center gap-3">56		<Button57			variant="tonal"58			size="sm"59			onclick={() => {60				tab = 'orders';61				index = 0;62				open = true;63			}}64		>65			Start66		</Button>67		<Text variant="label-sm" tone="muted">step {index + 1}</Text>68	</div>69</div>7071<Tour bind:open bind:index steps={STEPS} />

Across pages

A flow that lives on three pages. Each step names the path it belongs to and the tour navigates there itself — navigate: goto in a SvelteKit app, a local variable in this demo. The state lives in createTour rather than in the component, so a navigation that unmounts the page does not end the tour; mount <Tour /> in +layout.svelte and it survives every step.

now on /orders

14 open today.

1<script lang="ts">2	import { Button, Card, Text, Tour, createTour, type TourStep } from 'omaris';34	/** Stands in for `$page.url.pathname`; `goto` writes it in a real app. */5	let path = $state('/orders');67	const PAGES = [8		{ path: '/orders', label: 'Orders' },9		{ path: '/menu', label: 'Menu' },10		{ path: '/settings', label: 'Settings' }11	];1213	const STEPS: TourStep[] = [14		{15			path: '/orders',16			target: '#np-new',17			title: 'Take the order',18			content: 'Everything starts here. One order, one screen.',19			side: 'bottom',20			align: 'start'21		},22		{23			path: '/menu',24			target: '#np-item',25			title: 'Then the menu',26			content: 'The tour changed page for you and waited for this to render before pointing at it.',27			side: 'bottom',28			align: 'start'29		},30		{31			path: '/settings',32			target: '#np-hours',33			title: 'And the hours',34			content: 'Back navigates too — every step knows the page it belongs to.',35			side: 'top',36			align: 'start'37		},38		{39			title: 'Three pages, one tour',40			content: 'Add an `id` to the controller and it survives a real page load as well.'41		}42	];4344	const tour = createTour(STEPS, {45		navigate: (to) => {46			path = to;47		}48	});49</script>5051<div class="flex w-full flex-col gap-4">52	<div class="flex items-center gap-3">53		<Button variant="tonal" size="sm" onclick={() => tour.start()}>Show me around</Button>54		<Text variant="label-sm" tone="muted">now on <code>{path}</code></Text>55	</div>5657	<div class="overflow-hidden rounded-shape-lg border border-border">58		<nav class="flex gap-1 border-b border-border bg-surface-container-low p-2">59			{#each PAGES as page (page.path)}60				<Button61					variant={path === page.path ? 'tonal' : 'text'}62					size="xs"63					onclick={() => (path = page.path)}64				>65					{page.label}66				</Button>67			{/each}68		</nav>6970		<div class="p-4">71			{#if path === '/orders'}72				<div class="flex items-center gap-3">73					<Button id="np-new" size="sm">New order</Button>74					<Text variant="body-sm" tone="muted">14 open today.</Text>75				</div>76			{:else if path === '/menu'}77				<Card id="np-item" class="w-fit px-4 py-3">78					<Text variant="title-sm">Lamb quzi</Text>79					<Text variant="body-sm" tone="muted">18,000 IQD · 6 in stock</Text>80				</Card>81			{:else}82				<div id="np-hours" class="w-fit rounded-shape-md bg-surface-container px-4 py-3">83					<Text variant="title-sm">Opening hours</Text>84					<Text variant="body-sm" tone="muted">11 AM – 11 PM, every day but Friday.</Text>85				</div>86			{/if}87		</div>88	</div>89</div>9091<Tour {tour} />

Nowhere to put the card

The case a phone hits constantly: a target with less room beside it than the card wants. The card is never slid over the spotlight to fit — it takes the taller of the two bands, caps itself to it and scrolls what is left over, so the thing being explained stays visible. Narrow this window, or open it on a phone, and the first step does the same thing to a small target.

Kitchen display

Tall enough that a card at its natural height fits neither above nor below it.

Four on shift. Hana is closing tonight.

1<script lang="ts">2	import { Button, Text, Tour, type TourStep } from 'omaris';34	let open = $state(false);56	const STEPS: TourStep[] = [7		{8			target: '#nc-panel',9			title: 'A target with no room beside it',10			content:11				'This panel is most of the screen, so neither side can hold the card at its natural height. The card is capped to the band it has and scrolls inside itself instead — the alternative, sliding it back inside the viewport, would put it over the very thing this step is about. Keep reading: there is more here than fits, which is the point.',12			side: 'bottom',13			padding: 614		},15		{16			target: '#nc-footer',17			title: 'And back to normal',18			content: 'A target with room beside it gets a card at its full height, as usual.',19			side: 'top'20		}21	];22</script>2324<div class="flex w-full flex-col gap-3">25	<Button variant="tonal" size="sm" class="w-fit" onclick={() => (open = true)}>26		Point at the big one27	</Button>2829	<div30		id="nc-panel"31		class="flex h-[58vh] flex-col justify-between rounded-shape-lg border border-border bg-surface-container-low p-4"32	>33		<Text variant="title-sm">Kitchen display</Text>34		<Text variant="body-sm" tone="muted">35			Tall enough that a card at its natural height fits neither above nor below it.36		</Text>37	</div>3839	<Text id="nc-footer" variant="label-sm" tone="muted">Four on shift. Hana is closing tonight.</Text40	>41</div>4243<Tour bind:open steps={STEPS} />

Long page

Targets far apart in a scrolling panel. Each step scrolls its target into view first, then the hole and the card glide to it — the card's position and height are transitioned, so a longer explanation grows the card rather than snapping it. Scroll the panel yourself mid-tour and the spotlight keeps up without lagging.

Four sections, a screen apart.

Sales

1,240,000 IQD today, up 8% on last week.

2 out of stock

38 items across 6 categories. Two are out of stock.

Staff

Four on shift. Hana is closing tonight.

Reviews

4.7 across 212 reviews this month.

1<script lang="ts">2	import { Badge, Button, Card, Text, Tour, type TourStep } from 'omaris';34	let open = $state(false);56	const SECTIONS = [7		{ id: 'sales', title: 'Sales', line: '1,240,000 IQD today, up 8% on last week.' },8		{ id: 'menu', title: 'Menu', line: '38 items across 6 categories. Two are out of stock.' },9		{ id: 'staff', title: 'Staff', line: 'Four on shift. Hana is closing tonight.' },10		{ id: 'reviews', title: 'Reviews', line: '4.7 across 212 reviews this month.' }11	];1213	const STEPS: TourStep[] = [14		{15			target: '#tour-lp-sales',16			title: 'Sales, first',17			content: 'The top card is the one you check every morning.',18			side: 'bottom',19			align: 'start'20		},21		{22			target: '#tour-lp-stock',23			title: 'Out of stock',24			content:25				'The badge counts items that are hidden from the menu. Tap a section to restock; the tour waits, and the page underneath is still live inside the spotlight while it does.',26			side: 'left'27		},28		{29			target: '#tour-lp-reviews',30			title: 'Reviews, last',31			content: 'Far down the page — the tour scrolled here for you, and the card followed.',32			side: 'top'33		},34		{35			title: 'That is the whole page',36			content: 'A centred step closes the hole in place rather than swapping it out.'37		}38	];39</script>4041<div class="flex w-full flex-col gap-3">42	<div class="flex items-center gap-3">43		<Button variant="tonal" size="sm" onclick={() => (open = true)}>Walk the page</Button>44		<Text variant="label-sm" tone="muted">Four sections, a screen apart.</Text>45	</div>4647	<!-- svelte-ignore a11y_no_noninteractive_tabindex -->48	<div49		class="flex h-80 flex-col gap-48 overflow-y-auto rounded-shape-lg border border-border p-4"50		tabindex="0"51		role="group"52		aria-label="Page"53	>54		{#each SECTIONS as section (section.id)}55			<Card id="tour-lp-{section.id}" class="shrink-0 px-4 py-3">56				<div class="flex items-center gap-2">57					<Text variant="title-sm">{section.title}</Text>58					{#if section.id === 'menu'}59						<Badge id="tour-lp-stock" tone="warning" class="ms-auto">2 out of stock</Badge>60					{/if}61				</div>62				<Text variant="body-sm" tone="muted">{section.line}</Text>63			</Card>64		{/each}65	</div>66</div>6768<Tour bind:open steps={STEPS} />

Remembering where you were

Give the controller an id and the step you are on is written to sessionStorage, so a tour that is interrupted by a real page load — a link, a form post, a hard refresh — comes back on the same step instead of starting over. Start this one, stop halfway, and reload the page. once does the opposite bookkeeping: a first-run tour that start() only ever opens once, until reset().

Revenue today

1,240,000 IQD

not started

1<script lang="ts">2	import { Button, Text, Tour, createTour, type TourStep } from 'omaris';34	const STEPS: TourStep[] = [5		{6			target: '#nr-total',7			title: 'Today',8			content: 'Reload the page here and the tour comes back on this step.',9			side: 'bottom',10			align: 'start'11		},12		{13			target: '#nr-export',14			title: 'Export',15			content: 'Takes the rows you are looking at, not the whole table.',16			side: 'bottom'17		},18		{19			title: 'Finished',20			content: 'Finishing or skipping clears what was remembered.'21		}22	];2324	const tour = createTour(STEPS, { id: 'docs-tour-resume' });25</script>2627<div class="flex w-full flex-col gap-4">28	<div class="flex flex-wrap items-center gap-3 rounded-shape-lg border border-border p-3">29		<div id="nr-total">30			<Text variant="label-sm" tone="muted">Revenue today</Text>31			<Text variant="title-md" tabular>1,240,000 IQD</Text>32		</div>33		<Button id="nr-export" variant="outlined" size="sm" class="ms-auto">Export</Button>34	</div>3536	<div class="flex flex-wrap items-center gap-3">37		<Button variant="tonal" size="sm" onclick={() => tour.start()}>Start</Button>38		<Button variant="text" size="sm" onclick={() => tour.reset()}>Forget</Button>39		<Text variant="label-sm" tone="muted">40			{tour.open ? `on step ${tour.index + 1}` : tour.done ? 'seen' : 'not started'}41		</Text>42	</div>43</div>4445<Tour {tour} />

Overridden

scrim="strong" darkens the page further, dots={false} drops the progress row, labels rewrites the buttons, and classes reaches the card and the spotlight itself — a wider card with a tinted ring around the hole.

Revenue today

1,240,000 IQD

1<script lang="ts">2	import { Button, Card, Text, Tour, type TourStep } from 'omaris';34	let open = $state(false);56	const STEPS: TourStep[] = [7		{8			target: '#tour-o-total',9			title: 'Today so far',10			content: 'Updated as orders come in — no refresh needed.',11			side: 'right',12			padding: 1213		},14		{15			target: '#tour-o-export',16			title: 'Take it with you',17			content: 'Every table on the dashboard exports the rows you are looking at.',18			side: 'top'19		}20	];21</script>2223<div class="flex w-full flex-col gap-4">24	<div class="flex flex-wrap items-center gap-3">25		<Card id="tour-o-total" class="px-4 py-3">26			<Text variant="label-sm" tone="muted">Revenue today</Text>27			<Text variant="headline-sm">1,240,000 IQD</Text>28		</Card>29		<Button id="tour-o-export" variant="outlined" size="sm">Export CSV</Button>30	</div>3132	<Button variant="tonal" size="sm" class="self-start" onclick={() => (open = true)}>33		Show me around34	</Button>35</div>3637<Tour38	bind:open39	steps={STEPS}40	scrim="strong"41	dots={false}42	width={380}43	padding={10}44	labels={{ next: 'Keep going', back: 'Back a step', done: 'Got it', skip: 'Not now' }}45	classes={{46		spotlight: 'rounded-shape-lg',47		card: 'rounded-shape-xl shadow-4',48		title: 'text-title-lg'49	}}50/>

When to use it

Use it for

A first run through a dashboard: three to six steps pointing at real things like the new-order button, the filter bar, the settings menu. createTour(steps, { id, once: true }) runs it once per browser and resumes after a reload.
A "what's new" walk started from a button or ?tour=1 in the URL. Call tour.start() from anywhere, restart() to run it again.
A flow across pages. Put a path on the steps that live elsewhere, pass navigate: goto, and mount <Tour {tour} /> in +layout.svelte so navigation does not unmount it.
Steps whose target is not on screen yet. Open a menu, switch a tab or await a fetch in the step's before.

Not for

Explaining one control on hover → Tooltip. A tour is a sequence.
Documentation, more than two sentences a step → a docs page, linked from a rich Tooltip or an Alert with an action.
An announcement with nothing to point at, like "Welcome to v2" → Dialog. One centred, targetless step can open a tour but should not be the whole tour.
Walking someone through a form → the form itself, with required fields and supportingText.
A screen with nothing on it → Empty. With no targets every step is skipped and the tour finishes at once.

Do

Select targets by an id or a data-tour attribute you own. A step that names a design-system class breaks on the next refactor.
Keep a step to a title and a sentence or two. The card fits the room beside the target and scrolls; on a phone that room is small.
Let a step ask for a real click when it helps. The page stays live inside the spotlight; use the next step's before to put things back.
Set round on a step pointing at an avatar or icon button, and padding where the target's own padding is thin.
Leave dismissible on, and watch onskip to learn where people leave.

Don't

Run it on every visit. Give it an id and once, and a "Take the tour" button for the rest.
Put more than about eight steps in one tour. Split it by page and start the second from the first's onfinish.
Mount <Tour /> inside the page a step navigates away from. It goes with the page.
Point at a target inside an overflow: hidden box that clips it. The hole is clipped to what is visible.

Pairs with Tooltip Dialog Empty App Shell Button

Quick reference

scrim

soft (default)
strong

How dark the page goes behind the spotlight.

API

Tour

A guided tour: a spotlight on one thing at a time, with a card explaining it.

The scrim is a single element with a hole cut in it — one box-shadow with an enormous spread — rather than four rectangles arranged around the target. That matters because the hole then animates: moving between steps slides and resizes one box with MD3 easing, so the spotlight travels across the page instead of blinking from place to place. The card travels with it — its position and height are transitioned, and the copy inside fades out, swaps, and fades back in once the card has settled — so a step change reads as one movement, not a cut.

A step names its target with a CSS selector, so a tour is data — it can come from a config file, a feature flag or the server, and it does not need a ref threaded through every component it points at. A step whose target isn't on the page is skipped rather than left pointing at nothing: Next walks forward past it, Back walks backward past it, and a tour with nothing left to point at finishes. A step with no target is different — it is centred, which is how a tour opens and closes.

The card never covers the hole. When a side is too short for it — which on a phone is most sides — the card shrinks into that side and scrolls inside itself rather than sliding over the thing being pointed at, and the step scrolls its target near the top of the screen instead of the middle so there is a side to put it on at all.

The page underneath stays interactive inside the spotlight, so a tour can ask you to actually click the thing. Everywhere else, a click on the scrim ends the tour when it is dismissible.

A tour that crosses pages is the same thing with a path on the steps that live elsewhere, and a createTour controller holding the state so it survives the navigation. Mount that one in +layout.svelte, not in a page — a tour that navigates away from the component rendering it takes the component with it.

import { Tour } from 'omaris'

<Tour bind:open steps={[  { target: '#new-order', title: 'Start here', content: 'Every order begins with this button.' }]} />

const tour = createTour(STEPS, { id: 'onboarding', navigate: goto });

<Tour {tour} />

Parts

Every element this renders is reachable from outside. Pass Tailwind for one part as classes={{ part: '…' }}; class covers the root and is merged last, so it always wins.

scrim: The click-catcher behind the card when the tour is dismissible: a transparent sheet with the spotlight cut out of it, so the page stays clickable inside the hole and a click anywhere else ends the tour.
spotlight: The dark layer, with the spotlight cut out of it.
card: The explaining card. Positioned with translate, so it glides.
scroller: Holds the card's copy when there is less room beside the target than the card wants — the card is capped to the space it has and this scrolls, so it is never resized over the spotlight.
body: What gets measured: everything inside the card.
header: No description in the source yet.
title: No description in the source yet.
counter: 2 / 5.
progress: The slim track under the header.
progressBar: How much of the tour is done.
content: No description in the source yet.
footer: Dots, then the buttons.
dots: No description in the source yet.
dot: No description in the source yet.
actions: No description in the source yet.
ghost: Back, and the skip link — text buttons.
next: Next / Done — the filled button.

Props

steps

TourStep[]

The steps. Omit it when tour is given — the controller holds them.

tour

TourController

A controller from createTour, holding steps, open and index outside the component. Use one when the tour crosses pages: the state lives in the controller (and, with an id, in storage), so a real navigation resumes the tour where it was instead of ending it.

open bindable

Defaults to false

boolean

Whether the tour is running. Bindable. Ignored when tour is given.

index bindable

Defaults to 0

number

Which step, from 0. Bindable. Setting it to a step whose target is missing lands on the next one that resolves. Ignored when tour is given.

scrim

Defaults to 'soft'

TourScrim

soft
strong

padding

Defaults to 8

number

Default breathing room around a target, in px.

width

Defaults to 320

number | string

Card width. A number is px, a string any CSS length.

dismissible

Defaults to true

boolean

Let Escape and a click on the scrim end the tour.

dots

Defaults to true

boolean

Show the progress dots.

progress

Defaults to true

boolean

Show the slim progress bar under the header.

labels

{ next?: string; back?: string; done?: string; skip?: string }

Button text.

scrollIntoView

Defaults to true

boolean

Bring each target into view before pointing at it.

wait

Defaults to 0

number

How long to wait, in ms, for a step's target to appear before the step is treated as missing and skipped. 0 looks once. Raise it for targets that arrive with a fetch; a step with a path waits anyway.

navigate

(path: string) => void | Promise<void>

How a step's path is followed. goto from $app/navigation in a SvelteKit app; a full page load otherwise, which a tour with an id survives.

onfinish

() => void

onskip

(index: number) => void

onstep

(index: number, step: TourStep) => void

Fires once per step shown, after its target has been found.

class

string

classes

TourClasses