Onboarding Flow React block for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Onboarding Flow is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import OnboardingFlow from @/components/blocks/onboarding-flow.

// app/(app)/welcome/page.tsx
"use client";

import { useRouter } from "next/navigation";
import { OnboardingFlow } from "@/components/blocks/onboarding-flow";

export default function Page() {
  const router = useRouter();
  return (
    <OnboardingFlow
      user={{ name: "Emma Carter" }}
      persistKey="onboarding:ana"
      onUpload={async (blob) => {
        const response = await fetch("/api/avatar", { method: "POST", body: blob });
        if (!response.ok) throw new Error("Upload failed");
        return (await response.json()).url;
      }}
      onComplete={async ({ profile, preferences, permissions }) => {
        await fetch("/api/onboarding", { method: "POST", body: JSON.stringify({ profile, preferences, permissions }) });
        router.push("/");
      }}
    />
  );
}

Props

• defaultStepdefault "welcome"
  OnboardingStep

  The step shown first (uncontrolled, and the fallback before storage is read): "welcome" | "permissions" | "profile" | "preferences" | "done".

• step
  OnboardingStep

  The current step, controlled (then nothing is restored from storage for it).

• onStepChange
  (step: OnboardingStep) => void

  Runs on every step change (mirror it to the URL).

• slides
  OnboardingSlide[]

  The welcome slides (onboarding-carousel's slide shape). Default: the three Acme Market slides from ONBOARDING_FLOW_SAMPLE with their vignettes and the side panel pictures; custom slides show their image in the side panel.

• interests
  OnboardingInterest[]

  The chips of the profile step: { id, label, icon, description }. Default: the 12 Acme Market categories of ONBOARDING_FLOW_SAMPLE.interests; icon takes a node or a sample icon name.

• minInterestsdefault 3
  number

  How many interests the profile needs; 0 makes them optional.

• permissions
  ("notifications" | "location")[]

  The permissions asked for, default both; [] skips the step.

• simulatePermissionsdefault false
  boolean

  Answer granted after 600 ms instead of calling the browser (demos, tests); a simulated location is Gheorgheni, Cluj-Napoca.

• user
  OnboardingUser

  The signed-up person ({ name, avatar, city }): the name the profile starts with and the side panel's profile card. Default ONBOARDING_FLOW_SAMPLE.user (Emma Carter).

• defaultProfile
  OnboardingProfile

  The profile the flow starts with ({ avatar, name, city, interests }); default empty with the name from user.

• profile
  OnboardingProfile

  The profile, controlled; onProfileChange gets every draft change.

• onProfileChange
  (profile: OnboardingProfile) => void

  Every change of the profile draft (photo, name, city, interests).

• defaultPreferences
  OnboardingPreferences

  The preferences the flow starts with; default { frequency: "daily", newsletter: false }.

• preferences
  OnboardingPreferences

  The preferences, controlled; onPreferencesChange gets every change.

• onPreferencesChange
  (preferences: OnboardingPreferences) => void

  Every change of the frequency or the newsletter switch.

• persistKeydefault "onboarding-flow"
  string

  Local storage key that keeps the step, the drafts and the permission answers, so a closed app resumes where it stopped; empty keeps them in memory.

• showSkipdefault true
  boolean

  Skip on the slides and in the header of the later steps.

• allowRestartdefault true
  boolean

  The Start over button on the finish screen, which clears the saved progress.

• artdefault "image"
  "image" | "none"

  The picture beside the card from 1024px, cross fading per step and per slide (tablets show the card alone, centered); none centers the card alone everywhere.

• onComplete
  (result: OnboardingFlowResult) => (void | Promise<unknown>)

  Go to Home: gets { profile, preferences, permissions } (each permission granted, denied or skipped); a promise spins the button. Default: the toast "Welcome to Acme Market".

• onUpload
  (blob: Blob, context: AvatarUploadContext) => Promise<string | void>

  Uploads the cropped photo and resolves its url. Default: simulated for 900 ms, then kept as a data url; a failed upload shows a note and the flow continues without a photo.

• tonedefault "neutral"
  Tone

  The primary buttons, the progress bar, the selected chips, the frequency thumb, the switch and the slides' button and dots.

• radiusdefault "md"
  "sm" | "md" | "lg"

  The card and the side panel, the permission tiles and the controls' corners.

• loadingdefault false
  boolean

  The card as skeletons of the profile step and a pulsing side panel.

• animateIndefault true
  boolean

  The side panel and the card rise in once when the page mounts on the client (server html is already final).

• labels
  Partial<OnboardingFlowLabels>

  Every visible string: DEFAULT_ONBOARDING_FLOW_LABELS (English) by default; carousel, avatarUpload, cropper and validation carry the composed items' strings.

• localedefault "en-US"
  string

  Prices and distances on the slides and the page language (lang).

• classNames
  Partial<Record<OnboardingFlowSlot, string>>

  Classes for art, main, card, header, progress, step, title, description, footer, permission, interests and done.

Parts

FAQ

More React blocks