OnboardJS - Docs - Build Better Onboarding

Learn how to get OnboardJS set up in your project in under thirty minutes.

Installation

Step-by-step guide for installing the library and setting up a basic flow.

Plugins

Extend the library with third-party plugins or write your own.

React

Learn how easy it is to integrate OnboardJS into a React project.

Welcome to OnboardJS! This guide will help you quickly integrate flexible and powerful onboarding flows into your React application.

Quick start

OnboardJS provides a core engine for defining and managing onboarding logic, and a React SDK (@onboardjs/react) for easily integrating this engine into your UI.

Installing dependencies

First, install the necessary packages. You'll need the core engine and the React bindings.

bash

1 lines

1npm install @onboardjs/core @onboardjs/react

The @onboardjs/core package contains the core logic for defining and managing onboarding flows, while @onboardjs/react provides React components and hooks to integrate the engine into your application.

Define onboarding steps

The heart of OnboardJS is its configuration, where you define the steps of your onboarding flow. Each step has an id, type, and a payload specific to its type.

Create a file for your onboarding configuration, for example, src/lib/onboarding-config.ts:

tsx

39 lines

1import { OnboardingEngineConfig, OnboardingStep } from '@onboardjs/core'
2
3// Define your steps
4export const steps: OnboardingStep[] = [
5  {
6    id: 'welcome',
7    type: 'INFORMATION', // A simple informational step
8    payload: {
9      title: 'Welcome to Our App!',
10    },
11  },
12  {
13    id: 'profile-details',
14    type: 'CUSTOM_COMPONENT', // A step that renders your own React component
15    payload: {
16      componentKey: 'ProfileSetupForm', // A key to identify which custom component to render
17      title: 'Complete Your Profile',
18    },
19    nextStep: 'finish', // You can specify the next step by ID
20  },
21  {
22    id: 'finish',
23    type: 'INFORMATION',
24    payload: {
25      title: 'Setup Complete!',
26    },
27    nextStep: null, // null indicates the end of the flow
28  },
29]
30
31// Define your Component Registry
32export const componentRegistry = {
33  // Map every INFORMATION step to a simple informational component
34  INFORMATION: InformationStepComponent,
35  // Map CUSTOM_COMPONENT based on the componentKey
36  ProfileSetupForm: ProfileSetupFormComponent,
37  // Override the default INFORMATION component by providing the ID instead
38  finish: FinishStepComponent,
39}

You should know!

Omitting nextStep in a step allows the engine to automatically navigate to the next step after the current one is completed. If you want to control navigation manually, you can provide this field to specify the next step's ID.

Basic usage

Once you have your onboarding steps defined, you can integrate the onboarding flow into your React application.

Set up the OnboardingProvider

Wrap your application (or the relevant part of it) with the OnboardingProvider. This provider initializes the OnboardingEngine and makes the onboarding state and actions available to your components via a React Context.

tsx

27 lines

1// src/App.tsx or your main application file
2import React from 'react'
3import { OnboardingProvider } from '@onboardjs/react'
4import { steps, componentRegistry } from './onboarding-config' // Your config from the previous step
5import YourMainAppComponent from './YourMainAppComponent' // Your actual app content
6
7function App() {
8  return (
9    <OnboardingProvider
10      steps={steps}
11      componentRegistry={componentRegistry}
12      onFlowComplete={(context) => {
13        console.log('Onboarding flow completed!', context)
14        // Perform actions like redirecting the user, setting a flag, etc.
15      }}
16      onStepChange={(newStep, oldStep, context) => {
17        console.log('Step changed:', oldStep?.id, '->', newStep?.id)
18      }}
19      // Optional: Enable localStorage persistence
20      localStoragePersistence={{ key: 'myAppOnboardingState' }}
21    >
22      <YourMainAppComponent />
23    </OnboardingProvider>
24  )
25}
26
27export default App

Next.js Ready!

For more information on how to use OnboardJS with Next.js, check out the Next.js guide.

Create your UI components for Onboarding steps

OnboardJS is "headless" by default, meaning it provides the logic, and you provide the UI. You'll typically create a component that consumes the onboarding context and renders the current steps.

Custom Step Components

tsx

33 lines

1// src/components/onboarding/ProfileSetupFormComponent.tsx
2import React from 'react'
3import { StepComponentProps, useOnboarding } from '@onboardjs/react'
4
5type TypedPayload = {
6  title?: string
7  description?: string
8}
9
10// Props will include the current step and its payload
11const ProfileSetupFormComponent: React.FC<StepComponentProps<TypedPayload>> = ({
12  // step, // The current step object
13  payload,
14}) => {
15  const { next, updateContext } = useOnboarding()
16
17  const handleSubmit = async () => {
18    // Simulate form submission
19    await updateContext({ flowData: { profileComplete: true } })
20    await next() // Proceed to the next step
21  }
22
23  return (
24    <div>
25      <h2>{payload?.title || 'Profile Setup'}</h2>
26      <p>Please fill in your details...</p>
27      {/* Your form fields here */}
28      <button onClick={handleSubmit}>Save and Continue</button>
29    </div>
30  )
31}
32
33export default ProfileSetupFormComponent

Render the onboarding flow

Now, you can create a component that renders the current step based on the onboarding context.

tsx

54 lines

1// src/components/onboarding/OnboardingFlow.tsx
2import React from 'react'
3import { useOnboarding } from '@onboardjs/react'
4
5// Define your component registry
6// This maps step types or componentKeys to your React components
7const componentRegistry = {
8  ProfileSetupForm: React.lazy(() => import('./ProfileSetupFormComponent')),
9  // Add more components as needed
10}
11
12export const OnboardingFlowPresenter: React.FC = () => {
13  const { currentStep, state, isLoading, isCompleted, next, previous, skip, renderStep } =
14    useOnboarding()
15
16  if (!state) {
17    // The state is not initialized yet, possibly loading from localStorage or your data source
18    return <div>Loading Onboarding...</div>
19  }
20
21  if (isCompleted) {
22    // Flow is done!
23    // You might want to hide this component or show a completion message
24    // if not handled by onFlowComplete redirecting.
25    return null
26  }
27
28  return (
29    <div className="onboarding-modal-or-container">
30      {/* Render the content for the current step */}
31      {renderStep()}
32
33      <div
34        className="onboarding-navigation"
35        style={{
36          marginTop: '20px',
37          display: 'flex',
38          justifyContent: 'space-between',
39        }}
40      >
41        <button onClick={() => previous()}>Previous</button>
42        <button onClick={() => skip()}>Skip</button>
43
44        {/* The primary action button often comes from the step's payload or is 'Next' */}
45
46        <button onClick={() => next()}>
47          {currentStep.payload.ctaButtonText ?? "Next"}
48        </button>
49      </div>
50      {/* Optional: Display progress */}
51      <div>Step {state.currentStepNumber} of {state.totalSteps}</div>
52    </div>
53  )
54}

Using the Onboarding UI

Now, include your OnboardingFlowPresenter (or similar UI component) in your application where you want the onboarding to appear. This could be a modal, a dedicated page, or embedded within a section.

tsx

21 lines

1// src/YourMainAppComponent.tsx
2import React from "react";
3import { OnboardingFlowPresenter } from "./components/OnboardingFlowPresenter";
4import { useOnboarding } from "@onboardjs/react"; // To potentially hide presenter when completed
5
6const YourMainAppComponent = () => {
7  const { isCompleted } = useOnboarding(); // Get completion state
8
9  return (
10    <div>
11      <h1>My Awesome Application</h1>
12      {/* Conditionally render the onboarding flow */}
13      {!isCompleted && <OnboardingFlowPresenter />}
14      
15      <p>Rest of your application content...</p>
16      {/* Example: Show a button to reset onboarding for testing */}
17    </div>
18  );
19};
20
21export default YourMainAppComponent;

Key Concepts Recap

OnboardingEngineConfig<TContext>: Defines your steps, initial state, and callbacks.
OnboardingStep<TContext>: Represents a single screen/interaction in your flow. Key properties: id, type, payload, next, previous, condition.
OnboardingProvider: Initializes the engine and provides context to your app.
useOnboarding() Hook: Accesses the engine's state (currentStep, isLoading, isCompleted, etc.) and actions (next, previous, reset, etc.).

Next Steps

Explore Step Types: OnboardJS supports various step types like INFORMATION, SINGLE_CHOICE, MULTIPLE_CHOICE, CHECKLIST, FORM_STEP, and CUSTOM_COMPONENT.
Conditional Logic: Use the condition property on steps to show/hide them based on the current context.flowData.
Dynamic Navigation: Use functions for next or previous for complex routing.
Persistence: Implement customOnDataLoad and customOnDataPersist for backend storage if localStoragePersistence isn't sufficient.
Plugins: Extend functionality with plugins or create your own.
Styling: Style your onboarding components to match your application's look and feel.

This quickstart should give you a solid foundation. Dive into the more detailed documentation for advanced features and customization!

Getting started