PayrollFlow
Hub for running and managing all payrolls across a company's pay schedules.
Remarks
Renders the payroll landing page and orchestrates the full run-payroll experience: selecting a payroll, configuring earnings and reimbursements, reviewing totals, submitting, and viewing receipts. Off-cycle, transition, and edit-employee steps are reachable from the same flow.
Example
import { Payroll } from '@gusto/embedded-react-sdk'
function RunPayrollPage() {
return <Payroll.PayrollFlow companyId="a007e1ab-3595-43c2-ab4b-af7a5af2e365" onEvent={() => {}} />
}
PayrollFlowProps
Props accepted by PayrollFlow.
| Property | Type | Description |
|---|---|---|
companyId | string | Identifier of the company whose payroll is being run. |
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. |
ConfirmWireDetailsComponent? | ConfirmWireDetailsComponentType | Optional custom component that replaces the default wire-details confirmation UI. |
withReimbursements? | boolean | Whether reimbursement fields are shown in the payroll configuration and overview. Defaults to true. |
Inherits children, className, defaultValues, dictionary, FallbackComponent, LoaderComponent from BaseComponentInterface.
Events
| Event | Description | Data |
|---|---|---|
runPayroll/selected | A payroll is selected to run | { payrollId: string } |
payroll/review | A calculated payroll is opened for review | { payrollId: string } |
runPayroll/calculated | Payroll calculations complete | — |
runPayroll/edit | The user returns to configuration to make changes | — |
runPayroll/employee/edit | An employee row is opened for editing | { employeeId: string, firstName: string, lastName: string } |
runPayroll/employee/saved | Employee payroll changes are saved | { payrollPrepared: object, employee: object } |
runPayroll/employee/cancelled | Employee editing is cancelled | — |
runPayroll/submitted | Payroll is successfully submitted | Response from the submit payroll endpoint |
runPayroll/processed | Payroll processing completes | — |
runPayroll/processingFailed | Payroll processing fails | Error details |
runPayroll/cancelled | A submitted payroll is cancelled | { payrollId: string, result: object } |
runPayroll/summary/viewed | The summary screen is opened | { payrollId: string } |
runPayroll/receipt/viewed | The receipt screen is opened | { payrollId: string } |
runPayroll/offCycle/start | The user starts an off-cycle payroll | — |
transition/runPayroll | The user starts a pending transition payroll | — |
payroll/saveAndExit | The user clicks Save and Exit | — |
Sub-components
| Component | Description |
|---|---|
| PayrollLanding | Main landing surface for payroll operations, with tabs for running payroll and viewing payroll history, plus inline navigation to a payroll's overview and receipt. |
| PayrollExecutionFlow | Guided flow to configure, review, and submit a single payroll. |
| OffCycleFlow | Guided flow to create and run a bonus or correction payroll. |
| TransitionFlow | Guided flow to run a transition payroll when employees move from one pay schedule to another. |
| PayrollBlockerList | Displays the list of blockers preventing payroll from being processed for a company. |
| PayrollOverview | Final review screen for a calculated payroll before submission, with submit, cancel, and edit controls. After submission, tracks processing status and surfaces the receipt and per-employee paystub downloads once complete. |
| PayrollReceipts | Displays a detailed receipt for a completed payroll, including the debited total, per-category breakdown, tax breakdown, and a per-employee summary of payment method, garnishments, reimbursements, taxes, and net pay. |
Step flow
PayrollFlow opens on the landing page (PayrollLanding), which lists pending and calculated payrolls and acts as the hub: every path launches from it and returns to it, so the flow has no terminal step. Selecting a payroll to run (runPayroll/selected) or reviewing a calculated one (payroll/review) hands off to PayrollExecutionFlow; starting an off-cycle payroll (runPayroll/offCycle/start) or a pending transition payroll (transition/runPayroll) hands off to OffCycleFlow or TransitionFlow; and viewing all blockers (runPayroll/blockers/viewAll) opens PayrollBlockerList.
When any run path finishes processing (runPayroll/processed), the flow lands on the submitted overview (PayrollOverview), which can drill into receipts (runPayroll/receipt/get → PayrollReceipts). Returning to the landing hub happens via the breadcrumb header (breadcrumb/navigate) or Save & exit (payroll/saveAndExit) — here both are handled internally, returning to landing rather than exiting. A submitted payroll that is later cancelled (runPayroll/cancelled) also returns to landing, where a cancellation alert is shown.