Skip to Content
@get-asset/sdkComponents

Document Details

Statement details with reconciliation, buffered transaction edits, and PDF or image preview. Other document types render the not-available state.

Anatomy

Import the primitive and compose the parts you need.

<DocumentDetails.Root documentId={documentId} onBack={onBack}>  <DocumentDetails.Surface>    <DocumentDetails.Loading>Loading…</DocumentDetails.Loading>    <DocumentDetails.Error>      <DocumentDetails.ErrorMessage />      <DocumentDetails.Retry />    </DocumentDetails.Error>    <DocumentDetails.Back />    <DocumentDetails.NotAvailable><DocumentDetails.NotAvailableMessage /></DocumentDetails.NotAvailable>    <DocumentDetails.Ready>      <DocumentDetails.Title />      <DocumentDetails.CreatedDate />      <DocumentDetails.Type />      <DocumentDetails.Status />      <DocumentDetails.Processing><DocumentDetails.ProcessingMessage /></DocumentDetails.Processing>      <DocumentDetails.AllSet><DocumentDetails.BannerTitle /><DocumentDetails.BannerDescription /></DocumentDetails.AllSet>      <DocumentDetails.NeedsLook><DocumentDetails.BannerTitle /><DocumentDetails.BannerDescription /></DocumentDetails.NeedsLook>      <DocumentDetails.AccountUnmatched>{/* AccountSelect + AccountOptions */}</DocumentDetails.AccountUnmatched>      <DocumentDetails.Reconciliation>        <DocumentDetails.Difference />        <DocumentDetails.ReadOnly><DocumentDetails.BeginningBalance /></DocumentDetails.ReadOnly>        <DocumentDetails.Editing><DocumentDetails.BeginningBalanceInput /></DocumentDetails.Editing>        <DocumentDetails.TransactionsToggle />        <DocumentDetails.Rows>          <DocumentDetails.Row>            <DocumentDetails.ReadOnly>              <DocumentDetails.RowDate /><DocumentDetails.RowDescription /><DocumentDetails.RowAmount />            </DocumentDetails.ReadOnly>            <DocumentDetails.Editing>              <DocumentDetails.RowDateInput /><DocumentDetails.RowDescriptionInput />              <DocumentDetails.RowAmountInput /><DocumentDetails.Delete />            </DocumentDetails.Editing>          </DocumentDetails.Row>        </DocumentDetails.Rows>        <DocumentDetails.Editing><DocumentDetails.AddTransaction /></DocumentDetails.Editing>        <DocumentDetails.TransactionsTotal />        <DocumentDetails.ReadOnly><DocumentDetails.EndingBalance /><DocumentDetails.Edit /></DocumentDetails.ReadOnly>        <DocumentDetails.Editing>          <DocumentDetails.EndingBalanceInput /><DocumentDetails.Cancel /><DocumentDetails.Save />        </DocumentDetails.Editing>        <DocumentDetails.SaveErrorMessage />      </DocumentDetails.Reconciliation>      <DocumentDetails.PreviewImage><DocumentDetails.ZoomSurface>        <DocumentDetails.Url asChild><img alt="Statement" /></DocumentDetails.Url>      </DocumentDetails.ZoomSurface></DocumentDetails.PreviewImage>      <DocumentDetails.PreviewPdf>{/* Url supplies src + scale to your PDF renderer */}</DocumentDetails.PreviewPdf>      <DocumentDetails.PreviewZoomable><DocumentDetails.ZoomOut /><DocumentDetails.ZoomIn /></DocumentDetails.PreviewZoomable>      <DocumentDetails.OpenOriginal>Open original</DocumentDetails.OpenOriginal>    </DocumentDetails.Ready>  </DocumentDetails.Surface></DocumentDetails.Root>

Required scopes

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

  • document:read
  • document:update
  • external_account:read
  • ledger:read
  • journal_entry:read
  • journal_entry:create
  • journal_entry:update
  • journal_entry:delete
  • transaction:read
  • transaction:update
  • transaction:delete

API reference

Root props

PropTypeDefaultDescription
documentIdrequiredstring—The document to load. Changing it discards the previous document's edit session.
onBack() => void—Called by Back to documents. The host owns navigation.
formatAmount(amount: number) => string—Money formatter for balances, transactions, and banner amounts. Defaults to USD with two decimals.
formatDate(date: string) => string—Formats displayed dates, including the styled edit-mode date field. Input values retain YYYY-MM-DD calendar dates.
documentDocumentPublic—Offline document override. Disables all network reads and server writes. Balances come from metadata_.statement_starting_balance and metadata_.statement_closing_balance.
rowsJournalEntryEacPublic[]—Overrides journal entries, including their line_entries. Otherwise every page is fetched using document_id. Supply accounts and ledgers with offline rows to derive signed amounts.
transactionsTransactionPublic[]—Overrides backing transaction reads. Their amounts establish the sign convention for transaction-backed row edits. Otherwise fetched by transaction_id; document overrides keep these reads offline too.
accountsExternalAccountPublic[]—Overrides external accounts for the immediate-save picker and the statement account's ledger_id.
ledgersLedgerPublic[]—Overrides ledger lookup. Its debit_credit determines the signed statement amount. New rows prefer fallbackLedgerId, then look up Uncategorized Inflow or Uncategorized Outflow by name.
fallbackLedgerIdstring—Host-provided offset ledger ID for new rows, for either amount direction. Takes precedence over the legacy Uncategorized Inflow/Outflow name lookup. LedgerPublic has no unique uncategorized-ledger marker. If neither resolves, Save is disabled with the standard save error until the offset is available or the new row is removed.
previewUrlstring | null—Overrides the signed URL request; null explicitly supplies no URL. The file extension is always read from document.name.
state"loading" | "error"—Forces a display state and disables network reads.
onSave(draft: DocumentDetailsDraft) => void | Promise<void>—Replaces statement server writes. Useful for offline demos. Reject to show the save error; the raw cause remains attached to the error.
onSelectAccount(id: string) => void | Promise<void>—Replaces the immediate account-association write. Account selection is separate from the edit buffer.
childrenrequiredReactNode—Compound parts.

Parts

Container and state

PartDescription
RootOwns reads, the edit buffer, sequential writes, and preview state.
Surface
asChild?
Wrapper carrying data-screen, data-saving, and aria-busy for layout and locking feedback.
LoadingChildren while document, account, ledgers, or journal pages load.
ErrorChildren when a required read fails.
ErrorMessage
asChild?, format?
Standard load error. format receives Error | null.
Retry
asChild?
Refetches enabled reads.
ReadyChildren after all required reads succeed for an available document.
ProcessingChildren while an eligible statement is processing, inside Ready.
ProcessingMessage
asChild?
Processing this statement…
NotAvailableChildren for unsupported types or statements with an unavailable status.
NotAvailableMessage
asChild?
This document doesn't have a detail view yet.
useDocumentDetails()Context hook. Throws outside Root. Prefer slots when composing UI.

Header and banners

PartDescription
Back
asChild?
Back to documents; calls onBack.
Title
asChild?
Statement description falling back to the file name.
CreatedDate
asChild?, format?
Created date; format receives the raw ISO date.
Type
asChild?
Document type label.
Status
asChild?
Uses the Documents status mapping and data-status tone.
AllSetBanner gate when the difference is zero and the account is matched.
NeedsLookBanner gate for a nonzero difference.
AccountUnmatchedBanner gate for failure_code failed_account_matching.
BannerTitle
asChild?
Title of the active banner.
BannerDescription
asChild?
Explains the active banner. A nonzero difference uses a positive amount and more or less.
AccountHint
asChild?
Explains that missing accounts may need to be added from Accounts.
AccountSelect
children: ReactElement
Binds value, disabled, and onValueChange to a select child. Saves immediately and refetches the document.
AccountOptionsRepeats children for each external account.
AccountOption
asChild?
Supplies an option's value and account label, including mask.
AccountErrorMessage
asChild?, format?
Immediate account-save error with its original cause.
AccountRetry
asChild?
Retries the last account selection after a failure.

Reconciliation and editing

PartDescription
ReconciliationChildren when the statement is not processing, including unmatched accounts.
Difference
asChild?, format?
Numeric value from the current buffer; format receives the unformatted number.
BeginningBalance
asChild?, format?
Numeric value from the current buffer; format receives the unformatted number.
EndingBalance
asChild?, format?
Numeric value from the current buffer; format receives the unformatted number.
TransactionsTotal
asChild?, format?
Numeric value from the current buffer; format receives the unformatted number.
BeginningBalanceInput
asChild?, input props
Signed money input. Sanitizes on change, formats on blur, and locks during a save.
EndingBalanceInput
asChild?, input props
Signed money input. Sanitizes on change, formats on blur, and locks during a save.
TransactionsToggle
asChild?
Transactions (n) button with aria-expanded; opens or collapses rows.
TransactionsCount
asChild?
Current buffered row count.
RowsRepeats children with row context while expanded.
Row
asChild?
Row wrapper with data-row-id.
RowDate
asChild?, format?
Date display; format receives the calendar date string.
RowDescription
asChild?
Buffered transaction description.
RowAmount
asChild?, format?
Signed account-ledger amount. Credit-normal ledgers reverse the debit/credit sign.
RowDateInput
asChild?, input props
Input for the current row's buffered value. RowDateInput passes the Root formatDate as format to an asChild date field. RowAmountInput sanitizes signed money.
RowDescriptionInput
asChild?, input props
Input for the current row's buffered value. RowDateInput passes the Root formatDate as format to an asChild date field. RowAmountInput sanitizes signed money.
RowAmountInput
asChild?, input props
Input for the current row's buffered value. RowDateInput passes the Root formatDate as format to an asChild date field. RowAmountInput sanitizes signed money.
Delete
asChild?
Removes the row from the buffer; no immediate request.
AddTransaction
asChild?
Appends a blank buffered row.
EditingChildren while the local edit buffer is open.
ReadOnlyChildren outside edit mode.
Edit
asChild?
Starts editing a snapshot of the statement.
Cancel
asChild?
Discards unsaved changes and exits. Already completed writes are not undone.
Save
asChild?
Disabled until valid and dirty. Saves balances, one transaction-update batch, manual journal entry patches, one transaction-delete batch, manual journal entry deletes, then additions. Stops on the first failure and retries only remaining writes.
SaveErrorMessage
asChild?, format?
We couldn't save your changes. Try again. format receives the error with the raw cause attached.

Preview

PartDescription
PreviewLoadingChildren while the signed URL loads.
PreviewErrorChildren when the signed URL request fails.
PreviewErrorMessage
asChild?, format?
Failed to load document preview. Try refreshing or downloading.
PreviewRetry
asChild?
Refetches the signed URL.
PreviewPdfChildren for a PDF with a resolved URL. The SDK does not import a PDF renderer.
PreviewImageChildren for jpg, jpeg, or png with a resolved URL.
PreviewUnsupportedChildren for any other file extension.
PreviewUnsupportedMessage
asChild?
Preview not available for this file type.
PreviewZoomableChildren for a loaded PDF or image.
Url
asChild?
Supplies src and scale to its child renderer; without asChild renders data-url and data-zoom.
ZoomSurface
asChild?
Width-based image zoom wrapper with data-zoom.
ZoomOut
asChild?
Decreases zoom by 0.25, stopping at 0.5.
ZoomIn
asChild?
Increases zoom by 0.25, stopping at 3.
OpenOriginal
asChild?
Safe new-tab link to the signed URL.
ShowPreview
asChild?
Sets Surface's data-screen to preview.
ShowDetails
asChild?
Sets Surface's data-screen to details.

Saving and permissions

The statement form locks during saves. After a partial save, the remaining batch stays fixed until Save retries it or Cancel discards it. Completed writes remain saved. Account selection saves independently and may return the document to Processing, which preserves the header and preview and shows Processing this statement… without footer actions.

Date, description, and amount are editable on every row. Rows with a transaction_id use the transaction update and delete routes; manual rows use journal entry routes. The edited amount preserves the sign relationship between the original displayed amount and the backing transaction amount. Transaction amount changes rebuild journal entries asynchronously, so the post-save refetch may briefly show the old amount or omit an entry while it is rebuilt. When rows are missing after an amount save, they refresh every 1.5 seconds until every updated transaction has a row, for up to 30 seconds. Recovery stops silently at the cap or when this document closes. Processing documents refresh every 2 seconds until their status changes.

DocumentDetails.scopes lists all required permissions, including external_account:read, ledger:read, and transaction:read for account choices, ledger lookup, and backing transaction amounts. The SDK and styled component require the same scopes.

On this page