OnboardJS

Headless onboarding engine for React and Next.js. Define multi-step flows as data, bring your own UI.

Live Demo

Features

• Headless: full control over UI and styling
• Declarative step definitions with conditional navigation
• Persistence hooks for localStorage, databases, or custom storage
• Built-in analytics and progress tracking
• Plugin system for extensibility
• TypeScript with strict typing
• Works with Next.js App Router and Pages Router

Installation

npm install @onboardjs/core @onboardjs/react

pnpm add @onboardjs/core @onboardjs/react
# or
yarn add @onboardjs/core @onboardjs/react

Quick Start

'use client'

import { OnboardingProvider, useOnboarding } from '@onboardjs/react'

function WelcomeStep() {
    return (
        <div>
            <h1>Welcome</h1>
            <p>Let's get you set up.</p>
        </div>
    )
}

function NameStep() {
    const { updateContext, state } = useOnboarding()

    return (
        <input
            placeholder="Your name"
            value={state.context.flowData.userName || ''}
            onChange={(e) => updateContext({ flowData: { userName: e.target.value } })}
        />
    )
}

const steps = [
    { id: 'welcome', component: WelcomeStep, nextStep: 'name' },
    { id: 'name', component: NameStep, nextStep: null },
]

function OnboardingUI() {
    const { state, next, previous, loading, renderStep } = useOnboarding()

    if (!state?.currentStep) return <p>Loading...</p>
    if (state.isCompleted) return <p>Done</p>

    return (
        <div>
            {renderStep()}
            <button onClick={() => previous()} disabled={!state.canGoPrevious}>
                Back
            </button>
            <button onClick={() => next()} disabled={!state.canGoNext || loading.isAnyLoading}>
                Next
            </button>
        </div>
    )
}

export default function App() {
    return (
        <OnboardingProvider steps={steps} localStoragePersistence={{ key: 'onboarding' }}>
            <OnboardingUI />
        </OnboardingProvider>
    )
}

See the package READMEs for full API documentation:

• @onboardjs/core - Headless engine
• @onboardjs/react - React bindings

Packages

This monorepo contains:

Package	Description
@onboardjs/core	Headless, framework-agnostic engine
@onboardjs/react	React hooks and provider
@onboardjs/visualizer	Visual flow builder component
apps/examples	Example applications

Development

git clone https://github.com/Somafet/onboardjs.git
cd onboardjs
pnpm install
pnpm build
pnpm test

Community

• GitHub Issues - Bug reports and feature requests
• Discord - Chat and support
• Documentation - Guides and API reference

Contributing

See CONTRIBUTING.md for setup instructions and guidelines.

License

MIT - see LICENSE.md