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

1import { OnboardingProvider } from '@onboardjs/react'
2
3<OnboardingProvider steps={steps} componentRegistry={componentRegistry}>
4  <OnboardingApp />
5</OnboardingProvider>

Props

Prop	Type	Description
`steps`	`OnboardingStep<TContext>[]`	Required. Array of onboarding steps.
`componentRegistry`	`{ [key: string]: React.ComponentType<any> }`	Required. Maps step types and ids to custom React components for rendering step content.
`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

29 lines

1import { OnboardingProvider } from '@onboardjs/react'
2
3const steps = [
4  {
5    id: 'welcome',
6    type: 'INFORMATION',
7    payload: { message: 'Welcome to our app!' },
8  },
9  {
10    id: 'setup',
11    type: 'SINGLE_CHOICE',
12    payload: { question: 'Choose your setup option' },
13  },
14  // ...other steps
15]
16
17const componentRegistry = {
18  INFORMATION: MyInfoComponent,
19  SINGLE_CHOICE: MyChoiceComponent,
20  // ...other mappings
21}
22
23function App() {
24  return (
25    <OnboardingProvider steps={steps} componentRegistry={componentRegistry}>
26      <MainOnboardingUI />
27    </OnboardingProvider>
28  )
29}

Example: With Local Storage Persistence

tsx

9 lines

1<OnboardingProvider
2  steps={steps}
3  localStoragePersistence={{
4    key: 'onboardjs:my-flow',
5    ttl: 7 * 24 * 60 * 60 * 1000, // 7 days in ms (optional)
6  }}
7>
8  <App />
9</OnboardingProvider>

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

tsx

45 lines

1<OnboardingProvider
2  steps={steps}
3  customOnDataLoad={async () => {
4    const { data } = await this.supabase
5      .from('onboarding_progress')
6      .select('*')
7      .eq('user_id', userId)
8      .single()
9
10    return {
11      flowData: data.flow_data || {},
12      currentStepId: data.current_step_id,
13      // Include any other context fields stored in Supabase
14      ...(data.context_data || {}),
15    }
16  }}
17  customOnDataPersist={async (context) => {
18    // Update in Supabase
19    const { data, error } = await supabase
20      .from('profiles')
21      .update({ onboarding_progress: progress })
22      .eq('id', userId)
23      .select('onboarding_progress')
24      .single()
25
26    if (error) {
27      throw new Error(`Failed to update onboarding: ${error.message}`)
28    }
29
30    return data.onboarding_progress
31  }}
32  customOnClearPersistedData={async () => {
33    // Clear onboarding data in Supabase
34    const { error } = await supabase
35      .from('profiles')
36      .update({ onboarding_progress: null })
37      .eq('user_id', userId)
38
39    if (error) {
40      throw new Error(`Failed to clear onboarding data: ${error.message}`)
41    }
42  }}
43>
44  <App />
45</OnboardingProvider>

Example: Custom Step Components

tsx

25 lines

1
2const steps = [
3  {
4    id: 'welcome',
5    type: 'INFORMATION',
6    payload: { message: 'Welcome to our app!' },
7  },
8  {
9    id: 'setup',
10    type: 'SINGLE_CHOICE',
11    payload: { question: 'Choose your setup option' },
12  },
13  // ...other steps
14]
15
16const componentRegistry = {
17  INFORMATION: MyInfoComponent, // Maps to step type
18  SINGLE_CHOICE: MyChoiceComponent, // Maps to step type
19  welcome: WelcomeComponent, // Maps to specific step ID
20  // ...other mappings
21}
22
23<OnboardingProvider steps={steps} componentRegistry={componentRegistry}>
24  <OnboardingApp />
25</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.
The componentRegistry allows you to define custom React components for rendering step content based on step type or ID.

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.