@get-asset/sdk

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 / 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

Prop	Type	Default	Description
`externalId`required	`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, 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.
`children`required	`ReactNode`	—	Compound parts.

Parts

Progress

Part	Description
`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).

Part	Description
`Onboarding.Plan`	State wrapper for the bookkeeping step.
`Onboarding.PlanOptions`	Iterates 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.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, 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.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.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.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

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