OnboardingProvider

The OnboardingProvider component is the entry point for integrating OnboardJS into your React application. It creates and manages the onboarding engine instance, provides onboarding state and actions via React context, and handles persistence and configuration.

Usage

Wrap your app (or any subtree that needs onboarding) with OnboardingProvider:

tsx

5 lines

import { OnboardingProvider } from '@onboardjs/react';

<OnboardingProvider steps={steps}>
  <App />
</OnboardingProvider>

Props

Prop	Type	Description
`steps`	`OnboardingStep<TContext>[]`	Required. Array of onboarding steps.
`initialStepId`	`string \| number`	Optional. ID of the step to start from.
`initialContext`	`Partial<TContext>`	Optional. Initial onboarding context.
`onFlowComplete`	`(context: TContext) => void \| Promise<void>`	Optional. Called when the onboarding flow is completed.
`onStepChange`	`(newStep, oldStep, context) => void`	Optional. Called after a step changes.
`onStepActive`	`(context: TContext) => void \| Promise<void>`	Optional. Called when a step becomes active.
`onStepComplete`	`(stepData: any, context: TContext) => void`	Optional. Called when a step is completed.
`localStoragePersistence`	`{ key: string; ttl?: number }`	Optional. Enables localStorage persistence with the given key and optional TTL (ms).
`customOnDataLoad`	`() => Promise<TContext> \| TContext`	Optional. Custom function to load persisted context.
`customOnDataPersist`	`(context: TContext) => Promise<void> \| void`	Optional. Custom function to persist context.
`customOnClearPersistedData`	`() => Promise<void> \| void`	Optional. Custom function to clear persisted data.
`children`	`React.ReactNode`	Required. The subtree that will have access to onboarding context.

Example: Basic Usage

tsx

10 lines

import { OnboardingProvider } from '@onboardjs/react';
import { steps } from './onboardingSteps';

function App() {
  return (
    <OnboardingProvider steps={steps}>
      <MainOnboardingUI />
    </OnboardingProvider>
  );
}

Example: With Local Storage Persistence

tsx

9 lines

<OnboardingProvider
  steps={steps}
  localStoragePersistence={{
    key: 'onboardjs:my-flow',
    ttl: 7 * 24 * 60 * 60 * 1000, // 7 days in ms (optional)
  }}
>
  <App />
</OnboardingProvider>

Example: Custom Persistence (e.g., Supabase)

tsx

24 lines

<OnboardingProvider
  steps={steps}
  customOnDataLoad={async () => {
    const { data } = await supabase
      .from('onboarding')
      .select('context')
      .eq('user_id', user.id)
      .single();
    return data?.context || undefined;
  }}
  customOnDataPersist={async (context) => {
    await supabase
      .from('onboarding')
      .upsert({ user_id: user.id, context });
  }}
  customOnClearPersistedData={async () => {
    await supabase
      .from('onboarding')
      .delete()
      .eq('user_id', user.id);
  }}
>
  <App />
</OnboardingProvider>

Example: Custom Step Components

tsx

11 lines

const componentRegistry = {
  INFORMATION: MyInfoComponent,
  SINGLE_CHOICE: MyChoiceComponent,
  welcome: WelcomeComponent,
  // ...other mappings
};

<OnboardingProvider steps={steps}>
  {/** You app using the component registry */}
  <App />
</OnboardingProvider>

Notes

The provider must wrap any component that uses the useOnboarding hook.
If you provide both localStoragePersistence and custom persistence handlers, the custom handlers take precedence.
You can use the onFlowComplete, onStepChange, and other event props to trigger side effects or analytics.

Summary

OnboardingProvider sets up the onboarding engine and context for your React app.
Supports flexible configuration, persistence, and custom step rendering.
Required for using the useOnboarding hook and accessing onboarding state/actions.

For more, see useOnboarding Hook and Rendering Step Content.