Onboarding Wizard

PreviousNext

Multi-step talent setup wizard with progress tracking

What is the Onboarding Wizard?

The onboarding wizard guides new talent through a 7-step setup flow, replacing the original single-page setup screen. It uses animated step transitions, a visual progress bar, and fetches live data to show completion status.

Component: SetupScreen in packages/client/src/screens/SetupScreen.tsx

Exported from @zooly/client.

Steps

StepNameWhat It Does
1ProfileLinks to profile setup. Shows current display name and avatar status.
2CampaignsInformational step about campaign types. Links to campaign settings.
3TermsLinks to license setup screens (voice, image, merch).
4SamplesInformational step about uploading voice/image samples.
5Z LinkShows preview of public page URL. Links to Z Link page.
6PaymentsShows Stripe Connect status. Links to payout setup if not connected.
7ReviewSummary dashboard. Shows completion status per area. "Go to Dashboard" button.

Component Props

The SetupScreen component accepts navigation callbacks from the host application:

PropTypePurpose
onGoToProfile() => voidNavigate to profile editing
onGoToDashboard() => voidNavigate to main dashboard
onGoToVoiceLicense() => void (optional)Navigate to voice license setup
onGoToImageLicense() => void (optional)Navigate to image license setup
onGoToMerchLicense() => void (optional)Navigate to merch license setup

UI Features

  • Progress bar — sticky at top, numbered step indicators with animated fill
  • Animated transitions — uses framer-motion AnimatePresence for slide transitions between steps
  • Back / Next navigation — sticky at bottom, conditionally shown
  • Completion indicators — Step 7 (Review) shows green checkmarks for completed areas
  • Data-driven — fetches account and payout route on mount to determine status

Data Fetching

On mount, the component fetches:

  1. GET /api/account — current account data (display name, slug, avatar, Stripe status)
  2. GET /api/account/payout-route — payout route data (Stripe Connect account)

This data drives the completion indicators in the Review step and the Stripe Connect status in the Payments step.

Progress Tracking

Progress is derived from the current data state rather than stored separately:

  • Profile complete — account has displayName and slug
  • Payments connected — account has stripeConnectAccountId or payout route has a Stripe account

The wizard does not persist the current step position — if the user leaves and returns, they start at step 1 but can navigate freely.

Extending the Wizard

To add a new step:

  1. Add the step to the STEPS array in packages/client/src/screens/SetupScreen.tsx
  2. Create a new step component following the existing pattern (accepts relevant data as props)
  3. Add the step render case in the AnimatePresence block
  4. Update the total step count in the progress bar logic

Key Files

FileRole
packages/client/src/screens/SetupScreen.tsxWizard component with all 7 steps
packages/client/src/index.tsExports SetupScreen

Related Documentation