OnboardingCustom steps

Custom steps allow you to render any UI you want inside the onboarding flow while keeping the same navigation, persistence, and data handling.

You should only use custom steps when built-in step types are not sufficient.

When to use a custom step

Use a custom step if you need:

• A unique layout
• Complex interactions
• Multiple inputs on a single screen
• Custom animations or logic
• Third-party components

If your need fits a built-in step, prefer the built-in option.

How custom steps work

Custom steps rely on three elements:

1. A step config with type: "custom"
2. A React component implementing the step UI
3. Registration of that component in the onboarding registry

Step configuration

In your onboarding config:

tsx

The component value is a string key.

This key must match a registered custom component.

Creating a custom step component

Custom step components are regular React components.

They receive the same props as built-in steps, including:

• Navigation helpers
• Current step data
• Access to onboarding state

Example:

tsx

Registering the custom component

Custom steps must be registered in the onboarding step registry.

File location:

src/features/onboarding/step-component.tsx

Add your component to the customComponents map:

tsx

The key (profile_step) must match the component value used in the config.

Data handling in custom steps

Custom steps can:

• Write data using setData
• Read existing onboarding data
• Trigger navigation manually

Data written with setData is merged into userData, exactly like built-in steps.

Things to keep in mind

• Custom steps bypass built-in validation
• You are responsible for UX and accessibility
• Keep them focused and isolated
• Do not duplicate onboarding logic