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

20 lines

import { useOnboarding } from '@onboardjs/react'

function OnboardingStep() {
  const { state, next, previous, skip, goToStep, updateContext } =
    useOnboarding()

  if (state.isCompleted) return <div>Onboarding complete!</div>

  return (
    <div>
      <button onClick={previous} disabled={!state.canGoPrevious}>
        Back
      </button>
      <button onClick={next} disabled={!state.canGoNext}>
        Next
      </button>
      {state.isSkippable && <button onClick={skip}>Skip</button>}
    </div>
  )
}

Return Value

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

Property/Action	Type / Signature	Description
`engine`	`OnboardingEngine<TContext>`	The underlying onboarding engine instance.
`state`	`EngineState<TContext>`	The current onboarding state (step, context, navigation flags, etc).
`isLoading`	`boolean`	`true` if the engine is loading or hydrating.
`currentStep`	`OnboardingStep<TContext> \| null \| undefined`	The current step object, `undefined` if not stated or `null` if finished.
`isCompleted`	`boolean`	`true` 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) => void`	Set a loading state for custom step components.

tsx

22 lines

function MyOnboarding() {
  const { state, next, previous, skip, updateContext } = useOnboarding()

  const handleChoice = async (choice: string) => {
    await updateContext({
      answers: { ...state.context.answers, step1: choice },
    })
    await next()
  }

  return (
    <div>
      <h2>{state.currentStep?.payload.question}</h2>
      <button onClick={() => handleChoice('A')}>A</button>
      <button onClick={() => handleChoice('B')}>B</button>
      <button onClick={previous} disabled={!state.canGoPrevious}>
        Back
      </button>
      {state.isSkippable && <button onClick={skip}>Skip</button>}
    </div>
  )
}

Example: Rendering Step Content

If you have a componentRegistry, you can use currentStep.id, currentStep.type or currentStep.payload.componentKey to automatically render the correct component for the current step:

tsx

27 lines

const componentRegistry = {
  INFORMATION: MyInfoComponent, // currentStep.type === 'INFORMATION'
  SINGLE_CHOICE: MyChoiceComponent,
  welcome: WelcomeComponent, // currentStep.id === 'welcome' || currentStep.payload.componentKey === 'welcome'
  // ...other mappings
}

function OnboardingUI() {
  const { renderStepContent, state, currentStep } = useOnboarding()

  if (state.isCompleted) return <div>All done!</div>

  const ComponentToRender =
    componentRegistry[
      currentStep.payload.componentKey ?? currentStep.id ?? currentStep.type
    ]

  if (!ComponentToRender) {
    return <div>Unknown step type: {currentStep.type}</div>
  }

  return (
    <div>
      <ComponentToRender payload={...} />
    </div>
  )
}

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).

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.

Usage

Return Value

Example: Custom Navigation

Example: Rendering Step Content

Notes

Summary