Onboarding

@allem-ui/onboarding

Step-by-step onboarding wizard with animated transitions, progress indicators, and spotlight product tours.

Installation

npm install @allem-ui/onboarding

Add the @source directive to your CSS so Tailwind generates the component classes:

@source "@allem-ui/onboarding";

Wizard

Multi-step wizard with slide transitions. Click Next/Back to navigate.

Welcome

Let's get you set up in just a few steps.

👋

Customize

Pick your preferences and make it yours.

⚙️

You're ready!

Start exploring your new workspace.

🚀

Custom Labels

Customize button labels and add a skip option with the bar progress variant.

Connect your account

Link your GitHub account to get started.

🔗

Choose a plan

Select the plan that works for your team.

💎

Invite your team

Add teammates to your new workspace.

👥

Step 1 of 333%

Progress Variants

Three built-in styles for the progress indicator.

Dots

Bar

Step 3 of 560%

Numbers

OnboardingWizard Props

Prop	Type	Default	Description
currentStep*	number	—	Current step index
totalSteps*	number	—	Total number of steps
onNext*	() => void	—	Next step callback
onPrev*	() => void	—	Previous step callback
onSkip	() => void	—	Skip callback — shows skip button when provided
isFirst*	boolean	—	Whether on first step
isLast*	boolean	—	Whether on last step
progressVariant	"dots" \| "bar" \| "numbers"	"dots"	Progress indicator style
nextLabel	string	"Next"	Label for the next button
prevLabel	string	"Back"	Label for the previous button
skipLabel	string	"Skip"	Label for the skip button
finishLabel	string	"Get Started"	Label for the finish button (last step)
className	string	—	Additional CSS classes
children*	ReactNode	—	OnboardingStep elements

OnboardingStep Props

Prop	Type	Default	Description
title	string	—	Step title
description	string	—	Step description
icon	ReactNode	—	Step icon
className	string	—	Additional CSS classes
children*	ReactNode	—	Step content

OnboardingProgress Props

Prop	Type	Default	Description
currentStep*	number	—	Current step index
totalSteps*	number	—	Total number of steps
variant	"dots" \| "bar" \| "numbers"	"dots"	Progress display style
className	string	—	Additional CSS classes

useOnboarding

Hook that manages step navigation state. Spread the return value directly onto OnboardingWizard.

Options

Prop	Type	Default	Description
totalSteps*	number	—	Total number of steps
initialStep	number	0	Starting step index
onComplete	() => void	—	Called when the user completes all steps
onSkip	() => void	—	Called when the user skips

Return Value

Prop	Type	Default	Description
currentStep	number	—	Current step index
totalSteps	number	—	Total number of steps
isFirst	boolean	—	Whether on the first step
isLast	boolean	—	Whether on the last step
isComplete	boolean	—	Whether onboarding is complete
next	() => void	—	Go to the next step
prev	() => void	—	Go to the previous step
goTo	(step: number) => void	—	Jump to a specific step
skip	() => void	—	Skip the onboarding
reset	() => void	—	Reset to the initial step

Spotlight Tour

Use SpotlightTour + useTour to create guided tours that highlight DOM elements with a spotlight overlay.

Spotlight Tour requires live DOM targets — see the code example for usage.

SpotlightTour Props

Prop	Type	Default	Description
isActive*	boolean	—	Whether the tour is running
step*	TourStep \| null	—	Current tour step
targetRect*	TargetRect \| null	—	Bounding rect of the target element
currentStep*	number	—	Current step index
totalSteps*	number	—	Total number of steps
isFirst*	boolean	—	Whether on first step
isLast*	boolean	—	Whether on last step
onNext*	() => void	—	Next step callback
onPrev*	() => void	—	Previous step callback
onSkip*	() => void	—	Skip tour callback
padding	number	8	Padding around the spotlight target
className	string	—	Additional CSS classes

SpotlightStep Props

Declarative step component — use as children of SpotlightTour or pass steps directly to useTour.

Prop	Type	Default	Description
target*	string	—	CSS selector for the target element
title*	string	—	Step title
content*	string	—	Step description
placement	"top" \| "bottom" \| "left" \| "right"	—	Tooltip placement relative to target

useTour Options

Prop	Type	Default	Description
steps*	TourStep[]	—	Array of tour steps
onComplete	() => void	—	Called when tour finishes
onSkip	() => void	—	Called when user skips the tour

useTour Return Value

Prop	Type	Default	Description
isActive	boolean	—	Whether the tour is currently running
currentStep	number	—	Current step index
totalSteps	number	—	Total number of steps
step	TourStep \| null	—	Current step object
targetRect	TargetRect \| null	—	Bounding rect of target element
isFirst	boolean	—	Whether on the first step
isLast	boolean	—	Whether on the last step
start	() => void	—	Start the tour
stop	() => void	—	Stop the tour without triggering onComplete
next	() => void	—	Go to the next step
prev	() => void	—	Go to the previous step
skip	() => void	—	Skip the tour (triggers onSkip)

TourStep Type

Prop	Type	Default	Description
target*	string	—	CSS selector for the target element
title*	string	—	Step title
content*	string	—	Step description
placement	"top" \| "bottom" \| "left" \| "right"	—	Tooltip placement relative to target

Tour Built-in Behavior

Feature	Description
Keyboard navigation	→ next step, ← previous step, Esc to skip the tour.
Auto-scroll	Target elements are smoothly scrolled into view on each step.
Resize tracking	Spotlight position updates on window resize and scroll via ResizeObserver.
Spotlight overlay	Full-screen overlay with a cutout around the target element using box-shadow.