Skip to Content
@get-asset/sdkComponents

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:create
  • plaid:create
  • plaid:read
  • ledger:read
  • transaction:create

API reference

Root props

PropTypeDefaultDescription
externalIdrequiredstring—Your stable identifier stored against the created business. Required by the create endpoint.
plansBusinessPlan[]—Plans offered on the bookkeeping step. Defaults to ["diy", "managed"]. With one entry the step is skipped and that plan is submitted.
entityTypesBusinessEntityType[]—Override the filing types offered. Defaults to every entity type.
industriesstring[]—Override the industries offered.
defaultValuesOnboardingDefaults—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.
statusBusinessStatus—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.
initialStepOnboardingStep—Start on a specific step (testing/storybook).
initialCreatedBusinessPublic | null—Seed a created business so the connect step can be previewed offline.
childrenrequiredReactNode—Compound parts.

Parts

Progress

PartDescription
Onboarding.StepTitle
asChild?
The current step's title (Bookkeeping, Company details, …).
Onboarding.StepCounter
asChild?
The "1/4" step counter (adapts to the step count).
Onboarding.ProgressBar
asChild?
Progress fill — sets style.width and data-ratio.

Plan

Renders on the bookkeeping step (omitted when one plan).

PartDescription
Onboarding.PlanState wrapper for the bookkeeping step.
Onboarding.PlanOptionsIterates the offered plans, providing a per-plan context.
Onboarding.PlanOptionTrigger
asChild?
Selects the current plan. Sets data-plan and data-selected.
Onboarding.PlanOptionTitle
asChild?
The plan's title.
Onboarding.PlanOptionDescription
asChild?
The plan's description.
Onboarding.PlanOptionSelectedRenders its children only for the selected plan.

Details

Company-details step. Bind the fields via useOnboarding().

PartDescription
Onboarding.DetailsState wrapper. Read name/setName, entityType/setEntityType, entityTypes, industry/setIndustry, industries, homeCurrency/setHomeCurrency, currencies, fiscalYearMode/setFiscalYearMode, fiscalYearDate/setFiscalYearDate from useOnboarding().

StartDate

Books start-date step.

PartDescription
Onboarding.StartDateState wrapper for the start-date step.
Onboarding.StartDateOptionsIterates the three start-date options (this/last financial year, specific date).
Onboarding.StartDateOptionTrigger
asChild?
Selects the current option. Sets data-start-date and data-selected.
Onboarding.StartDateOptionTitle
asChild?
The option's title.
Onboarding.StartDateOptionDescription
asChild?
The computed sub-label, e.g. "Books from Jan 2026 · about 5 months".
Onboarding.StartDateOptionRecommendedRenders its children only for the recommended option.
Onboarding.StartDateOptionSelectedRenders its children only for the selected option (e.g. the date input).

Creating / Connect

PartDescription
Onboarding.CreatingRenders while the business is being created.
Onboarding.ConnectRenders the final connect-accounts step. Connect against useOnboarding().businessId.
Onboarding.ErrorRenders when business creation failed.

Navigation

PartDescription
Onboarding.Next
asChild?
Advances the flow; creates the business on the start-date step. Disabled until the current step is valid.
Onboarding.Previous
asChild?
Steps back. Disabled on the first step.
Onboarding.Complete
asChild?
Finishes the flow with reason "finished" — wire to Finish up.
Onboarding.Skip
asChild?
Finishes the flow with reason "skipped" — wire to Skip for now.
Onboarding.Retry
asChild?
Retries business creation after an error.

Hooks

PartDescription
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).

On this page