Classifications Editor
Styled drop-in component. 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.
Built on the headless ClassificationsEditor compound from @get-asset/sdk.
Preview
Loading preview…
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 |
|---|---|---|---|
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. |
className | string | — | Additional class on the component shell. Uses the existing Asset theme tokens. |
Behaviour
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.
“Apply to past transactions” appears directly below Action, checked on every mount. Uncheck it to save without applying: edits preserve the rule’s active or archived state, the button reads “Saving…”, the preview stays visible, and onDone fires after saving. An unchanged draft cannot be saved with the checkbox unchecked. The checkbox is disabled while the form is locked and hidden when onSave owns the write.
onSave overrides the write and does not start an apply run. Use onSaveSuccess for a save notification and onDone to leave the editor after applying completes. With the checkbox checked, Apply activates saved rules, including unchanged inactive rules. After a polling request fails, pressing it again resumes the same run; a terminal failed run or refused run request starts a new run without resaving an unchanged active rule.
Editing after a test run keeps its results with a plain bordered notice above the results: “The rule changed since this run.” Selecting a different rule clears the preview and apply state.