OnboardingFlow
Guided flow to onboard multiple employees, one at a time.
Remarks
Renders a multi-step experience that collects every piece of information required to add an employee to payroll. Begins on the employee list and transitions into the onboarding execution flow when "Add employee" or a row's "Edit"/"Review" action is invoked; returning from the execution flow surfaces the list again. The flow is driven by an internal state machine and wraps each step in error and suspense boundaries.
The per-employee steps live in OnboardingExecutionFlow, which is also exported as a standalone block — along with each individual step — for composing a custom workflow when this orchestration is the wrong fit. See the Composition guide for how to recompose these blocks into your own flow.
The flow forwards every event emitted by its blocks to onEvent;
see the events table on each block for the full set of events and
payloads observable from this flow.
Example
import { EmployeeOnboarding, type EventType } from '@gusto/embedded-react-sdk'
function MyApp() {
return (
<EmployeeOnboarding.OnboardingFlow
companyId="a007e1ab-3595-43c2-ab4b-af7a5af2e365"
withEmployeeI9
onEvent={(eventType: EventType) => {
if (eventType === 'employee/onboarding/done') {
// Onboarding complete — navigate to your next screen
}
}}
/>
)
}
OnboardingFlowProps
Props for OnboardingFlow.
| Property | Type | Default value | Description |
|---|---|---|---|
companyId | string | The associated company identifier. | |
onEvent | OnEventType<EventType, unknown> | Callback invoked each time the component emits an event — user interactions, successful API responses, step transitions, or errors. Receives the event type constant and an optional payload whose shape varies by event. See the Event Handling guide and each component's event table for the full list of emitted events. | |
defaultValues? | RequireAtLeastOne<OnboardingDefaultValues> | Default values for individual flow step components. | |
isSelfOnboardingEnabled? | boolean | When true, presents the self-onboarding toggle allowing the admin to opt the employee into self-onboarding. When false, the option to self-onboard is not available. Defaults to true. | |
showContinueButton? | boolean | false | Controls visibility of the Continue button in the employee list. When true, shows a Continue button allowing navigation to the next step. Use this when the employee onboarding flow is embedded as a step within a larger flow (e.g., company onboarding). When false (default), hides the Continue button. Use this for standalone employee onboarding where the list is the terminal screen. |
withEmployeeI9? | boolean | When true, enables the Employee Documents step in the onboarding flow, allowing the admin to configure I-9 document requirements. Defaults to false. |
Inherits children, className, dictionary, FallbackComponent, LoaderComponent from BaseComponentInterface.
Sub-components
| Component | Description |
|---|---|
| EmployeeList | Renders a paginated list of a company's employees with per-row onboarding actions (edit, delete, review, cancel self-onboarding) and an "Add employee" entry point. |
| OnboardingExecutionFlow | Guided flow to onboard an employee. |
Step flow
OnboardingFlow pairs the employee list with OnboardingExecutionFlow. Adding or editing a list row runs the per-employee onboarding steps; finishing an employee returns to the list, and completing onboarding exits the flow. The step sequence — which varies with self-onboarding and withEmployeeI9 — is covered on OnboardingExecutionFlow.