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:readclassification_rule:createclassification_rule:updatemerchant:readledger:readtag:readexternal_account:read
API reference
Root props
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | — | Compound parts. Required on the SDK Root. |
ruleId | string | — | 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. |
saveLabel | string | — | Idle save label; defaults to Apply. Reads Applying… while saving/applying with history checked, or Saving… when unchecked. |
saving | boolean | — | Force the busy form lock for stories and tests. |
saveError | Error | — | Override footer save error for stories and tests. |
disabled | boolean | — | Disable form controls and actions; defaults to false. |
editable | boolean | — | Whether editing is allowed; defaults to true. False locks controls and hides Save. |
explainer | boolean | — | Offer the dismissible explainer; defaults to true. |
state | "loading" | "error" | — | Force the editor state and skip network activity. |
rule | TxnClassificationRulePublic | — | Override the fetched rule and enter edit mode. Skips its read. |
merchants | MerchantPublic[] | — | Override merchant search results; skips merchant requests. |
ledgers | LedgerPublic[] | — | Override the category directory; skips its read. |
tagFields | TagFieldWithTagValuesPublic[] | — | Override tag fields with their values; skips their read. |
accounts | ExternalAccountPublic[] | — | Override the external-account directory; skips its read. |
preview | ClassificationsEditorPreview | — | Offline panel override: { state: "idle" | "running" | "results" | "empty" | "error", changes?: TxnClassificationRuleChangePublic[], stale?: boolean }. Skips all reads and writes. |
build | ClassificationsEditorBuild | — | 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.
| Part | Description |
|---|---|
ClassificationsEditor.Describe | Slottable description card wrapper. |
ClassificationsEditor.DescribeInput | Bound textarea, maxLength 2000, disabled with the form. Supports asChild and native textarea props. |
ClassificationsEditor.Build | Slottable button: Build rule, Building, or Rebuild. Disabled for blank text, building, locks, or unchanged successful text. |
ClassificationsEditor.BuildLabel | Slottable current build button label, for custom button content. |
ClassificationsEditor.Building | Gate while creating or polling a pending draft. |
ClassificationsEditor.BuildStale | Gate when description differs from the last successful build text. |
ClassificationsEditor.Steps | Slottable steps wrapper with data-dimmed=true while building or stale. |
ClassificationsEditor.Root | Owns the draft, directories, validation, preview mutation, save, apply run and polling. |
ClassificationsEditor.Loading | Gate while the rule or a directory is loading. |
ClassificationsEditor.Error | Gate for an unavailable rule or failed read. |
ClassificationsEditor.Ready | Gate after all enabled reads succeed. |
ClassificationsEditor.ErrorMessage | Friendly initial-load error; accepts format(error). |
ClassificationsEditor.Retry | Refetches only enabled initial reads. |
ClassificationsEditor.Title | Add Rule in create mode or Edit rule in edit mode. |
ClassificationsEditor.Explainer | Gate while the explainer is offered and not dismissed. |
ClassificationsEditor.DismissExplainer | Dismisses the explainer. |
ClassificationsEditor.Cancel | Calls onCancel. |
ClassificationsEditor.ApplyToHistory | Checkbox 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.Save | Validates 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.SaveErrorMessage | Footer save or apply error; accepts format(error). |
ClassificationsEditor.TestRun | Validates like Save and previews up to 10 changes without saving; disabled while either operation is running. |
ClassificationsEditor.Applying | Gate during saving or applying; takes precedence over preview gates. |
ClassificationsEditor.PreviewIdle | Gate before the first Test run. |
ClassificationsEditor.PreviewRunning | Gate while the preview mutation is pending. |
ClassificationsEditor.PreviewResults | Gate for nonempty successful preview changes. |
ClassificationsEditor.PreviewEmpty | Gate for an empty successful preview. |
ClassificationsEditor.PreviewError | Gate when the preview fails. |
ClassificationsEditor.PreviewStale | Gate above a retained successful preview when sameDraft detects a changed draft. |
ClassificationsEditor.PreviewTitle | A preview of your rule in action. |
ClassificationsEditor.PreviewSubtitle | Showing up to 10 matching transactions awaiting review. |
ClassificationsEditor.PreviewStaleMessage | The rule changed since this run. |
ClassificationsEditor.PreviewErrorMessage | We couldn't check your transactions. Try again. Accepts format?: (error: Error | null) => ReactNode to customize the copy. |
ClassificationsEditor.PreviewRetry | Retries the failed preview snapshot; TestRun uses the current draft instead. |
ClassificationsEditor.PreviewRows | Iterates returned changes and provides preview row context. |
ClassificationsEditor.PreviewRow | Wrapper exposing data-transaction-id. |
ClassificationsEditor.PreviewDescription | Transaction description exactly as returned. |
ClassificationsEditor.PreviewAmount | Signed transaction amount via Root formatAmount; accepts format(number). |
ClassificationsEditor.PreviewDate | Transaction date via Root formatDate; accepts format(ISO string). |
ClassificationsEditor.PreviewChips | Iterates only new category names and tag values. The API excludes bank/account lines. |
ClassificationsEditor.PreviewChip | One new value; exposes data-kind="category" or "tag". |
ClassificationsEditor.DraftError | Shown validation error; requires field="trigger", "action", "conditions.<key>" or "action.<key>". |
ClassificationsEditor.Section | Requires section="trigger" | "conditions" | "action". Exposes data-section, data-open and data-complete. |
ClassificationsEditor.SectionTrigger | Toggles the containing section, closing the previous section; disabled while locked. |
ClassificationsEditor.SectionOpen | Gate while the containing section is open. |
ClassificationsEditor.SectionClosed | Gate while the containing section is closed. |
ClassificationsEditor.SectionSummary | Iterates the containing section sentence clauses. |
ClassificationsEditor.Clause | Clause wrapper with data-clause. |
ClassificationsEditor.ClauseConnector | Words linking clause values. |
ClassificationsEditor.ClauseValues | Iterates one clause’s values. |
ClassificationsEditor.ClauseValue | Value text with data-kind for styling. |
ClassificationsEditor.TriggerKind | Binds a select-shaped child to merchant or description. |
ClassificationsEditor.TriggerKindItems | Iterates available trigger kind options; provides context for TriggerKindItem. |
ClassificationsEditor.TriggerKindItem | Renders one option with value and data-value; use within TriggerKindItems. Supports asChild for a select item. |
ClassificationsEditor.TriggerEmpty | Gate while the trigger has no value. |
ClassificationsEditor.MerchantTrigger | Gate for merchant mode. |
ClassificationsEditor.DescriptionTrigger | Gate for description mode. |
ClassificationsEditor.TriggerMatchType | Binds contains, not_contains or equals to a select-shaped child. |
ClassificationsEditor.TriggerMatchTypeItems | Iterates available trigger match type options; provides context for TriggerMatchTypeItem. |
ClassificationsEditor.TriggerMatchTypeItem | Renders one option with value and data-value; use within TriggerMatchTypeItems. Supports asChild for a select item. |
ClassificationsEditor.TriggerDescription | Text input bound to the description predicate. |
ClassificationsEditor.MerchantInput | Merchant search input; disabled while the editor is locked. |
ClassificationsEditor.MerchantQuery | Current search text; accepts format(string). |
ClassificationsEditor.MerchantOpen | Gate while merchant suggestions are open. |
ClassificationsEditor.MerchantPortal | Portals the merchant suggestions; accepts container. |
ClassificationsEditor.MerchantContent | Popover content anchored to MerchantInput. |
ClassificationsEditor.MerchantMatches | Iterates current merchant matches. |
ClassificationsEditor.MerchantMatch | Selects a merchant; use within MerchantMatches. Hidden while locked. |
ClassificationsEditor.MerchantEmpty | Gate after a search settles with no matches. |
ClassificationsEditor.MerchantLoadingMore | Gate while another merchant page loads. |
ClassificationsEditor.MerchantAutoLoadMore | IntersectionObserver sentinel for merchant pagination. |
ClassificationsEditor.MerchantError | Gate for failed merchant search/paging. |
ClassificationsEditor.MerchantErrorMessage | Friendly merchant error copy. |
ClassificationsEditor.MerchantRetry | Retries merchant search/paging. |
ClassificationsEditor.Conditions | Iterates draft condition rows. |
ClassificationsEditor.Condition | Row wrapper exposing data-key and data-field. |
ClassificationsEditor.HasConditions | Gate when at least one condition exists. |
ClassificationsEditor.NoConditions | Gate with no conditions. |
ClassificationsEditor.ConditionField | Binds the condition field, offering each field at most once. |
ClassificationsEditor.ConditionFieldItems | Iterates available condition field options; provides context for ConditionFieldItem. |
ClassificationsEditor.ConditionFieldItem | Renders one option with value and data-value; use within ConditionFieldItems. Supports asChild for a select item. |
ClassificationsEditor.ConditionOperator | Binds the current field’s comparison operator. |
ClassificationsEditor.ConditionOperatorItems | Iterates available condition operator options; provides context for ConditionOperatorItem. |
ClassificationsEditor.ConditionOperatorItem | Renders one option with value and data-value; use within ConditionOperatorItems. Supports asChild for a select item. |
ClassificationsEditor.ConditionValue | Input for the lower or sole bound; normalizes amounts on blur. |
ClassificationsEditor.ConditionDate | Binds ISO day and Root date formatter to a date-picker-shaped child. |
ClassificationsEditor.ConditionMaxDate | Picker binding for a between condition’s upper date. |
ClassificationsEditor.ConditionMaxValue | Input for a between condition’s upper bound. |
ClassificationsEditor.IsBetween | Gate for a between operator in the current condition. |
ClassificationsEditor.ConditionDirection | Select binding for money_in or money_out. |
ClassificationsEditor.ConditionDirectionItems | Iterates available condition direction options; provides context for ConditionDirectionItem. |
ClassificationsEditor.ConditionDirectionItem | Renders one option with value and data-value; use within ConditionDirectionItems. Supports asChild for a select item. |
ClassificationsEditor.ConditionAccount | Select binding for external account id. |
ClassificationsEditor.ConditionAccountItems | Iterates available condition account options; provides context for ConditionAccountItem. |
ClassificationsEditor.ConditionAccountItem | Renders one option with value and data-value; use within ConditionAccountItems. Supports asChild for a select item. |
ClassificationsEditor.RemoveCondition | Removes the containing condition. |
ClassificationsEditor.AddCondition | Adds a row using the first free condition field. |
ClassificationsEditor.CanAddCondition | Gate while an unused condition field exists. |
ClassificationsEditor.ActionMode | Select binding for categorize or tag. |
ClassificationsEditor.ActionModeItems | Iterates available action mode options; provides context for ActionModeItem. |
ClassificationsEditor.ActionModeItem | Renders one option with value and data-value; use within ActionModeItems. Supports asChild for a select item. |
ClassificationsEditor.Categorizing | Gate for category actions. |
ClassificationsEditor.Tagging | Gate for tag actions. |
ClassificationsEditor.ActionEmpty | Gate while no category or tag value is selected. |
ClassificationsEditor.Categories | Iterates category rows. |
ClassificationsEditor.CategoryRow | Row wrapper exposing data-key. |
ClassificationsEditor.CategoryLedger | Select binding for the current category ledger id. |
ClassificationsEditor.LedgerGroups | Iterates available ledger groups, excluding other rows’ selections. |
ClassificationsEditor.LedgerGroup | Wrapper exposing data-type and data-label. |
ClassificationsEditor.LedgerGroupLabel | Current ledger group display name. |
ClassificationsEditor.LedgerItems | Iterates available ledger options; provides context for LedgerItem. |
ClassificationsEditor.LedgerItem | Renders one option with value and data-value; use within LedgerItems. Supports asChild for a select item. |
ClassificationsEditor.CategoryPercentage | Numeric input for a split share. |
ClassificationsEditor.RemoveCategory | Removes the containing category row. |
ClassificationsEditor.AddCategory | Adds a split row; splits evenly until a share is explicitly edited. |
ClassificationsEditor.IsSplit | Gate when more than one category exists. |
ClassificationsEditor.NotSplit | Gate for a single category. |
ClassificationsEditor.SplitTotal | Sum of category or tag shares; accepts format(number), with data-complete at 100. |
ClassificationsEditor.TagField | Select binding for the tag field name. |
ClassificationsEditor.TagFieldItems | Iterates available tag field options; provides context for TagFieldItem. |
ClassificationsEditor.TagFieldItem | Renders one option with value and data-value; use within TagFieldItems. Supports asChild for a select item. |
ClassificationsEditor.HasTagField | Gate once a tag field is selected. |
ClassificationsEditor.IsTagSplit | Gate with multiple tag rows. |
ClassificationsEditor.NotTagSplit | Gate for a single tag row. |
ClassificationsEditor.Tags | Iterates tag rows. |
ClassificationsEditor.TagRow | Wrapper exposing data-key. |
ClassificationsEditor.TagValue | Select binding for the current tag value. |
ClassificationsEditor.TagValueItems | Iterates available tag value options; provides context for TagValueItem. |
ClassificationsEditor.TagValueItem | Renders one option with value and data-value; use within TagValueItems. Supports asChild for a select item. |
ClassificationsEditor.TagPercentage | Numeric input for the current tag share. |
ClassificationsEditor.RemoveTag | Removes the containing tag row. |
ClassificationsEditor.AddTag | Adds another tag row. |
ClassificationsEditor.useClassificationsEditor | Root 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.useCondition | Current condition row hook; use within Conditions. |
ClassificationsEditor.useCategoryRow | Current category row hook; use within Categories. |
ClassificationsEditor.useTagRow | Current tag row hook; use within Tags. |
ClassificationsEditor.useMerchantMatch | Current merchant and match-highlight offsets; use within MerchantMatches. |
ClassificationsEditor.scopes | Required 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.