OnboardJS

React

useOnboarding Hook

The useOnboarding hook is the primary way to interact with the onboarding engine from your React components. It provides access to the current onboarding state, navigation actions, and utility functions for rendering step content and managing onboarding UI.

Usage

Call useOnboarding() inside any component wrapped by OnboardingProvider:

tsx
23 lines
1import { useOnboarding } from '@onboardjs/react'
2
3function OnboardingStep() {
4  const { state, next, previous, skip, goToStep, updateContext, renderStep } =
5    useOnboarding()
6
7  if (state.isCompleted) return <div>Onboarding complete!</div>
8
9  return (
10    <div>
11      <div>
12        {renderStep()}
13      </div>
14      <button onClick={previous} disabled={!state.canGoPrevious}>
15        Back
16      </button>
17      <button onClick={next} disabled={!state.canGoNext}>
18        Next
19      </button>
20      {state.isSkippable && <button onClick={skip}>Skip</button>}
21    </div>
22  )
23}

Return Value

The hook returns an object with the following properties and actions:

Property/ActionType / SignatureDescription
engineOnboardingEngine<TContext>The underlying onboarding engine instance.
stateEngineState<TContext>The current onboarding state (step, context, navigation flags, etc).
renderStep() => React.ReactNodeFunction to render the current step's content based on the component registry.
isLoadingbooleantrue if the engine is loading or hydrating.
currentStepOnboardingStep<TContext> | null | undefinedThe current step object, undefined if not stated or null if finished.
isCompletedbooleantrue if the onboarding flow is complete.
next(data?: any) => Promise<void>Advance to the next step. Optionally merge data into context.
previous() => Promise<void>Go to the previous step.
skip() => Promise<void>Skip the current step (if skippable).
goToStep(id: string | number, data?: any) => Promise<void>Jump to a specific step by ID. Optionally merge data into context.
updateContext(newContext: Partial<TContext>) => Promise<void>Merge new data into the onboarding context.
reset(newConfig?: Partial<OnboardingEngineConfig<TContext>>) => Promise<void>Reset the onboarding flow. Optionally provide new config.
setComponentLoading(isLoading: boolean) => voidSet a loading state for custom step components.

Example: Custom Navigation

tsx
25 lines
1function MyOnboarding() {
2  const { state, next, previous, skip, updateContext, renderStep } = useOnboarding()
3
4  const handleChoice = async (choice: string) => {
5    await updateContext({
6      answers: { ...state.context.answers, step1: choice },
7    })
8    await next()
9  }
10
11  return (
12    <div>
13      <h2>{state.currentStep?.payload.question}</h2>
14      <div>
15        {renderStep()}
16      </div>
17      <button onClick={() => handleChoice('A')}>A</button>
18      <button onClick={() => handleChoice('B')}>B</button>
19      <button onClick={previous} disabled={!state.canGoPrevious}>
20        Back
21      </button>
22      {state.isSkippable && <button onClick={skip}>Skip</button>}
23    </div>
24  )
25}

Example: Rendering Step Content

You must specify a componentRegistry for the OnboardingProvider to map step types or IDs to custom React components. This allows you to render different content for each step based on its type or ID.

tsx
18 lines
1const componentRegistry = {
2  INFORMATION: MyInfoComponent, // Maps to step type
3  SINGLE_CHOICE: MyChoiceComponent,
4  welcome: WelcomeComponent, // Maps to step ID
5  // ...other mappings
6}
7
8function OnboardingUI() {
9  const { renderStepContent, state, currentStep, renderStep } = useOnboarding()
10
11  if (state.isCompleted) return <div>All done!</div>
12
13  return (
14    <div>
15      {renderStep()}
16    </div>
17  )
18}

Notes

  • The hook must be used within a component tree wrapped by OnboardingProvider.
  • All navigation actions (next, previous, skip, goToStep) are async and return promises.
  • updateContext merges new data into the existing context; it does not replace it.
  • Use setComponentLoading to show loading states in custom step components (e.g., during async validation).
  • The renderStep function uses the componentRegistry to render the current step's content based on its type or ID.
  • If you need to access the onboarding engine instance directly, use the engine property.

Summary

  • useOnboarding gives you full access to onboarding state and actions in React.
  • Use it to drive navigation, update context, and render step content.
  • Integrates seamlessly with custom UIs and your component registry.

For more, see Rendering Step Content and Examples & Recipes.

Previous
Onboarding Provider
Next
Render step content