Rendering Step Component

OnboardJS is headless by design, meaning you have full control over how each onboarding step is rendered. The React SDK makes it easy to map steps to custom components, allowing you to create a tailored user experience.

How Step Rendering Works

You can render each step in your onboarding flow in two main ways:

Each step in your onboarding flow can be associated with a custom React component.
You can define a component registry that maps step IDs or step types to specific components.

1. Component in Step Config

You can specify the component to render for each step right in your step definition:

tsx

14 lines

1// import the type from the React SDK instead of the core SDK
2import type { OnboardingStep } from '@onboardjs/react'
3import InitialStep from './steps/initial-step'
4
5const initialStep: OnboardingStep = {
6  id: 'initial',
7  // Using the React specific OnboardingStep type to define the step component right in the step definition
8  component: InitialStep,
9
10  meta: {
11    title: 'Unlock your tailored OnboardJS experience!',
12    subtitle: 'Which best describes your goal?',
13  },
14}

This allows you to directly associate a React component with each step, making it easy to manage your onboarding flow.

2. Using a Component Registry

You can also create a component registry that maps step IDs to components. This is useful for larger applications where you want to keep your step definitions clean and separate from the rendering logic or when you want to assign a component based on the step type.

tsx

28 lines

1import { OnboardingStep } from '@onboardjs/core'
2import InformationStep from './steps/information-step'
3
4const componentRegistry = {
5  // Specify the component based on the step type
6  INFORMATION: InformationStep,
7}
8
9const steps: OnboardingStep[] = [
10  {
11    id: 'initial',
12    type: 'INFORMATION',
13    component: 'initial', // Reference by ID
14    meta: {
15      title: 'Unlock your tailored OnboardJS experience!',
16      subtitle: 'Which best describes your goal?',
17    },
18  },
19  {
20    id: 'another',
21    type: 'INFORMATION',
22    component: 'another', // Reference by ID
23    meta: {
24      title: 'Another Step',
25      subtitle: 'This is another step in the onboarding process.',
26    },
27  },
28]

Step Component Props

Each step component receives the following props:

tsx

10 lines

1import type { StepComponentProps } from '@onboardjs/react'
2
3interface StepComponentProps<TPayload = any, TContext = any> {
4  payload: TPayload
5  /**
6   * The full context of the current onboarding session.
7   * This includes any data collected so far, such as answers to previous steps.
8   */
9  context: TContext
10}

This gives your components full access to the current step's payload and the overall context of the onboarding session, allowing you to build dynamic and responsive UIs.

Example: Custom Step Component

tsx

21 lines

1type YourPayload = {
2  title: string
3}
4
5function MyCustomComponent({
6  payload,
7  context,
8}: StepComponentProps<YourPayload>) {
9  const { updateContext, next } = useOnboarding()
10
11  const handleSubmit = async () => {
12    updateContext({ flowData: { answers: { custom: true } } })
13  }
14
15  return (
16    <div>
17      <h2>{payload.title}</h2>
18      <button onClick={handleSubmit}>Send</button>
19    </div>
20  )
21}

Rendering the Current Step

You can use the renderStep function from the useOnboarding hook to automatically render the current step's component based on the step ID or type defined in your onboarding configuration.

tsx

17 lines

1export default function OnboardingUI() {
2  const { state, currentStep, renderStep } = useOnboarding()
3
4  if (!state) {
5    return <Loading />
6  }
7
8  if (!currentStep) {
9    return (
10      <div className="p-10 text-center text-gray-500">
11        No active onboarding step.
12      </div>
13    )
14  }
15
16  return <>{renderStep()}</>
17}

Fallbacks and Error Handling

You can customize an OnboardingUI component to handle errors gracefully, such as logging or showing a user-friendly message.

Summary

renderStep() automatically renders the correct component for the current step.
Step components receive full context and payloads as props.
Customize your onboarding UI freely—OnboardJS handles the logic, you handle the presentation.

For more, see useOnboarding Hook and Examples & Recipes.