Skip to Content
@get-asset/sdkComponents

Classifications Editor

Create or edit one business classification rule. Test run validates the draft and previews up to 10 changes without saving. Apply saves the rule and, by default, applies it to past transactions; onDone fires when the selected operation completes.

Anatomy

Import the primitive and compose the parts you need.

<ClassificationsEditor.Root ruleId={ruleId} onDone={closeEditor} onCancel={closeEditor}>  <ClassificationsEditor.Title />  <ClassificationsEditor.Loading>Loading…</ClassificationsEditor.Loading>  <ClassificationsEditor.Error><ClassificationsEditor.ErrorMessage /><ClassificationsEditor.Retry /></ClassificationsEditor.Error>  <ClassificationsEditor.Ready>    <ClassificationsEditor.Describe>      <ClassificationsEditor.DescribeInput aria-label="Describe the rule" />      <ClassificationsEditor.Build />    </ClassificationsEditor.Describe>    <ClassificationsEditor.Steps>    <ClassificationsEditor.Section section="trigger">      <ClassificationsEditor.SectionTrigger>Trigger</ClassificationsEditor.SectionTrigger>      <ClassificationsEditor.SectionOpen><ClassificationsEditor.MerchantInput /></ClassificationsEditor.SectionOpen>      <ClassificationsEditor.DraftError field="trigger" />    </ClassificationsEditor.Section>    <ClassificationsEditor.Section section="conditions">      <ClassificationsEditor.SectionTrigger>Conditions</ClassificationsEditor.SectionTrigger>      <ClassificationsEditor.AddCondition />      <ClassificationsEditor.Conditions><ClassificationsEditor.ConditionValue /></ClassificationsEditor.Conditions>    </ClassificationsEditor.Section>    <ClassificationsEditor.Section section="action">      <ClassificationsEditor.SectionTrigger>Action</ClassificationsEditor.SectionTrigger>      <ClassificationsEditor.Categories>        <ClassificationsEditor.CategoryLedger><CategorySelect /></ClassificationsEditor.CategoryLedger>      </ClassificationsEditor.Categories>      <ClassificationsEditor.DraftError field="action" />    </ClassificationsEditor.Section>    </ClassificationsEditor.Steps>    <ClassificationsEditor.TestRun />    <ClassificationsEditor.ApplyToHistory aria-label="Apply to past transactions" />    <ClassificationsEditor.Save />    <ClassificationsEditor.SaveErrorMessage />  </ClassificationsEditor.Ready>  <ClassificationsEditor.PreviewIdle>Nothing to preview yet</ClassificationsEditor.PreviewIdle>  <ClassificationsEditor.PreviewRunning>Checking your transactions</ClassificationsEditor.PreviewRunning>  <ClassificationsEditor.Applying>Applying your rule to past transactions</ClassificationsEditor.Applying>  <ClassificationsEditor.PreviewStale><ClassificationsEditor.PreviewStaleMessage /></ClassificationsEditor.PreviewStale>  <ClassificationsEditor.PreviewResults>    <ClassificationsEditor.PreviewTitle /><ClassificationsEditor.PreviewSubtitle />    <ClassificationsEditor.PreviewRows>      <ClassificationsEditor.PreviewRow>        <ClassificationsEditor.PreviewDescription /><ClassificationsEditor.PreviewAmount /><ClassificationsEditor.PreviewDate />        <ClassificationsEditor.PreviewChips><ClassificationsEditor.PreviewChip /></ClassificationsEditor.PreviewChips>      </ClassificationsEditor.PreviewRow>    </ClassificationsEditor.PreviewRows>  </ClassificationsEditor.PreviewResults>  <ClassificationsEditor.PreviewEmpty>No unreviewed transactions match</ClassificationsEditor.PreviewEmpty>  <ClassificationsEditor.PreviewError><ClassificationsEditor.PreviewErrorMessage /><ClassificationsEditor.PreviewRetry /></ClassificationsEditor.PreviewError></ClassificationsEditor.Root>

Required scopes

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

  • classification_rule:read
  • classification_rule:create
  • classification_rule:update
  • merchant:read
  • ledger:read
  • tag:read
  • external_account:read

API reference

Root props

PropTypeDefaultDescription
childrenReactNode—Compound parts. Required on the SDK Root.
ruleIdstring—Saved rule to edit; omit to create a rule.
onDone(rule?: TxnClassificationRulePublic) => void—Called with the saved rule after its apply run completes, or immediately after saving when applyToHistory is false. With onSave, called without a rule after the host save resolves.
onCancel() => void—Host navigation callback for Cancel and the back button.
onSave(draft: RuleDraft) => void | Promise<void>—Owns the write instead of the SDK. No apply run starts because this callback supplies no stored rule id. onDone fires after it resolves. Reject to show a save error. Use toCreateRequest or toUpdateRequest to serialize the draft.
onSaveSuccess(draft: RuleDraft) => void—Called after a successful save with the submitted draft, before any apply run completes. Use onDone for the completed save or apply hand-off.
onSaveError(error: Error) => void—Called for save failures with the same error displayed by SaveErrorMessage. Apply failures are shown by SaveErrorMessage.
saveLabelstring—Idle save label; defaults to Apply. Reads Applying… while saving/applying with history checked, or Saving… when unchecked.
savingboolean—Force the busy form lock for stories and tests.
saveErrorError—Override footer save error for stories and tests.
disabledboolean—Disable form controls and actions; defaults to false.
editableboolean—Whether editing is allowed; defaults to true. False locks controls and hides Save.
explainerboolean—Offer the dismissible explainer; defaults to true.
state"loading" | "error"—Force the editor state and skip network activity.
ruleTxnClassificationRulePublic—Override the fetched rule and enter edit mode. Skips its read.
merchantsMerchantPublic[]—Override merchant search results; skips merchant requests.
ledgersLedgerPublic[]—Override the category directory; skips its read.
tagFieldsTagFieldWithTagValuesPublic[]—Override tag fields with their values; skips their read.
accountsExternalAccountPublic[]—Override the external-account directory; skips its read.
previewClassificationsEditorPreview—Offline panel override: { state: "idle" | "running" | "results" | "empty" | "error", changes?: TxnClassificationRuleChangePublic[], stale?: boolean }. Skips all reads and writes.
buildClassificationsEditorBuild—Offline fixture: { state: "typed" | "building", text: string }, { state: "built", text: string, rule: CreateTxnClassificationRuleRequestOutput }, or { state: "stale", text: string, builtText: string, rule: CreateTxnClassificationRuleRequestOutput }. Built/stale fixtures replace the steps and collapse all sections. Skips all reads and writes.
applyState"applying" | "error"—Offline apply override. Applying locks the form; error exposes the footer retry action. Skips all reads and writes.
formatAmount(value: number) => string—Format summary money and signed preview transaction amounts. Defaults to US dollars.
formatDate(value: string) => string—Format summary and preview dates from ISO strings. SDK defaults to Jan 31, 2026; React defaults to Jan 31.

Parts

Compound parts

Value, wrapper and action parts support asChild. Gates and iterators take children. Select bindings clone a child accepting value, onValueChange and disabled. Row parts must be nested inside their iterator.

PartDescription
ClassificationsEditor.DescribeSlottable description card wrapper.
ClassificationsEditor.DescribeInputBound textarea, maxLength 2000, disabled with the form. Supports asChild and native textarea props.
ClassificationsEditor.BuildSlottable button: Build rule, Building, or Rebuild. Disabled for blank text, building, locks, or unchanged successful text.
ClassificationsEditor.BuildLabelSlottable current build button label, for custom button content.
ClassificationsEditor.BuildingGate while creating or polling a pending draft.
ClassificationsEditor.BuildStaleGate when description differs from the last successful build text.
ClassificationsEditor.StepsSlottable steps wrapper with data-dimmed=true while building or stale.
ClassificationsEditor.RootOwns the draft, directories, validation, preview mutation, save, apply run and polling.
ClassificationsEditor.LoadingGate while the rule or a directory is loading.
ClassificationsEditor.ErrorGate for an unavailable rule or failed read.
ClassificationsEditor.ReadyGate after all enabled reads succeed.
ClassificationsEditor.ErrorMessageFriendly initial-load error; accepts format(error).
ClassificationsEditor.RetryRefetches only enabled initial reads.
ClassificationsEditor.TitleAdd Rule in create mode or Edit rule in edit mode.
ClassificationsEditor.ExplainerGate while the explainer is offered and not dismissed.
ClassificationsEditor.DismissExplainerDismisses the explainer.
ClassificationsEditor.CancelCalls onCancel.
ClassificationsEditor.ApplyToHistoryCheckbox checked on every mount. Binds checked, onCheckedChange and disabled to a custom asChild control, or checked and onChange to a native input. Renders nothing when onSave owns the write.
ClassificationsEditor.SaveValidates and saves, then applies when applyToHistory is true. Disabled during preview or saving/applying. Uses saveLabel, Applying… when applying, or Saving… for save-only writes.
ClassificationsEditor.SaveErrorMessageFooter save or apply error; accepts format(error).
ClassificationsEditor.TestRunValidates like Save and previews up to 10 changes without saving; disabled while either operation is running.
ClassificationsEditor.ApplyingGate during saving or applying; takes precedence over preview gates.
ClassificationsEditor.PreviewIdleGate before the first Test run.
ClassificationsEditor.PreviewRunningGate while the preview mutation is pending.
ClassificationsEditor.PreviewResultsGate for nonempty successful preview changes.
ClassificationsEditor.PreviewEmptyGate for an empty successful preview.
ClassificationsEditor.PreviewErrorGate when the preview fails.
ClassificationsEditor.PreviewStaleGate above a retained successful preview when sameDraft detects a changed draft.
ClassificationsEditor.PreviewTitleA preview of your rule in action.
ClassificationsEditor.PreviewSubtitleShowing up to 10 matching transactions awaiting review.
ClassificationsEditor.PreviewStaleMessageThe rule changed since this run.
ClassificationsEditor.PreviewErrorMessageWe couldn't check your transactions. Try again. Accepts format?: (error: Error | null) => ReactNode to customize the copy.
ClassificationsEditor.PreviewRetryRetries the failed preview snapshot; TestRun uses the current draft instead.
ClassificationsEditor.PreviewRowsIterates returned changes and provides preview row context.
ClassificationsEditor.PreviewRowWrapper exposing data-transaction-id.
ClassificationsEditor.PreviewDescriptionTransaction description exactly as returned.
ClassificationsEditor.PreviewAmountSigned transaction amount via Root formatAmount; accepts format(number).
ClassificationsEditor.PreviewDateTransaction date via Root formatDate; accepts format(ISO string).
ClassificationsEditor.PreviewChipsIterates only new category names and tag values. The API excludes bank/account lines.
ClassificationsEditor.PreviewChipOne new value; exposes data-kind="category" or "tag".
ClassificationsEditor.DraftErrorShown validation error; requires field="trigger", "action", "conditions.<key>" or "action.<key>".
ClassificationsEditor.SectionRequires section="trigger" | "conditions" | "action". Exposes data-section, data-open and data-complete.
ClassificationsEditor.SectionTriggerToggles the containing section, closing the previous section; disabled while locked.
ClassificationsEditor.SectionOpenGate while the containing section is open.
ClassificationsEditor.SectionClosedGate while the containing section is closed.
ClassificationsEditor.SectionSummaryIterates the containing section sentence clauses.
ClassificationsEditor.ClauseClause wrapper with data-clause.
ClassificationsEditor.ClauseConnectorWords linking clause values.
ClassificationsEditor.ClauseValuesIterates one clause’s values.
ClassificationsEditor.ClauseValueValue text with data-kind for styling.
ClassificationsEditor.TriggerKindBinds a select-shaped child to merchant or description.
ClassificationsEditor.TriggerKindItemsIterates available trigger kind options; provides context for TriggerKindItem.
ClassificationsEditor.TriggerKindItemRenders one option with value and data-value; use within TriggerKindItems. Supports asChild for a select item.
ClassificationsEditor.TriggerEmptyGate while the trigger has no value.
ClassificationsEditor.MerchantTriggerGate for merchant mode.
ClassificationsEditor.DescriptionTriggerGate for description mode.
ClassificationsEditor.TriggerMatchTypeBinds contains, not_contains or equals to a select-shaped child.
ClassificationsEditor.TriggerMatchTypeItemsIterates available trigger match type options; provides context for TriggerMatchTypeItem.
ClassificationsEditor.TriggerMatchTypeItemRenders one option with value and data-value; use within TriggerMatchTypeItems. Supports asChild for a select item.
ClassificationsEditor.TriggerDescriptionText input bound to the description predicate.
ClassificationsEditor.MerchantInputMerchant search input; disabled while the editor is locked.
ClassificationsEditor.MerchantQueryCurrent search text; accepts format(string).
ClassificationsEditor.MerchantOpenGate while merchant suggestions are open.
ClassificationsEditor.MerchantPortalPortals the merchant suggestions; accepts container.
ClassificationsEditor.MerchantContentPopover content anchored to MerchantInput.
ClassificationsEditor.MerchantMatchesIterates current merchant matches.
ClassificationsEditor.MerchantMatchSelects a merchant; use within MerchantMatches. Hidden while locked.
ClassificationsEditor.MerchantEmptyGate after a search settles with no matches.
ClassificationsEditor.MerchantLoadingMoreGate while another merchant page loads.
ClassificationsEditor.MerchantAutoLoadMoreIntersectionObserver sentinel for merchant pagination.
ClassificationsEditor.MerchantErrorGate for failed merchant search/paging.
ClassificationsEditor.MerchantErrorMessageFriendly merchant error copy.
ClassificationsEditor.MerchantRetryRetries merchant search/paging.
ClassificationsEditor.ConditionsIterates draft condition rows.
ClassificationsEditor.ConditionRow wrapper exposing data-key and data-field.
ClassificationsEditor.HasConditionsGate when at least one condition exists.
ClassificationsEditor.NoConditionsGate with no conditions.
ClassificationsEditor.ConditionFieldBinds the condition field, offering each field at most once.
ClassificationsEditor.ConditionFieldItemsIterates available condition field options; provides context for ConditionFieldItem.
ClassificationsEditor.ConditionFieldItemRenders one option with value and data-value; use within ConditionFieldItems. Supports asChild for a select item.
ClassificationsEditor.ConditionOperatorBinds the current field’s comparison operator.
ClassificationsEditor.ConditionOperatorItemsIterates available condition operator options; provides context for ConditionOperatorItem.
ClassificationsEditor.ConditionOperatorItemRenders one option with value and data-value; use within ConditionOperatorItems. Supports asChild for a select item.
ClassificationsEditor.ConditionValueInput for the lower or sole bound; normalizes amounts on blur.
ClassificationsEditor.ConditionDateBinds ISO day and Root date formatter to a date-picker-shaped child.
ClassificationsEditor.ConditionMaxDatePicker binding for a between condition’s upper date.
ClassificationsEditor.ConditionMaxValueInput for a between condition’s upper bound.
ClassificationsEditor.IsBetweenGate for a between operator in the current condition.
ClassificationsEditor.ConditionDirectionSelect binding for money_in or money_out.
ClassificationsEditor.ConditionDirectionItemsIterates available condition direction options; provides context for ConditionDirectionItem.
ClassificationsEditor.ConditionDirectionItemRenders one option with value and data-value; use within ConditionDirectionItems. Supports asChild for a select item.
ClassificationsEditor.ConditionAccountSelect binding for external account id.
ClassificationsEditor.ConditionAccountItemsIterates available condition account options; provides context for ConditionAccountItem.
ClassificationsEditor.ConditionAccountItemRenders one option with value and data-value; use within ConditionAccountItems. Supports asChild for a select item.
ClassificationsEditor.RemoveConditionRemoves the containing condition.
ClassificationsEditor.AddConditionAdds a row using the first free condition field.
ClassificationsEditor.CanAddConditionGate while an unused condition field exists.
ClassificationsEditor.ActionModeSelect binding for categorize or tag.
ClassificationsEditor.ActionModeItemsIterates available action mode options; provides context for ActionModeItem.
ClassificationsEditor.ActionModeItemRenders one option with value and data-value; use within ActionModeItems. Supports asChild for a select item.
ClassificationsEditor.CategorizingGate for category actions.
ClassificationsEditor.TaggingGate for tag actions.
ClassificationsEditor.ActionEmptyGate while no category or tag value is selected.
ClassificationsEditor.CategoriesIterates category rows.
ClassificationsEditor.CategoryRowRow wrapper exposing data-key.
ClassificationsEditor.CategoryLedgerSelect binding for the current category ledger id.
ClassificationsEditor.LedgerGroupsIterates available ledger groups, excluding other rows’ selections.
ClassificationsEditor.LedgerGroupWrapper exposing data-type and data-label.
ClassificationsEditor.LedgerGroupLabelCurrent ledger group display name.
ClassificationsEditor.LedgerItemsIterates available ledger options; provides context for LedgerItem.
ClassificationsEditor.LedgerItemRenders one option with value and data-value; use within LedgerItems. Supports asChild for a select item.
ClassificationsEditor.CategoryPercentageNumeric input for a split share.
ClassificationsEditor.RemoveCategoryRemoves the containing category row.
ClassificationsEditor.AddCategoryAdds a split row; splits evenly until a share is explicitly edited.
ClassificationsEditor.IsSplitGate when more than one category exists.
ClassificationsEditor.NotSplitGate for a single category.
ClassificationsEditor.SplitTotalSum of category or tag shares; accepts format(number), with data-complete at 100.
ClassificationsEditor.TagFieldSelect binding for the tag field name.
ClassificationsEditor.TagFieldItemsIterates available tag field options; provides context for TagFieldItem.
ClassificationsEditor.TagFieldItemRenders one option with value and data-value; use within TagFieldItems. Supports asChild for a select item.
ClassificationsEditor.HasTagFieldGate once a tag field is selected.
ClassificationsEditor.IsTagSplitGate with multiple tag rows.
ClassificationsEditor.NotTagSplitGate for a single tag row.
ClassificationsEditor.TagsIterates tag rows.
ClassificationsEditor.TagRowWrapper exposing data-key.
ClassificationsEditor.TagValueSelect binding for the current tag value.
ClassificationsEditor.TagValueItemsIterates available tag value options; provides context for TagValueItem.
ClassificationsEditor.TagValueItemRenders one option with value and data-value; use within TagValueItems. Supports asChild for a select item.
ClassificationsEditor.TagPercentageNumeric input for the current tag share.
ClassificationsEditor.RemoveTagRemoves the containing tag row.
ClassificationsEditor.AddTagAdds another tag row.
ClassificationsEditor.useClassificationsEditorRoot context hook, including description, setDescription, build, building, builtText, buildStale, canBuild, buildLabel, draft, validation, preview state, locks and actions; applyToHistory (initially true) and setApplyToHistory control whether saving also applies to past transactions.
ClassificationsEditor.useConditionCurrent condition row hook; use within Conditions.
ClassificationsEditor.useCategoryRowCurrent category row hook; use within Categories.
ClassificationsEditor.useTagRowCurrent tag row hook; use within Tags.
ClassificationsEditor.useMerchantMatchCurrent merchant and match-highlight offsets; use within MerchantMatches.
ClassificationsEditor.scopesRequired OAuth scope array.

Describe the rule

Describe the rule starts empty in create and edit mode. Build rule posts the trimmed description (up to 2,000 characters) and polls about every 1.5 seconds while pending. Building locks the form and dims all three steps. A successful build replaces every step, including hand edits, and collapses every section. It never saves or calls onSave; Apply still saves to the same rule in edit mode.

After a successful build, changing the description dims the steps and offers Rebuild. Editing steps by hand does not dim them. Blank text, building, a locked form, or text identical to the last successful build disables Build. Failed requests, failed drafts, missing rules, and shapes the editor cannot hold leave the draft untouched with no message. Agent notes are never shown. Selecting another rule clears the description and build state; older build results are ignored.

The headless parts are Describe (wrapper), DescribeInput (bound textarea with asChild), Build (button), BuildLabel (current label), Building and BuildStale (gates), and Steps (wrapper with data-dimmed). The context exposes description, setDescription, build(), building, builtText, buildStale, canBuild, and buildLabel. The build prop supplies offline typed, building, built, or stale fixtures; built and stale fixtures include the unsaved create body. Building uses classification_rule:create and polling uses classification_rule:read, already included in the editor scopes.

Preview and apply

Preview requests run only on Test run or its retry. Invalid drafts open their first error section. Create mode sends a create request; edit mode sends the complete update request for the saved id. Both request limit 10. A changed draft keeps the successful result with a plain bordered notice above the results; Retry repeats a failed snapshot, while Test run uses the current draft.

With Apply to past transactions checked, an unchanged rule can be turned on and applied only when it is archived or its last apply failed; an active rule needs a change first. The edit PATCH includes is_active: true; edit previews do not change activation. Saving and applying lock the form. The SDK polls pending and running apply runs about every 1.5 seconds. After a polling request fails, retry resumes the same run. A terminal failed run or refused run request allows starting a new run without resaving an unchanged, active rule. Save errors never start a run. Changing ruleId or the override rule's id clears operation state and ignores the old rule's completions; creating a rule keeps its apply run.

Unchecking Apply to past transactions saves without starting a run. Edit requests omit is_active, preserving activation. onDone receives the saved rule immediately after saving. The button reads “Saving…” and the preview stays visible. An unchanged draft is disabled, including archived rules and failed applies. The checkbox locks with the form and is hidden when onSave owns the write.

The editor supports one classification that either categorizes or tags one tag field. Rules it cannot represent fully show an unavailable error. A preview or applyState override disables network activity. To supply only local directories, override merchants, ledgers, tagFields and accounts.

On this page