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

28 lines

1import { OnboardingStep } from '@onboardjs/react'
2
3// Define your steps
4export const steps: OnboardingStep[] = [
5  {
6    id: 'welcome',
7    component: WelcomeStep,
8    payload: {
9      title: 'Welcome to Our App!',
10    },
11  },
12  {
13    id: 'profile-details',
14    component: ProfileSetupStep, // A React component you create
15    payload: {
16      title: 'Complete Your Profile',
17    },
18    nextStep: 'finish', // You can specify the next step by ID
19  },
20  {
21    id: 'finish',
22    component: FinishStep,
23    payload: {
24      title: 'Setup Complete!',
25    },
26    nextStep: null, // null indicates the end of the flow
27  },
28]

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

14 lines

1// src/App.tsx or your main application file
2import { OnboardingProvider } from '@onboardjs/react'
3import { steps } from './onboarding-config' // Your config from the previous step
4import OnboardingUI from './onboarding-ui' // Your actual app content
5
6function App() {
7  return (
8    <OnboardingProvider steps={steps}>
9      <OnboardingUI />
10    </OnboardingProvider>
11  )
12}
13
14export 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  context, // The current onboarding context
13  payload,
14}) => {
15  const { next, updateContext } = useOnboarding()
16
17  const handleSubmit = () => {
18    // Simulate form submission
19    updateContext({ flowData: { profileComplete: true } })
20    next() // Proceed to the next step
21  }
22
23  return (
24    <div>
25      <h2>{payload?.title}</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

56 lines

1// src/components/onboarding/OnboardingFlow.tsx
2import { useOnboarding } from '@onboardjs/react'
3
4export const OnboardingUI = () => {
5  const {
6    currentStep,
7    state,
8    isLoading,
9    isCompleted,
10    next,
11    previous,
12    skip,
13    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>
52        Step {state.currentStepNumber} of {state.totalSteps}
53      </div>
54    </div>
55  )
56}

Key Concepts Recap

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