OnboardJS

Core concepts

Onboarding Config

The heart of any OnboardingJS flow is its configuration. This is where you define the structure, content, and logic of your user onboarding experience. The primary configuration object is passed to the OnboardingEngine (directly or via the OnboardingProvider in React).

Main Configuration Object OnboardingEngineConfig

The OnboardingEngineConfig is an object that brings together all aspects of your onboarding flow. Here are its key properties:

tsx
24 lines
1// Example: onboarding-config.ts
2import { OnboardingEngineConfig, OnboardingStep } from "@onboardjs/core";
3
4export const myAppOnboardingConfig: OnboardingEngineConfig = {
5  // 1. Define your steps (see below)
6  steps: [ /* ... your step objects ... */ ],
7
8  // 2. (Optional) Tell it where to start
9  initialStepId: "welcome", // The 'id' of your first step
10
11  // 3. (Optional) Actions when things happen
12  onFlowComplete: (context) => {
13    console.log("All done!", context.flowData);
14    // Example: Mark onboarding as done for the user
15  },
16  onStepChange: (newStep, oldStep) => {
17    console.log(`Moved from ${oldStep?.id} to ${newStep?.id}`);
18  },
19
20  // 4. (Optional) Initial data for your flow
21  // initialContext: {
22  //   flowData: { userSegment: 'trial' }
23  // }
24};

Defining a Step OnboardingStep

Each step in the steps array is an object with a few important properties:

tsx
14 lines
1// Example of a single step object
2const welcomeStep: OnboardingStep = {
3  id: "welcome", // Unique ID for this step
4  type: "INFORMATION", // What kind of step is this? (e.g., "INFORMATION", "SINGLE_CHOICE", "CUSTOM_COMPONENT")
5  payload: {       
6    // Data for this step
7    title: "Welcome to Our App!",
8    mainText: "We're glad to have you.",
9    ctaButtonText: "Next", // Text for the main action button
10  },
11  nextStep: "feature-overview", // (Optional) ID of the step to go to next
12  // previousStep: "some-other-step-id", // Optional: ID of the previous step
13  // condition: (context) => context.flowData.userIsAdmin === true, // Optional: Only show if condition is met
14};

The context and flowData

Throughout your onboarding, OnboardJS maintains a context object. A special part of this is context.flowData.

  • context.flowData: This is your scratchpad!
    • Store answers from questions (e.g., context.flowData.userRole = 'developer').
    • Track progress or choices.
    • Use it in condition functions to show/hide steps.
    • Use it in nextStep functions for dynamic routing.

Putting It Together (Minimal Example)

tsx
26 lines
1// onboarding-config.ts
2import { OnboardingEngineConfig, OnboardingStep } from "@onboardjs/core";
3
4const steps: OnboardingStep[] = [
5  {
6    id: "step1",
7    type: "INFORMATION",
8    payload: { title: "Step 1: Welcome", mainText: "Hello there!" },
9    nextStep: "step2",
10  },
11  {
12    id: "step2",
13    type: "INFORMATION",
14    payload: { title: "Step 2: You're Done!", mainText: "That was easy." },
15    nextStep: null, // End of flow
16    previousStep: "step1",
17  },
18];
19
20export const minimalOnboardingConfig: OnboardingEngineConfig = {
21  steps: steps,
22  initialStepId: "step1",
23  onFlowComplete: () => {
24    alert("Onboarding finished!");
25  },
26};

This configuration defines the "what" and "when" of your onboarding. The "how it looks" is up to your React components that will use this configuration via @onboardjs/react.

Next Steps

Previous
What is OnboardJS?
Next
Defining steps