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

24 lines

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

Example: Rendering Step Content

Check out the Defining steps page for how to create custom step components and use the component registry.

tsx

22 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
8...
9
10<OnboardingProvider componentRegistry={componentRegistry}>
11  <OnboardingUI />
12</OnboardingProvider>
13
14...
15
16function OnboardingUI() {
17  const { renderStepContent, state, currentStep, renderStep } = useOnboarding()
18
19  if (state.isCompleted) return <div>All done!</div>
20
21  return <div>{renderStep()}</div>
22}

Example: Updating the Context

tsx

25 lines

1function MyOnboarding() {
2  const { state, next, previous, skip, updateContext, renderStep } =
3    useOnboarding()
4
5  const handleChoice = (choice: string) => {
6    updateContext({
7      flowData: {
8        answers: { step1: choice },
9      },
10    })
11  }
12
13  return (
14    <div>
15      <h2>{state.currentStep?.payload.question}</h2>
16      <div>{renderStep()}</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}

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.

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).
`renderStep`	`() => React.ReactNode`	Function to render the current step's content based on the component registry.
`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.