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

11 lines

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

Common Step Types

INFORMATION: Show a message, image, or instructions.
SINGLE_CHOICE: Present a question with multiple options (radio buttons).
MULTIPLE_CHOICE: Present a question with multiple selectable options (checkboxes).
CHECKLIST: Show a list of tasks for the user to complete.
CUSTOM_COMPONENT: Render your own React component for custom UI or logic.

You can define your own types as well—OnboardJS is headless and type-agnostic.

Example: Minimal Steps Array

tsx

37 lines

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

Advanced Step Features

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

tsx

6 lines

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

Conditional Steps

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

tsx

6 lines

1{
2  id: "dev-setup",
3  type: "INFORMATION",
4  payload: { title: "Developer Setup", mainText: "..." },
5  condition: (context) => context.flowData.userRole === "developer",
6}

Custom Components

For complex UI, use type: "CUSTOM_COMPONENT" and provide a componentKey in the payload:

tsx

9 lines

1{
2  id: "profile-form",
3  type: "CUSTOM_COMPONENT",
4  payload: {
5    componentKey: "ProfileForm", // You map this to your React component
6    title: "Set up your profile",
7  },
8  nextStep: "finish",
9}

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.
Use CUSTOM_COMPONENT for advanced UI: When you need more than the built-in step types.

Next: Learn about the Onboarding Context & flowData