Onboarding
Headless compound for a self-contained business-onboarding wizard. It owns the step machine, the collected values and the business:create mutation, and exposes a slot for every element. Steps collect a bookkeeping plan, company details and a books start date, then create the business; the final Connect step is where you connect accounts against the new business — the styled drop-in does this with a single PlaidLink card plus a read-only AccountsList. On creation it calls setBusinessId on the surrounding AssetProvider, which re-provisions a business-scoped token — so no second provider is needed. Supply a single entry in plans and the bookkeeping step is skipped and that plan submitted automatically.
Anatomy
Import the primitive and compose the parts you need.
<Onboarding.Root externalId={externalId} plans={["diy", "managed"]} onComplete={done}> <Onboarding.StepTitle /> <Onboarding.StepCounter /> <Onboarding.ProgressBar /> <Onboarding.Plan> <Onboarding.PlanOptions> <Onboarding.PlanOptionTrigger> <Onboarding.PlanOptionTitle /> <Onboarding.PlanOptionDescription /> </Onboarding.PlanOptionTrigger> </Onboarding.PlanOptions> <Onboarding.Next>Next</Onboarding.Next> </Onboarding.Plan> <Onboarding.Details> {/* read useOnboarding() for name / entityType / industry / homeCurrency / fiscalYear fields */} <Onboarding.Previous>Previous</Onboarding.Previous> <Onboarding.Next>Next</Onboarding.Next> </Onboarding.Details> <Onboarding.StartDate> <Onboarding.StartDateOptions> <Onboarding.StartDateOptionTrigger> <Onboarding.StartDateOptionTitle /> <Onboarding.StartDateOptionRecommended>Recommended</Onboarding.StartDateOptionRecommended> <Onboarding.StartDateOptionDescription /> </Onboarding.StartDateOptionTrigger> </Onboarding.StartDateOptions> <Onboarding.Next>Next</Onboarding.Next> </Onboarding.StartDate> <Onboarding.Creating>Setting up your books…</Onboarding.Creating> <Onboarding.Error><Onboarding.Retry>Try again</Onboarding.Retry></Onboarding.Error> <Onboarding.Connect> {/* connect accounts against useOnboarding().businessId */} <Onboarding.Skip>Skip for now</Onboarding.Skip> <Onboarding.Complete>Finish up</Onboarding.Complete> </Onboarding.Connect></Onboarding.Root>Required scopes
The access token used by AssetProvider must include these scopes for this primitive to fetch data successfully:
business:createplaid:createplaid:readledger:readtransaction:create
API reference
Root props
| Prop | Type | Default | Description |
|---|---|---|---|
externalIdrequired | string | — | Your stable identifier stored against the created business. Required by the create endpoint. |
plans | BusinessPlan[] | — | Plans offered on the bookkeeping step. Defaults to ["diy", "managed"]. With one entry the step is skipped and that plan is submitted. |
entityTypes | BusinessEntityType[] | — | Override the filing types offered. Defaults to every entity type. |
industries | string[] | — | Override the industries offered. |
defaultValues | OnboardingDefaults | — | Pre-populate any form field (plan, name, entityType, industry, homeCurrency, fiscalYearMode, fiscalYearDate, startDateMode, specificStartDate). Each seeds the field's initial value; the user can still change it. |
status | BusinessStatus | — | Initial business status. Forwarded to the create request when set. |
onCreated | (business) => void | — | Called once the business is created, before the connect step shows. |
onComplete | (business, reason: "finished" | "skipped") => void | — | Called when the user finishes on the last step. reason is "finished" for Finish up or "skipped" for Skip for now. |
onError | (error) => void | — | Called if creating the business fails. |
state | "creating" | "error" | — | Force a state for testing/storybook. |
initialStep | OnboardingStep | — | Start on a specific step (testing/storybook). |
initialCreated | BusinessPublic | null | — | Seed a created business so the connect step can be previewed offline. |
childrenrequired | ReactNode | — | Compound parts. |
Parts
Progress
| Part | Description |
|---|---|
Onboarding.StepTitleasChild? | The current step's title (Bookkeeping, Company details, …). |
Onboarding.StepCounterasChild? | The "1/4" step counter (adapts to the step count). |
Onboarding.ProgressBarasChild? | Progress fill — sets style.width and data-ratio. |
Plan
Renders on the bookkeeping step (omitted when one plan).
| Part | Description |
|---|---|
Onboarding.Plan | State wrapper for the bookkeeping step. |
Onboarding.PlanOptions | Iterates the offered plans, providing a per-plan context. |
Onboarding.PlanOptionTriggerasChild? | Selects the current plan. Sets data-plan and data-selected. |
Onboarding.PlanOptionTitleasChild? | The plan's title. |
Onboarding.PlanOptionDescriptionasChild? | The plan's description. |
Onboarding.PlanOptionSelected | Renders its children only for the selected plan. |
Details
Company-details step. Bind the fields via useOnboarding().
| Part | Description |
|---|---|
Onboarding.Details | State wrapper. Read name/setName, entityType/setEntityType, entityTypes, industry/setIndustry, industries, homeCurrency/setHomeCurrency, currencies, fiscalYearMode/setFiscalYearMode, fiscalYearDate/setFiscalYearDate from useOnboarding(). |
StartDate
Books start-date step.
| Part | Description |
|---|---|
Onboarding.StartDate | State wrapper for the start-date step. |
Onboarding.StartDateOptions | Iterates the three start-date options (this/last financial year, specific date). |
Onboarding.StartDateOptionTriggerasChild? | Selects the current option. Sets data-start-date and data-selected. |
Onboarding.StartDateOptionTitleasChild? | The option's title. |
Onboarding.StartDateOptionDescriptionasChild? | The computed sub-label, e.g. "Books from Jan 2026 · about 5 months". |
Onboarding.StartDateOptionRecommended | Renders its children only for the recommended option. |
Onboarding.StartDateOptionSelected | Renders its children only for the selected option (e.g. the date input). |
Creating / Connect
| Part | Description |
|---|---|
Onboarding.Creating | Renders while the business is being created. |
Onboarding.Connect | Renders the final connect-accounts step. Connect against useOnboarding().businessId. |
Onboarding.Error | Renders when business creation failed. |
Navigation
| Part | Description |
|---|---|
Onboarding.NextasChild? | Advances the flow; creates the business on the start-date step. Disabled until the current step is valid. |
Onboarding.PreviousasChild? | Steps back. Disabled on the first step. |
Onboarding.CompleteasChild? | Finishes the flow with reason "finished" — wire to Finish up. |
Onboarding.SkipasChild? | Finishes the flow with reason "skipped" — wire to Skip for now. |
Onboarding.RetryasChild? | Retries business creation after an error. |
Hooks
| Part | Description |
|---|---|
useOnboarding() | Returns the full step machine (steps, step, stepIndex, progress, canAdvance, next/previous/goTo), every collected field + setter, the derived fiscalYear / entriesStart / startDateOptions, and creation state (creating, createError, created, businessId, retryCreate, complete). |