Stop Wasting Time: Build Your First Onboarding Flow with OnboardJS in Under 10 Minutes

// src/onboarding-config.ts
// Import your actual React components here
import ProfileSetupForm from './components/ProfileSetupForm';
import FinishStepComponent from './components/FinishStepComponent';

// Define your onboarding flow steps
export const steps: OnboardingStep[] = [
  {
    id: 'welcome',
    type: 'CUSTOM_COMPONENT',
    payload: {
      componentKey: 'ProfileSetupForm', // Maps to our component registry
      title: 'Welcome to Our App!', // Example custom payload data
      description: 'Let\'s get your profile set up quickly.',
    },
  },
  {
    id: 'finish',
    type: 'CUSTOM_COMPONENT',
    payload: {
      componentKey: 'FinishStepComponent', // Maps to our finish component
      title: 'Setup Complete!',
      message: 'You\'re all set to explore our amazing features!',
    },
    nextStep: null, // Critical: 'null' indicates the end of the flow
  },
];

// Define your component registry to map componentKeys to actual React components
// This tells OnboardJS which UI component to render for each custom step.
export const componentRegistry: StepComponentRegistry = {
  ProfileSetupForm: ProfileSetupForm,
  FinishStepComponent: FinishStepComponent,
};

// src/components/ProfileSetupForm.tsx
"use client"; // Required for Next.js App Router client components
import React from "react";
import { useOnboarding, StepComponentProps } from "@onboardjs/react"; // <-- Essential hook for navigation

interface ProfileSetupPayload {
  title: string;
  description: string;
}

const ProfileSetupForm: React.FC<StepComponentProps<ProfileSetupPayload>> = ({
  payload, // Access the payload data passed from the engine
  coreContext, // Access global onboarding data here if needed
}) => {
  const { next, isLoading, state, updateContext } = useOnboarding(); // Get navigation functions and current state

  const updateName = (newName: string) => {
    // Then, you update the context here
    updateContext({ flowData: { profileName: newName } });
  };

  return (
    <div>
      <h2>{payload.title}</h2>
      <p>{payload.description}</p>

      <label htmlFor="name-input">Your Name:</label>
      <input
        id="name-input"
        type="text"
        defaultValue={coreContext?.flowData?.profileName || ""}
        onChange={(e) => updateName(e.target.value)}
        placeholder="Enter your name"
      />

      <button
        onClick={() => next()} // Calls the engine's 'next' function
        disabled={isLoading || !state?.canGoNext} // Disable if loading or if step isn't valid
      >
        {isLoading ? "Loading..." : "Next"}
      </button>
    </div>
  );
};

export default ProfileSetupForm;

// src/components/FinishStepComponent.tsx
"use client"; // Required for Next.js App Router client components

import React from "react";
import { StepComponentProps, useOnboarding } from "@onboardjs/react";
// No need for useOnboarding here if no navigation action is taken on this final step

interface FinishPayload {
  title: string;
  message: string;
}

const FinishStepComponent: React.FC<StepComponentProps<FinishPayload>> = ({
  payload,
  coreContext,
}) => {
  const { next } = useOnboarding();
  // You can access all collected data from coreContext.flowData
  const finalUserName = coreContext.flowData.profileName || "Guest"; // Use 'profileName' collected from previous step

  return (
    <div
      style={{
        padding: "20px",
        border: "1px solid #eee",
        borderRadius: "8px",
        maxWidth: "400px",
        margin: "auto",
      }}
    >
      <h2>{payload.title}</h2>
      <p>{payload.message}</p>
      <p>Welcome, {finalUserName}!</p>
      <p>
        Your collected data:
        <pre
          style={{
            backgroundColor: "#f0f0f0",
            padding: "10px",
            borderRadius: "4px",
            overflowX: "auto",
            fontSize: "0.9em",
          }}
        >
          {JSON.stringify(coreContext.flowData, null, 2)}
        </pre>
      </p>
      {/* The Finish button */}
      <button
        onClick={() => {
          // Finish the onboarding flow by calling next()
          next();
        }}
      >
        Finish
      </button>
    </div>
  );
};

export default FinishStepComponent;

// ./components/OnboardingUI.tsx
"use client"; // REQUIRED for client-side hooks like useOnboarding and useRouter

import React from 'react';
import { useOnboarding } from "@onboardjs/react";

// Create a simple wrapper component to manage global UI and navigation
export default function OnboardingUI() {
  const { state, isLoading, next, previous, skip, reset, renderStep } = useOnboarding();

  // Basic Loading/Completion/Error States for brevity in this guide
  if (!state) {
    return <div style={{ textAlign: 'center', padding: '20px' }}>Loading onboarding...</div>;
  }
  if (state.error) {
    return (
      <div style={{ textAlign: 'center', padding: '20px', color: 'red' }}>
        Error: {state.error.message} <button onClick={() => reset()} style={{ marginLeft: '10px' }}>Reset</button>
      </div>
    );
  }
  if (state.isCompleted) {
    return (
      <div style={{ textAlign: 'center', padding: '20px' }}>
        <h2>Onboarding Completed! 🎉</h2>
        <p>You're all set. Redirecting to dashboard...</p>
      </div>
    );
  }

  return (
    <div style={{ maxWidth: '600px', margin: '20px auto', padding: '20px', border: '1px solid #ccc', borderRadius: '8px' }}>
      {/* The function that renders your current step's UI */}
      {renderStep()}

      {/* (Optional) Basic Navigation Buttons */}
      <div style={{ marginTop: '20px', display: 'flex', justifyContent: 'space-between' }}>
        {state.canGoPrevious && (
          <button onClick={previous} disabled={isLoading} style={{ padding: '8px 15px', cursor: 'pointer' }}>
            Back
          </button>
        )}
        {state.isSkippable && (
          <button onClick={skip} disabled={isLoading} style={{ padding: '8px 15px', cursor: 'pointer', marginLeft: 'auto' }}>
            Skip
          </button>
        )}
        {state.canGoNext && (
          <button onClick={next} disabled={isLoading || !state.canGoNext} style={{ padding: '8px 15px', cursor: 'pointer', backgroundColor: '#0070f3', color: 'white', border: 'none' }}>
            Next
          </button>
        )}
        {state.isLastStep && !state.isCompleted && (
          <button onClick={next} disabled={isLoading} style={{ padding: '8px 15px', cursor: 'pointer', backgroundColor: '#28a745', color: 'white', border: 'none' }}>
            Finish
          </button>
        )}
      </div>
    </div>
  );
}

// src/app/layout.tsx (for Next.js App Router example)
"use client"; // REQUIRED for client-side hooks like useOnboarding and useRouter

import React from "react";
import { OnboardingProvider } from "@onboardjs/react";
import { steps, componentRegistry } from "./onboarding-config";
import { useRouter } from "next/navigation"; // Import useRouter for redirection example

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  const router = useRouter(); // Initialize router if you want to redirect after flow completion

  return (
    <html lang="en">
      <body>
        <OnboardingProvider
          steps={steps}
          componentRegistry={componentRegistry} // Link your UI components
          onFlowComplete={(context) => {
            console.log("Onboarding flow completed!", context);
            alert(
              `Onboarding complete for ${
                context.flowData.profileName || "user"
              }!`
            );
            // Example: Redirect the user to their dashboard after onboarding
            router.push("/dashboard"); // Make sure you have a /dashboard page!
          }}
          onStepChange={(newStep, oldStep, context) => {
            console.log("Step changed:", oldStep?.id, "->", newStep?.id);
            // You could use this to send analytics events, update UI, etc.
          }}
          localStoragePersistence={{ key: "myAppOnboardingState" }} // Magical persistence!
          initialStepId="welcome" // Optional: Specify starting step if not the first in array
        >
          <main>
            {/* You can render your application UI here */}
            <YourApplicationUI />
          </main>
        </OnboardingProvider>
      </body>
    </html>
  );
}