Skip to Content
@get-asset/sdkComponents

Chart of Accounts

Headless compound for the business's chart of accounts. It lists every ledger parent over child, ordered by sort code, under a type filter. CreateTrigger toggles a draft for a new top-level ledger, the way Add account reveals its panel. A click on a row opens its ledger's details in place, read-only (show them as text with DraftValue), and EditDetails turns them into the edit draft. EditTrigger opens the same draft ready to edit, AddChildTrigger opens it for a child that inherits from its parent, and DeleteTrigger asks for confirmation before it deletes. One thing is open at a time.

Anatomy

Import the primitive and compose the parts you need.

<ChartOfAccounts.Root  // Optional. Without it there's no View report.  onViewAccount={({ ledgerId }) => router.push(`/reports/ledger-statement/${ledgerId}`)}>  {/* Header controls */}  <ChartOfAccounts.TypeFilter>    <Select> {/* any Select-Root-shaped child */}      <ChartOfAccounts.TypeFilterItems>        <ChartOfAccounts.TypeFilterItem />      </ChartOfAccounts.TypeFilterItems>    </Select>  </ChartOfAccounts.TypeFilter>  <ChartOfAccounts.CreateTrigger />  {/* The create draft for a top-level ledger, revealed under the header */}  <ChartOfAccounts.Create>    <LedgerFields />  </ChartOfAccounts.Create>  <ChartOfAccounts.ActionError />  <ChartOfAccounts.Loading>{/* skeleton rows */}</ChartOfAccounts.Loading>  <ChartOfAccounts.Error>    <ChartOfAccounts.ErrorMessage />    <ChartOfAccounts.Retry />  </ChartOfAccounts.Error>  <ChartOfAccounts.Empty>{/* empty copy */}</ChartOfAccounts.Empty>  <ChartOfAccounts.Success>    <ChartOfAccounts.Rows>      {/* Spread useRowProps() on the row for data-depth and data-open. */}      <ChartOfAccounts.ChildMarker>{/* ↳ */}</ChartOfAccounts.ChildMarker>      <ChartOfAccounts.SortCode />      <ChartOfAccounts.Name />      <ChartOfAccounts.Type />      <ChartOfAccounts.Subtype />      <ChartOfAccounts.TaxCategory />      <ChartOfAccounts.ViewAccountTrigger />      <ChartOfAccounts.EditTrigger />      <ChartOfAccounts.AddChildTrigger />      <ChartOfAccounts.DeleteTrigger />      {/* A click on the row opens its details read-only; the actions open          it to act on its ledger. Gate the expansion on useRowExpanded().          One thing is open at a time. */}      {/* Delete asks first, in the row it was chosen from (or use the          root-level DeleteConfirm) */}      <ChartOfAccounts.Deleting>        <ChartOfAccounts.DeleteTargetName />        <ChartOfAccounts.CancelDelete />        <ChartOfAccounts.ConfirmDelete />      </ChartOfAccounts.Deleting>      {/* The details show each field as text (DraftValue); EditDetails          swaps them for the edit draft. An edit and a new child open the          fields in the row. */}      <ChartOfAccounts.Viewing>        <ChartOfAccounts.DraftValue field="name" />        <ChartOfAccounts.DraftValue field="debitCredit" />        {/* …one per field */}        <ChartOfAccounts.CancelDraft />        <ChartOfAccounts.EditDetails />      </ChartOfAccounts.Viewing>      <ChartOfAccounts.Editing>        <LedgerFields />      </ChartOfAccounts.Editing>      <ChartOfAccounts.AddingChild>        <LedgerFields />      </ChartOfAccounts.AddingChild>    </ChartOfAccounts.Rows>  </ChartOfAccounts.Success></ChartOfAccounts.Root>/* One set of fields serves create, add child and edit: */function LedgerFields() {  return (    <>      <ChartOfAccounts.SaveError />      <ChartOfAccounts.DraftIsChild>        Sits under <ChartOfAccounts.DraftParentName />      </ChartOfAccounts.DraftIsChild>      <ChartOfAccounts.DraftNameOnly>        <ChartOfAccounts.DraftNameOnlyMessage />      </ChartOfAccounts.DraftNameOnly>      <ChartOfAccounts.DraftName />      <ChartOfAccounts.DraftError field="name" />      <ChartOfAccounts.DraftSortCode />      <ChartOfAccounts.DraftError field="sortCode" />      <ChartOfAccounts.DraftType>        <Select>          <ChartOfAccounts.DraftTypeItems>            <ChartOfAccounts.DraftTypeItem />          </ChartOfAccounts.DraftTypeItems>        </Select>      </ChartOfAccounts.DraftType>      {/* DraftSubtype, DraftFinancialAccountType: same three-part shape */}      <ChartOfAccounts.DraftIsEdit>        <ChartOfAccounts.DraftDebitCredit>{/* … */}</ChartOfAccounts.DraftDebitCredit>      </ChartOfAccounts.DraftIsEdit>      <ChartOfAccounts.DraftSupportsTaxCategory>        <ChartOfAccounts.DraftTaxCategory>{/* … */}</ChartOfAccounts.DraftTaxCategory>      </ChartOfAccounts.DraftSupportsTaxCategory>      <ChartOfAccounts.DraftDescription />      <ChartOfAccounts.DraftReportCashFlow />      <ChartOfAccounts.CancelDraft />      <ChartOfAccounts.Save />    </>  )}

Required scopes

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

  • ledger:read
  • ledger:create
  • ledger:update
  • ledger:delete

API reference

Root props

PropTypeDefaultDescription
nounstring"ledger"What a ledger is called in the default copy ("Add ledger", "Delete ledger"). A household's chart might say "category".
defaultTypeFilterLedgerType | "all""all"Initial type filter. The filter applies to top-level ledgers; a child is shown with its parent.
defaultCreatingbooleanfalseOpen the create draft on mount.
defaultEditingIdstring—Open this ledger's edit draft once the chart has loaded — the deep link to editing one ledger.
onViewAccount(target: LedgerViewTarget) => void—Called with { ledgerId, type, subtype } when a row's View report is chosen. The host decides where it goes — see Viewing a ledger. Optional: without it ViewAccountTrigger renders nothing, so there is never a View report that goes nowhere.
onCreated / onUpdated(ledger: LedgerPublic) => void—Called with the ledger a create or an edit wrote, after the chart refetches — for a host's own confirmation.
onDeleted(ledgerId: string) => void—Called with the id of the ledger a delete removed.
ledgersLedgerOverride[]—Override the fetched ledgers (skips every request). Ordered and nested exactly as live data is, and adds, edits and deletes change a local copy — so a prototype or story works end to end without touching the API. A delete is refused while the ledger has children, or when it sets deletable: false, as the API refuses those. deletable: false makes it a system ledger, so an edit can change only its name.
state"loading" | "error" | "empty"—Force a specific state for testing. Skips every request.

Parts

Container

Always rendered. Fetches the ledgers, builds the tree, owns the type filter, the draft, the delete confirmation and every write. A management surface rather than an entitled report, so it has no locked state.

PartDescription
ChartOfAccounts.RootOwns fetching, the create/edit draft and the delete confirmation.

Header controls

These read the root context rather than a row, so they keep working while the list is loading, empty or errored.

PartDescription
ChartOfAccounts.TypeFilterWires the type filter to a single Select-Root-shaped child (value is a LedgerType or "all"). A value it does not recognise is ignored.
ChartOfAccounts.TypeFilterItemsRenders its children once per option — All types, then asset, liability, equity, revenue and expense.
ChartOfAccounts.TypeFilterItem
asChild?
One option — sets value and renders the label.
ChartOfAccounts.CreateTrigger
asChild?
Toggles a clean draft for a top-level ledger, and sets aria-expanded while it's open. Renders nothing without ledger:create. Default label "Add ledger" (the root's noun).
ChartOfAccounts.ActionError
asChild?
The last failed delete, in neutral copy: "This ledger can't be deleted." It never says why. Nothing when all is well.

Rows

Renders inside Success, once per ledger, each parent followed by its children.

PartDescription
ChartOfAccounts.SuccessState wrapper.
ChartOfAccounts.RowsIterates the filtered chart, providing a per-row context.
ChartOfAccounts.SortCode / Name / Description
asChild?
The ledger's own text. Each renders nothing when the ledger has none.
ChartOfAccounts.Type
asChild?
The type as a label, with data-type for tone.
ChartOfAccounts.Subtype / NormalBalance / FinancialAccountType
asChild?
Wire enums as words — "Operating Expense", "Debit", "Bank Account". FinancialAccountType renders nothing when unset.
ChartOfAccounts.TaxCategory
asChild?
The tax form's wording for the category ("Office expense"), or nothing when unset.
ChartOfAccounts.ReportsCashFlow
asChild?
Yes or No — whether the ledger is in the cash flow report.
ChartOfAccounts.ChildMarkerRenders its children only on a child ledger — for the nested marker.
ChartOfAccounts.useRowProps()Spread onto the row element. The row is a button (role, tabIndex, aria-expanded): a click, or Enter or Space, opens the ledger's details read-only and a second closes them; it does nothing while the row is open for an edit, a new child or a delete, and ignores clicks on controls inside it. Also data-depth (0 top-level, 1 child, 2 grandchild, 3 great-grandchild), data-open while the row is open, and the depth as the --asset-row-depth style variable.
ChartOfAccounts.useRowExpanded()True while this row is open (edited, given a child, or confirmed for delete) — for an expand animation.

Row actions

A host with actions of its own (moving line entries, say) renders them beside these in the row; each reads the row through useLedgerRow().

PartDescription
ChartOfAccounts.ViewAccountTrigger
asChild?
Calls onViewAccount with the row's ledger id, type and subtype. Default label "View". Renders nothing without onViewAccount.
ChartOfAccounts.EditTrigger
asChild?
Opens the draft over this ledger, in its row, where Editing renders. Renders nothing without ledger:update.
ChartOfAccounts.AddChildTrigger
asChild?
Opens a create draft for a child of this ledger, in its row, where AddingChild renders. Renders nothing on a great-grandchild (a chart nests at most four levels: parent, child, grandchild and great-grandchild) or without ledger:create.
ChartOfAccounts.DeleteTrigger
asChild?
Asks to delete this ledger. Renders nothing without ledger:delete. On a system ledger (is_deletable: false) it stays in place but disabled (disabled, data-disabled); a ledger from an API that doesn't send the flag stays deletable.
ChartOfAccounts.DeleteAvailable / DeleteUnavailableRow-scoped: children when this ledger can be deleted, or when the token could delete but this ledger can't be — for wrapping the disabled Delete in a tooltip.
ChartOfAccounts.DeleteUnavailableMessage
asChild?
Why Delete is disabled on a system ledger: "System ledgers cannot be deleted" (with the chart's noun, e.g. "System categories").
ChartOfAccounts.DeleteConfirmChildren while a delete awaits confirmation — for asking at the top of the surface.
ChartOfAccounts.DeletingRow-scoped: children while this row's ledger awaits confirmation. DeleteTrigger also opens the row, so the question can sit in the row where Delete was chosen.
ChartOfAccounts.DeleteTargetName
asChild?
The name of the ledger awaiting confirmation.
ChartOfAccounts.ConfirmDelete / CancelDelete
asChild?
Deletes it ("Delete ledger", "Deleting…" in flight), or backs out.

Draft

One set of fields serves create, add child and edit. Errors show once a field is touched or a save attempted.

PartDescription
ChartOfAccounts.CreateChildren while a draft for a top-level ledger is open.
ChartOfAccounts.Editing / AddingChildRow-scoped: children while this row's ledger is being edited, or given a child.
ChartOfAccounts.ViewingRow-scoped: children while this row's ledger details are open read-only. The draft parts render the ledger with every field locked (text inputs readOnly, selects and the switch disabled) and Save hidden. Needs no write scope.
ChartOfAccounts.DraftIsEditChildren while the draft edits an existing ledger.
ChartOfAccounts.DraftIsChild / DraftParentNameChildren, and the parent's name, while the draft is for a child.
ChartOfAccounts.DraftNameOnly / DraftNameOnlyMessageChildren, and the line "System ledgers can only be renamed.", while the draft edits a system ledger (is_deletable: false). Its other fields are locked (inputs disabled with data-locked, selects and the cash-flow switch disabled), only the name is validated, and Save sends the name alone. Other ledgers edit as usual.
ChartOfAccounts.DraftName / DraftSortCode / DraftDescription
asChild?, …input props
Controlled inputs. The sort code must be numeric; name and sort code are required.
ChartOfAccounts.DraftType / DraftSubtype / DraftFinancialAccountType / DraftTaxCategory / DraftDebitCreditEach wires a Select-Root-shaped child (value, onValueChange, disabled), with …Items and …Item parts for its options. Subtypes and tax categories follow the chosen type, and changing type drops one it no longer allows. The optional selects offer a None option (value LEDGER_NONE_VALUE). DraftDebitCredit (the normal balance) has the same shape and is only set by an edit — a new ledger takes its type's.
ChartOfAccounts.DraftSupportsTaxCategoryChildren when the chosen type carries a tax category — revenue and expense.
ChartOfAccounts.DraftReportCashFlow
asChild?
The cash-flow flag as a switch (role="switch", aria-checked, data-state).
ChartOfAccounts.DraftError
field, asChild?
The problem with one field: name, sortCode, type, subtype or taxCategory.
ChartOfAccounts.SaveError
asChild?
The last failed create or update.
ChartOfAccounts.Save / CancelDraft
asChild?
Writes the draft ("Add ledger" or "Save") — disabled until it's valid, and on an edit until something has changed — or discards it ("Cancel", or "Close" on the details). Save renders nothing on the details.
ChartOfAccounts.DraftValue
field, asChild?
One draft field as text, for read-only details: a chosen option's label, the text as typed, or "Yes" / "No" for reportCashFlow. An empty field reads "—" and carries data-empty.
ChartOfAccounts.EditDetails
asChild?
Where an edit has Save, the details have Edit: it unlocks the fields in place. Renders nothing outside the details or without ledger:update.

Loading / Error / Empty

PartDescription
ChartOfAccounts.LoadingWhile the list is first read.
ChartOfAccounts.ErrorWhen it couldn't be read.
ChartOfAccounts.ErrorMessage
asChild?, format?
Error copy.
ChartOfAccounts.Retry
asChild?
Refetches the list.
ChartOfAccounts.EmptyWhen the business has no ledgers.

Parents and children

Top-level ledgers are ordered by sort code (compared as numbers, so 6010 follows 6002), each followed by its children in the same order, at every depth the API holds. A chart nests at most four levels deep, so Add child is offered on every ledger down to grandchildren, not on great-grandchildren. A child whose parent isn't in the chart is listed as a top-level ledger rather than lost.

A child is its parent's kind of ledger: its type, subtype, financial account type and cash flow setting come from the parent and their draft fields are disabled. Its name, sort code, description and tax category are its own.

Viewing a ledger

The chart manages accounts and nothing else: no report, ledger table or transactions table renders inside it, and nothing else has to be embedded to use it. Viewing a ledger is the host's, through onViewAccount:

  • Route to the Transactions component, filtered to the ledger's type and subtype.
  • Read the ledger statement report from the API (“Retrieve the ledger statement report” in the General Ledger reference) with the business id and ledgerId: every journal entry on that ledger.
  • Open a ledger page of the host's own.

Not here

Moving line entries from one ledger to another and bookkeeper notes are part of Asset's bookkeeping tools rather than the public API, so this compound leaves them out; a host with access adds them as its own row actions.

On this page