Tutorial

A tutorial component with spotlight overlays and guided popovers.

vu-tutorial · @velkin/react-pro/tutorial

Copy page

Import

React

npm i @velkin/react-pro

import { LicenseInfo } from "@velkin/license";
// Vite: import.meta.env.VITE_VELKIN_LICENSE_KEY
// Next: process.env.NEXT_PUBLIC_VELKIN_LICENSE_KEY
LicenseInfo.setLicenseKey(import.meta.env.VITE_VELKIN_LICENSE_KEY ?? process.env.NEXT_PUBLIC_VELKIN_LICENSE_KEY ?? "");

// @velkin-pro
import { VuTutorial } from "@velkin/react-pro/tutorial";

Examples

API

Props

Prop	Type	Default	Description
steps	TutorialStep[]	[]	Tutorial steps; filtered with `step.when()` before running.
open	`boolean`	false	Whether the overlay is visible.
startIndex	`number`	0	Index used by `start()`.
closeOnBackdrop	`boolean`	true	Close when the dimmed mask is clicked (overridable per step).
closeOnEscape	`boolean`	true	Close on Escape.
lockScroll	`boolean`	true	Lock body scroll while open.
spotlightPadding	`number`	0	Extra padding around target rects.
spotlightRadius	`number`	14	Spotlight corner radius.
popoverMaxWidth	`number`	380	Max width of the tip panel.
zIndex	`number`	9999	Overlay z-index.
progress	TutorialProgress	"counter"	Progress indicator style.
showGroup	`boolean`	true	Show step group label.
tourId	`string`	"default"	Persistence key id.
version	`string`	"v1"	Persistence key version.
persist	`boolean`	true	Persist progress in localStorage.
navigate	`(route: string) => void \| Promise<void>`	—	SPA navigation for route steps.
waitForRouteReady	`() => void \| Promise<void>`	—	Await route readiness after navigate.
labels	Partial	{}	Override chrome labels.
variant	VuTutorialVariant	"elevated"	Floating tip surface recipe. Default: `"elevated"`.
tone	VuTutorialTone	"normal"	Neutral overlay weight. Default: `"normal"`.
size	VuTutorialSize	"md"	Tip panel size scale. Default: `"md"`.
radius	VuTutorialRadius	"md"	Tip panel corner radius. Default: `"md"`.

Events

Event	Detail	Description
vu-open	VuTutorialEventDetail	Tutorial opened.
vu-step	VuTutorialEventDetail	Step entered.
vu-complete	VuTutorialEventDetail	All steps completed.
vu-skip	VuTutorialEventDetail	Tour skipped.
vu-close	VuTutorialEventDetail	Tutorial closed.
vu-missing	VuTutorialMissingTargetDetail	Target could not be resolved.
vu-noroute	VuTutorialRouteMissingNavigatorDetail	Route step without navigate.

Slots

Slot	Description
content:{stepId}	Named slots for step-specific content (e.g. `content:first-step`).

CSS parts

Part	Description
layer	Full-viewport overlay layer.
mask	Dimmed SVG mask with spotlight holes.
spotlight	Highlighted target outline.
connectors	SVG connector layer.
connector	One connector path.
annotation	Floating annotation label.
popover	Tip panel (role=dialog).
header	Title/group row.
body	Step content region.
footer	Action button row.

Methods

Method	Description
start	Opens from an index.
next	Advances one step.
back	Moves one step back.
nextStep	Alias for `next()`.
prevStep	Alias for `back()`.
finish	Completes and closes.
skip	Skips and closes.
resume	Resumes from persisted progress.
reset	Clears persisted state.
isOpen	Whether currently open.
getCurrentStep	Current step metadata.
close	Closes the overlay.

Types

Name	Definition
TutorialProgress	`"none" \| "dots" \| "bar" \| "counter"`
VuTutorialEventDetail	`{ tourId: string; version: string; index: number; total: number; stepId: string \| null; group: string \| null; }`
VuTutorialMissingTargetDetail	`VuTutorialEventDetail & { target: string; }`
VuTutorialRadius	`"sm" \| "md" \| "lg"`
VuTutorialRouteMissingNavigatorDetail	`VuTutorialEventDetail & { route: string; }`
VuTutorialSize	`"sm" \| "md" \| "lg"`
VuTutorialTone	`"subtle" \| "normal" \| "strong"`
VuTutorialVariant	`"outline" \| "elevated" \| "soft"`

Import

React

npm i @velkin/react-pro import { LicenseInfo } from "@velkin/license"; // Vite: import.meta.env.VITE_VELKIN_LICENSE_KEY // Next: process.env.NEXT_PUBLIC_VELKIN_LICENSE_KEY LicenseInfo.setLicenseKey(import.meta.env.VITE_VELKIN_LICENSE_KEY ?? process.env.NEXT_PUBLIC_VELKIN_LICENSE_KEY ?? ""); // @velkin-pro import { VuTutorial } from "@velkin/react-pro/tutorial";

API

Props

Prop	Type	Default	Description
steps	TutorialStep[]	[]	Tutorial steps; filtered with `step.when()` before running.
open	`boolean`	false	Whether the overlay is visible.
startIndex	`number`	0	Index used by `start()`.
closeOnBackdrop	`boolean`	true	Close when the dimmed mask is clicked (overridable per step).
closeOnEscape	`boolean`	true	Close on Escape.
lockScroll	`boolean`	true	Lock body scroll while open.
spotlightPadding	`number`	0	Extra padding around target rects.
spotlightRadius	`number`	14	Spotlight corner radius.
popoverMaxWidth	`number`	380	Max width of the tip panel.
zIndex	`number`	9999	Overlay z-index.
progress	TutorialProgress	"counter"	Progress indicator style.
showGroup	`boolean`	true	Show step group label.
tourId	`string`	"default"	Persistence key id.
version	`string`	"v1"	Persistence key version.
persist	`boolean`	true	Persist progress in localStorage.
navigate	`(route: string) => void \| Promise<void>`	—	SPA navigation for route steps.
waitForRouteReady	`() => void \| Promise<void>`	—	Await route readiness after navigate.
labels	Partial	{}	Override chrome labels.
variant	VuTutorialVariant	"elevated"	Floating tip surface recipe. Default: `"elevated"`.
tone	VuTutorialTone	"normal"	Neutral overlay weight. Default: `"normal"`.
size	VuTutorialSize	"md"	Tip panel size scale. Default: `"md"`.
radius	VuTutorialRadius	"md"	Tip panel corner radius. Default: `"md"`.

Events

Event	Detail	Description
vu-open	VuTutorialEventDetail	Tutorial opened.
vu-step	VuTutorialEventDetail	Step entered.
vu-complete	VuTutorialEventDetail	All steps completed.
vu-skip	VuTutorialEventDetail	Tour skipped.
vu-close	VuTutorialEventDetail	Tutorial closed.
vu-missing	VuTutorialMissingTargetDetail	Target could not be resolved.
vu-noroute	VuTutorialRouteMissingNavigatorDetail	Route step without navigate.

Slots

Slot	Description
content:{stepId}	Named slots for step-specific content (e.g. `content:first-step`).

CSS parts

Part	Description
layer	Full-viewport overlay layer.
mask	Dimmed SVG mask with spotlight holes.
spotlight	Highlighted target outline.
connectors	SVG connector layer.
connector	One connector path.
annotation	Floating annotation label.
popover	Tip panel (role=dialog).
header	Title/group row.
body	Step content region.
footer	Action button row.

Methods

Method	Description
start	Opens from an index.
next	Advances one step.
back	Moves one step back.
nextStep	Alias for `next()`.
prevStep	Alias for `back()`.
finish	Completes and closes.
skip	Skips and closes.
resume	Resumes from persisted progress.
reset	Clears persisted state.
isOpen	Whether currently open.
getCurrentStep	Current step metadata.
close	Closes the overlay.

Types

Name	Definition
TutorialProgress	`"none" \| "dots" \| "bar" \| "counter"`
VuTutorialEventDetail	`{ tourId: string; version: string; index: number; total: number; stepId: string \| null; group: string \| null; }`
VuTutorialMissingTargetDetail	`VuTutorialEventDetail & { target: string; }`
VuTutorialRadius	`"sm" \| "md" \| "lg"`
VuTutorialRouteMissingNavigatorDetail	`VuTutorialEventDetail & { route: string; }`
VuTutorialSize	`"sm" \| "md" \| "lg"`
VuTutorialTone	`"subtle" \| "normal" \| "strong"`
VuTutorialVariant	`"outline" \| "elevated" \| "soft"`

Import

Examples

API

Props

Events

Slots

CSS parts

Methods

Types

Related

Feedback

Guides

Browse

Import

Examples

API

Props

Events

Slots

CSS parts

Methods

Types

Related

Feedback

Guides

Browse