@get-asset/sdk

PlaidLink

Headless wrapper around react-plaid-link that drives Plaid Link end-to-end against the Asset API. Calling connect(account?) creates a link_token (POST /plaid-link-token, update mode when an account is passed), opens Link, and on success exchanges the result via POST /link-institutions. No backend wiring of your own is required — just an AssetProvider with the plaid:create scope.

Anatomy

Import the primitive and compose the parts you need.

<PlaidLink.Root onConnected={() => refetchAccounts()}>
  <PlaidLink.Trigger>Connect account</PlaidLink.Trigger>
  <PlaidLink.Loading>Starting…</PlaidLink.Loading>
  <PlaidLink.Error>
    <PlaidLink.ErrorMessage />
  </PlaidLink.Error>
</PlaidLink.Root>

Required scopes

The access token used by AssetProvider must include this scope for this primitive to fetch data successfully:

plaid:create

API reference

Root props

Prop	Type	Default	Description
`onConnected`	`(institutions, account) => void`	—	Called once accounts are linked on the Asset API. account is the reconnected account, or null for a new connection.
`confirm`	`boolean`	—	Defer linking: on Plaid success, expose the result as `pending` (via usePlaidLink) instead of calling link-institutions immediately. Render a confirmation step and call linkInstitutions(accounts) once accounts are assigned business/personal. Default false.
`onError`	`(error) => void`	—	Called if creating the link token or finalising the connection fails.
`onExit`	`PlaidLinkOnExit`	—	Forwarded to Plaid Link — called when the user exits the flow.
`onEvent`	`PlaidLinkOnEvent`	—	Forwarded to Plaid Link — called on each Link event.
`state`	`"loading" \| "error"`	—	Force a specific state for testing/storybook.
`children`required	`ReactNode`	—	Compound parts.

Parts

Container

Always rendered. Manages the token lifecycle and provides context.

Part	Description
`PlaidLink.Root`	Owns the Plaid Link handler, link-token creation and the link-institutions exchange.
`PlaidLink.Trigger` `asChild?`	Button that calls connect(null) to start a new connection. Disabled while a token is being created.

Loading

Renders while a link token is being created or the connection is being finalised.

Part	Description
`PlaidLink.Loading`	State wrapper. Render a spinner or placeholder inside.

Error

Renders when token creation or linking fails.

Part	Description
`PlaidLink.Error`	State wrapper. Compose the error UI inside.
`PlaidLink.ErrorMessage` `asChild?`	Renders the error message string.

Confirm

Renders while a connection awaits confirmation (confirm mode only).

Part	Description
`PlaidLink.Pending`	State wrapper. Renders its children when a connection is staged for confirmation. Read usePlaidLink().pending for the institution + accounts, then call linkInstitutions(accounts) to finalise.

Hooks

Part	Description
`usePlaidLink()`	Hook returning connect(account?), ready, loading, error, plus pending / linkInstitutions(accounts) / cancelPending for confirm mode. Use connect(account) to reconnect a specific account; on a successful connection the SDK invalidates the accounts query so a mounted <AccountsList> background-refetches automatically.