Defining steps

Steps are the building blocks of your onboarding flow in OnboardJS. Each step represents a screen, question, or action the user will encounter. You define your steps as an array of objects, each with a unique id, a type, and a payload describing the content or behavior of the step.

Basic Step Structure

Here’s what a typical step looks like:

tsx

10 lines

1const step: OnboardingStep = {
2  id: "welcome", // Unique identifier for this step
3  payload: {
4    title: "Welcome!",
5    mainText: "Let's get started.",
6    ctaButtonText: "Next",
7  },
8  nextStep: "profile", // (Optional) The id of the next step
9  previousStep: null,  // (Optional) The id of the previous step
10};

Example: Minimal Steps Array

tsx

35 lines

1const steps: OnboardingStep[] = [
2  {
3    id: "welcome",
4    payload: {
5      title: "Welcome to the App!",
6      mainText: "Let's get you set up.",
7      ctaButtonText: "Start",
8    },
9    nextStep: "choose-role",
10  },
11  {
12    id: "choose-role",
13    type: "SINGLE_CHOICE",
14    payload: {
15      question: "What is your role?",
16      dataKey: "userRole",
17      options: [
18        { id: "dev", label: "Developer", value: "developer" },
19        { id: "designer", label: "Designer", value: "designer" },
20      ],
21    },
22    nextStep: "finish",
23    previousStep: "welcome",
24  },
25  {
26    id: "finish",
27    payload: {
28      title: "You're all set!",
29      mainText: "Enjoy using the app.",
30      ctaButtonText: "Done",
31    },
32    previousStep: "choose-role",
33    nextStep: null, // End of flow
34  },
35];

Advanced Step Features

You can use a function for nextStep or previousStep to determine the next step based on the current context:

tsx

5 lines

1{
2  id: "figma-choose-role",
3  payload: { /* ... */ },
4  nextStep: (context) => context.flowData.userRole === "developer" ? "dev-setup" : "designer-setup",
5}

Conditional Steps

Use the condition property to show or skip a step based on the context:

tsx

10 lines

1{
2  id: "dev-setup",
3  payload: { title: "Developer Setup" },
4  condition: (context) => context.flowData.userRole === "developer",
5},
6{
7  id: "admin-setup",
8  payload: { title: "Admin Setup" },
9  condition: (context) => context.flowData.userRole === "admin",
10}

Best Practices

Unique IDs: Every step must have a unique id.
Keep it modular: Break complex flows into small, focused steps.
Use flowData: Store user answers and flags in context.flowData for use in navigation and conditions.
Use condition for personalization: Show or skip steps based on previous answers.

Next:

Basic Step Structure

Example: Minimal Steps Array

Advanced Step Features

Dynamic Navigation

Conditional Steps

Best Practices