Recommended pattern for showing a single current field error with errorMap?

[dpkass]

TanStack Form exposes field validation results by cause via errorMap (onChange, onBlur, onSubmit, etc.), which is flexible, but I’m unsure what the recommended UX pattern is when an app wants to show only one current error per field.

This feels especially difficult with form-level schema validation, because blurring one field can populate onBlur errors for other fields at the same time. Later, when the user starts editing one of those fields, that field may also get onChange validation, so multiple causes can be present in errorMap for the same field. At that point, it’s not obvious which error should be displayed to the user.

Without using onDynamic/revalidateLogic, is there an intended pattern for collapsing errorMap into one displayed field error when using form-level schemas? Or is the expectation that apps implement their own precedence / active-cause tracking on top of errorMap?

[sueun-dev]

There's no built-in "show one error" helper — TanStack Form intentionally exposes all causes and leaves the display logic to apps. But the pattern is straightforward.

Without revalidateLogic: priority-based selection

Since each cause in errorMap holds a single value (whatever your validator returns), you just pick by priority:

const displayError =
  field.state.meta.errorMap.onChange ??  // currently typing — most current
  field.state.meta.errorMap.onBlur ??    // touched and left
  field.state.meta.errorMap.onSubmit     // submitted invalid

{displayError && <em>{String(displayError)}</em>}

Why onChange first: it reflects the live value as the user types. If onChange errors are absent (user hasn't edited this field yet), you fall through to onBlur, then onSubmit. This handles the cascade case you described — when a form-level validator sets onBlur errors on multiple fields simultaneously, unedited fields show their onBlur error while the field being actively typed into shows onChange.

field.state.meta.errors is Object.values(errorMap).filter(Boolean).flat(1) — useful if you just need "any error", but the order is insertion-order so it doesn't give you predictable priority.

The clean solution: revalidateLogic + onDynamic

If you're open to revisiting the "without onDynamic" constraint, this was added in v1 specifically to solve this UX problem (PR #1622). It routes everything through a single cause key so stale-cause overlap never happens:

import { revalidateLogic, useForm } from '@tanstack/react-form'

const form = useForm({
  validationLogic: revalidateLogic({
    mode: 'submit',               // no live validation before first submit
    modeAfterSubmission: 'change', // clear errors as user fixes them after submit
  }),
  validators: {
    onDynamic: yourZodSchema,
  },
})

With this setup, each field only ever has errorMap.onDynamic populated — no separate onBlur/onChange keys accumulating independently. Displaying a single error is just field.state.meta.errorMap.onDynamic.

The mode: 'submit' behavior matches what most users expect: validate silently until submit, then show errors, then clear them as the user fixes each field.

One caveat: there's a known bug (#1861) where event.fieldName is always undefined inside a custom validationLogic function, so if you want custom routing logic beyond what revalidateLogic provides you'll hit that for now. Using revalidateLogic() directly is unaffected.

[dpkass]

Thank you for your response. I think my previous framing of the question wasn't so clear, so I'll be more concrete:

A detail that seems important here is that with form-level schema validation, the validation cause and the field interaction are not necessarily the same thing. A validation run triggered by one field can populate errorMap entries for other fields as well, even if those other fields have not been changed or blurred themselves.

In our case, some of that can be handled at the display layer, for example by only showing onBlur errors once the field itself has actually been blurred (isBlurred/isTouched flags).
But I’m still unsure about indirect updates, e.g. cascading fields. For example, imagine typeId determines the allowed statusId options, and changing typeId also auto-selects the default statusId (which also sets isTouched). Now say statusId previously had an onBlur error (from interacting with an unrelated field), but later becomes valid indirectly because typeId changed and updated statusId.

The docs propose onChangeListenTo, but as far as I understand it, that only revalidates statusId on the change cause. It would not clear the older onBlur entry for statusId, so in that case the stale onBlur error would still have to be manually purged from errorMap, no?

RHF vs TSF

Part of why this still feels tricky to me is that React Hook Form is more field-local during normal interactions: when the user edits one field, validation is triggered from that field event and the resulting error update is scoped to that field.

That difference becomes most noticeable with dependent fields like the typeId / statusId example above, because RHF does not really run into this class of issue: it keeps one current error state per field, and indirectly setting a dependent field revalidates that field rather than leaving parallel cause buckets behind.

And I feel like TSF should maybe find a way to mirror that behavior, because 1. having blur errors on fields that haven't been touched before seems paradoxical (though you can work around that with the flags), and 2. stale errors become a real concern.

I hope this make clear, where I was coming from. Please correct me if I misunderstood something, maybe my concern is too much of an edge case.

[dpkass]

While rewriting my response for the 15th time, I realized my earlier example is mostly covered by gating display with isBlurred, since indirect value updates do not set isBlurred, so an old onBlur error would stay hidden.

The edge case seems to be when the dependent field had already been blurred earlier. For example: blur statusId while empty so it gets an onBlur error, then go back and change typeId, which indirectly sets statusId to a valid value. In that case, the old onBlur entry can still remain even though statusId is now valid.