svelte-tourlight

Product tours for Svelte 5: spotlight, multi-page, accessible, and defined as JSON.

Live demo and docs →

Install

npm i svelte-tourlight
# or
pnpm add svelte-tourlight

npmjs.com/package/svelte-tourlight · peer: svelte@^5 · runtime dependency: @floating-ui/dom

Quickstart

<!-- src/routes/+layout.svelte -->
<script lang="ts">
	import { goto } from '$app/navigation';
	import { SpotlightProvider, SpotlightTour } from 'svelte-tourlight';
	let { children } = $props();

	const steps = [
		{ id: 'hi', title: 'Welcome', content: 'A centered step.' },
		{ id: 'search', target: '[data-tour="search"]', title: 'Search', content: 'Find anything.' },
		{
			id: 'new',
			target: '[data-tour="new"]',
			title: 'Create',
			content: 'Click it.',
			advanceOn: { event: 'click' }
		}
	];
</script>

<SpotlightProvider theme="auto" persist navigate={(p) => goto(p)}>
	<SpotlightTour id="onboarding" {steps} />
	{@render children()}
</SpotlightProvider>

Start it from any component with useSpotlight().start('onboarding'). The Getting started guide covers base paths, persistence and the footer snippet.

Features

• Spotlight cutout that tracks scroll, resize and re-renders
• Multi-page tours that navigate for you (SvelteKit goto) and survive reloads
• Interactive steps that finish when the user clicks the real button (advanceOn)
• Beacons (pulsing hint dots) and one-off highlights
• Accessible: dialog semantics, focus trap, inert background, arrow and Escape keys, live announcements, 44px controls
• Phone sheet below 640px that docks away from low targets such as fixed tab bars
• Reduced motion that follows the OS setting or a prop
• Themes: light, dark, auto, or custom tokens, all as CSS variables
• JSON tours with a JSON Schema and path-level validation; documents never run code
• Analytics through a single onEvent stream
• Headless core for fully custom UIs

Theming

Pass theme="light" | "dark" | "auto" or { base, ...tokens }, or set the --tourlight-* variables on .tourlight-root in your own CSS. The overlay is marked with data-tourlight-theme, never data-theme, so daisyUI (and other systems that switch themes on [data-theme]) don't redefine --color-* inside the tour. To use your daisyUI colours, map them: .tourlight-root { --tourlight-primary: var(--color-primary); }.

Why Svelte, not React

Our app is SvelteKit with Svelte 5. Using react-tourlight would mean shipping React and ReactDOM (about 45 KB gzipped), running a second framework and hydration system, and bridging routing and themes between them. A native runes port is smaller, fits SvelteKit routing and our design tokens directly, and is ours to extend.

API overview

Export	What it does	Demo
SpotlightProvider	Root component: theme, persistence, navigate, basePath, callbacks	Getting started
SpotlightTour	Registers a tour's steps	Basic tour
useSpotlight()	Reactive controller: start(id, { stepIndex }), next, skip, highlight, state	Basic tour
Step route	Multi-page, route-aware steps	Multi-page
Step advanceOn / interactive	Real input through the cutout	Interactive
SpotlightBeacon, SpotlightHighlight	Hint dots and one-off callouts	Beacons
svelte-tourlight/document	validateTourDocument, compileTourDocument, schema	JSON tours
theme	Light, dark, auto, custom tokens	Themes
sheetPosition, mobileBreakpoint	Phone sheet, docked away from low targets	Phone
Built-in a11y, labels	Keys, focus, announcements, i18n	Accessibility

Credits

Inspired by and ported from react-tourlight (MIT, © react-tourlight contributors), created by Bilal Tahir. See NOTICE.

License

MIT