@get-asset/sdk

AccountsList

Headless compound that fetches a business's connected external accounts and groups them by institution. Each group sorts its accounts by name; groups are sorted alphabetically. Each group is a collapsible summary row (GroupToggle, GroupStatus, GroupBalance); per-account parts expose the name, masked number, type, sync status and balance, plus a Disconnected gate wrapping a Reconnect action.

Anatomy

Import the primitive and compose the parts you need.

<AccountsList.Root onReconnect={reconnect}>
  <AccountsList.Success>
    <AccountsList.Groups>
      {/* Group summary row */}
      <AccountsList.GroupToggle>▾</AccountsList.GroupToggle>
      <AccountsList.GroupName />
      <AccountsList.GroupStatus />
      <AccountsList.GroupBalance />

      <AccountsList.Accounts>
        <AccountsList.Account>
          <AccountsList.AccountName />
          <AccountsList.AccountMask />
          <AccountsList.AccountStatus />
          <AccountsList.Balance />
          <AccountsList.Disconnected>
            <AccountsList.Reconnect>Reconnect</AccountsList.Reconnect>
          </AccountsList.Disconnected>
        </AccountsList.Account>
      </AccountsList.Accounts>
    </AccountsList.Groups>
  </AccountsList.Success>
  <AccountsList.Loading>…</AccountsList.Loading>
  <AccountsList.Empty>No accounts connected.</AccountsList.Empty>
</AccountsList.Root>

Required scopes

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

external_account:read
external_account:update
transaction:delete
ledger:read

API reference

Root props

Prop	Type	Default	Description
`institutionName`	`(account) => string \| null`	—	Override how an account maps to its institution group. Defaults to the account's institution_name, falling back to metadata_ then "Other accounts". Return null to use the fallback.
`source`	`ExternalAccountSource`	—	Filter by account source (manual / plaid / statements / gusto). Passed to the API.
`type`	`ExternalAccountType`	—	Filter by account type (business / personal). Passed to the API.
`status`	`ExternalAccountStatus`	—	Filter by account status (connected / disconnected / untracked). Passed to the API.
`onReconnect`	`(account) => void`	—	Invoked when a disconnected account's <Reconnect> part is clicked. Receives the raw account.
`accounts`	`ExternalAccountPublic[]`	—	Override fetched data — pass the API list as-is. Skips the API call.
`state`	`"loading" \| "error" \| "empty"`	—	Force a specific state for testing.
`children`required	`ReactNode`	—	Compound parts.

Parts

Container

Always rendered. Fetches accounts and provides context.

Part	Description
`AccountsList.Root`	Fetches external accounts, groups them by institution and provides context.

Success

Renders when at least one account is available.

Part	Description
`AccountsList.Success`	State wrapper. Compose the grouped table inside.
`AccountsList.Groups`	Iterates each institution group, providing a group context and tracking per-group collapse state.
`AccountsList.GroupName` `asChild?`	Renders the current group's institution name.
`AccountsList.GroupToggle` `asChild?`	Button that collapses/expands the group. Sets aria-expanded and data-collapsed (for styling a chevron). While collapsed, <Accounts> renders nothing.
`AccountsList.GroupStatus` `asChild?, format?`	Renders the group's rolled-up status (connected if any account is, else disconnected, else paused) and sets data-status. Connected groups show the most recent sync time.
`AccountsList.GroupBalance` `asChild?, format?`	Renders the sum of the group's account balances.
`AccountsList.Accounts`	Iterates the current group's accounts (nothing while collapsed). Must be used inside <Groups> (throws otherwise). Provides an account context to each iteration.
`AccountsList.Account` `asChild?`	Per-account row wrapper. Sets data-type, data-status and data-disconnected attributes from the account.
`AccountsList.AccountName` `asChild?`	Renders the account name (falls back to "Unnamed account").
`AccountsList.AccountMask` `asChild?, format?`	Renders the account mask (e.g. last four digits). Pass format(mask) to decorate it; mask may be null.
`AccountsList.AccountStatus` `asChild?, format?`	Renders the account's status and sets data-status. Connected accounts show a relative sync time ("2h ago"); others show "Disconnected"/"Paused". Pass format(status, lastSyncedAt) to override.
`AccountsList.AccountType` `asChild?, format?`	Renders the account type. Defaults to "Business"/"Personal" and sets data-type on the element.
`AccountsList.LastSynced` `asChild?, format?`	Renders the last-synced timestamp as an absolute date ("Mon DD, YYYY", or "Never synced"). Pass format(date \| null) to override.
`AccountsList.Balance` `asChild?, format?`	Renders the account's external balance. Renders nothing when the balance is unknown (null).
`AccountsList.Disconnected`	Per-account state gate. Renders its children only when the account is disconnected.
`AccountsList.Connected`	Inverse of Disconnected — renders only for connected accounts.
`AccountsList.Reconnect` `asChild?`	Button that calls Root's onReconnect with the current account. Renders nothing unless the account is disconnected and has a linked_item_id (Plaid update mode).
`AccountsList.Business`	Per-account gate. Renders only for business accounts.
`AccountsList.Personal`	Per-account gate. Renders only for personal accounts.
`AccountsList.Paused`	Per-account gate. Renders only for a paused synced account (status untracked). Never renders for manual accounts, which have nothing to sync.
`AccountsList.Syncing`	Per-account gate. Renders only for an actively-syncing account. Like Paused, it is sync-specific and never renders for manual accounts.
`AccountsList.Editing` `editor`	Per-account gate. Renders only while this account's inline editor of the given kind is open — editor="switch-personal" for the ledger editor, editor="delete" for the delete confirmation. Open via edit(account, editor); compose the editor UI and the actions (cancelEdit / switchToPersonal / deleteAccount) inside.
`AccountsList.Synced`	Per-account source gate. Renders only for externally-synced accounts (anything but manual) — compose sync-specific UI here (last-synced time, pause/resume). For a specific source use Source instead.
`AccountsList.Source` `value`	Per-account source gate — renders only when the account's source matches value. Pass a single source (value="plaid" / value="manual") or an array to match any of several (value={["plaid", "gusto"]}). This is the per-source gate; new sources need no new component.

Loading

Renders while the fetch is in flight.

Part	Description
`AccountsList.Loading`	State wrapper. Render any skeleton or placeholder UI inside.

Empty

Renders when no accounts are connected.

Part	Description
`AccountsList.Empty`	State wrapper. Render an empty-state message inside.

Error

Renders on fetch error.

Part	Description
`AccountsList.Error`	State wrapper. Compose the error UI inside.
`AccountsList.ErrorMessage` `asChild?`	Renders the error message string.
`AccountsList.Retry` `asChild?`	Button that re-runs the fetch.

Hooks

Part	Description
`useAccountsList()`	Hook returning groups, accounts, hasData, loading, error, retry, onReconnect, plus per-account actions: pauseSync, resumeSync, deleteAccount, switchToBusiness, switchToPersonal(account, { contributionLedgerId, distributionLedgerId }), actionPending, and the inline row editors — editing ({ account, editor } \| null), edit(account, editor) and cancelEdit open/close the switch-to-personal ("switch-personal") or delete ("delete") editor, with ledgers / ledgersLoading for the switch form. Each action mutates via the API and refetches the list.
`useAccountsListGroup()`	Hook used inside a Groups iteration; returns the current group ({ institution, accounts }).
`useAccountsListAccount()`	Hook used inside an Accounts iteration; returns the current account node ({ account, institution, status, isDisconnected, canReconnect, isBusiness, isPersonal, isPaused, source, isManual, isPlaid, isSynced }).