OnboardingExecutionFlow
Guided flow to onboard an employee.
Remarks
Drives the per-employee, admin-led onboarding steps used by OnboardingFlow and EmployeeManagement.EmployeeListFlow. (SelfOnboardingFlow is the separate employee-driven flow and runs its own state machine.) Each step is also exported as a standalone block (see the Blocks table) for composing a custom workflow when this orchestration is the wrong fit.
Self-onboarding statuses cause the federal-taxes, state-taxes, and payment-method steps to be skipped (the employee fills those in themselves); the documents step is also skipped unless withEmployeeI9 is true and the documents config has not yet been completed.
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.OnboardingExecutionFlow
companyId="a007e1ab-3595-43c2-ab4b-af7a5af2e365"
onEvent={(eventType: EventType) => {
if (eventType === 'employee/onboarding/done') {
// Onboarding complete — navigate to your next screen
}
}}
/>
)
}
OnboardingExecutionFlowProps
Props for OnboardingExecutionFlow.
| Property | Type | Description |
|---|---|---|
companyId | string | The associated company identifier. |
onEvent | OnEventType<EventType, unknown> | Callback invoked when the flow emits an event. |
defaultValues? | OnboardingDefaultValues | Default values for individual flow step components. |
initialEmployeeId? | string | The associated employee identifier to resume onboarding for. Omit to begin onboarding a new employee. |
initialOnboardingStatus? | "admin_onboarding_incomplete" | "self_onboarding_pending_invite" | "self_onboarding_invited" | "self_onboarding_invited_started" | "self_onboarding_invited_overdue" | "self_onboarding_completed_by_employee" | "self_onboarding_awaiting_admin_review" | "onboarding_completed" | The current onboarding status of the employee being onboarded. Drives skip behavior for self-onboarding and document steps. |
initialState? | "employeeProfile" | The step the flow starts on. Defaults to employeeProfile. |
isAdmin? | boolean | When true, the flow renders in the admin context. When false, it is configured for employee self-onboarding. Defaults to true. |
isSelfOnboardingEnabled? | boolean | When true, presents the self-onboarding toggle on the profile step. Defaults to true. |
withEmployeeI9? | boolean | When true, enables the Employee Documents step in the flow, allowing the admin to configure I-9 document requirements. Defaults to false. |
Sub-components
| Component | Description |
|---|---|
| Profile | Onboarding step for collecting an employee's basic profile and addresses. |
| Compensation | Onboarding step for collecting an employee's role and compensation details. |
| FederalTaxes | Onboarding step for collecting an employee's federal tax (W-4) withholdings — filing status, multiple-jobs flag, dependents, other income, deductions, and extra withholding. |
| StateTaxes | Onboarding step that collects an employee's per-state tax withholding answers. The set of fields is driven by the API response for each state on record. |
| PaymentMethod | Onboarding step for setting up an employee's payment method. |
| Deductions | Onboarding step for collecting an employee's post-tax deductions and court-ordered garnishments. |
| EmployeeDocuments | Onboarding step for selecting which documents the employee must complete. |
| OnboardingSummary | Displays a summary of an employee's onboarding status, listing completed and outstanding steps. Rendered as a standalone step inside OnboardingFlow. |
Step flow
OnboardingExecutionFlow runs the per-employee steps in order. After compensation, the path branches on the employee's self-onboarding status — set by the self-onboarding toggle the admin chooses on the Profile step, not by a flow prop:
- Admin onboarding — the admin completes every step, including federal taxes, state taxes, and payment method.
- Self-onboarding — the admin sets up the basics and the employee completes federal taxes, state taxes, and payment method themselves, so those three steps are skipped here.
The isSelfOnboardingEnabled prop only controls whether that toggle is offered: when false, the toggle is hidden and the flow always takes the admin path; when true (the default), the branch follows the admin's selection.
The documents step appears only when withEmployeeI9 is set.