Does disableErrorFlat do anything?

[literalpie]

The documentation makes it sound like disableErrorFlat changes the shape of errors and/or errorMap, but it's not clear to me at all. My understanding is that errors is always flattened and errorMap always includes the information about the "trigger" of the error (onChange, onBlur, etc.)

Stackblitz showing two fields - with and without the property.

[wesleysmyth]

Yes, disableErrorFlat changes what field.state.errors contains, but the difference is subtle.

Default behavior (disableErrorFlat: false)

By default, TanStack Form flattens all errors from nested validators into a single flat array on field.state.errors:

<form.Field
  name="email"
  validators={{
    onChange: ({ value }) => !value ? "Required" : undefined,
    onBlur: ({ value }) => !value.includes("@") ? "Invalid email" : undefined,
  }}
>
  {(field) => {
    // field.state.errors = ["Required", "Invalid email"]
    // All validator errors merged into one flat array
  }}
</form.Field>

With disableErrorFlat: true

<form.Field
  name="email"
  disableErrorFlat
  validators={{
    onChange: ({ value }) => !value ? "Required" : undefined,
    onBlur: ({ value }) => !value.includes("@") ? "Invalid email" : undefined,
  }}
>
  {(field) => {
    // field.state.errors is still an array, BUT:
    // field.state.errorMap gives you errors keyed by validator:
    // {
    //   onChange: "Required",
    //   onBlur: "Invalid email",
    // }
  }}
</form.Field>

What actually changes

The real value is in field.state.errorMap. Without disableErrorFlat, the error map may have its entries merged. With disableErrorFlat: true, each validator's errors stay isolated in the map.

This matters when you want to display different errors differently:

<form.Field name="password" disableErrorFlat validators={{
  onChange: ({ value }) => value.length < 8 ? "Too short" : undefined,
  onSubmit: async ({ value }) => {
    const result = await checkPasswordStrength(value);
    return result.weak ? "Password is too weak" : undefined;
  },
}}>
  {(field) => (
    <div>
      <input {...field.getInputProps()} />
      {/* Show real-time validation inline */}
      {field.state.errorMap.onChange && (
        <span className="hint">{field.state.errorMap.onChange}</span>
      )}
      {/* Show server validation more prominently */}
      {field.state.errorMap.onSubmit && (
        <div className="alert">{field.state.errorMap.onSubmit}</div>
      )}
    </div>
  )}
</form.Field>

TL;DR

	disableErrorFlat: false (default)	disableErrorFlat: true
errors	Flat array of all errors	Flat array of all errors
errorMap	Errors may be merged across validators	Each validator key preserved separately
Use case	Simple "show all errors" UI	Different styling/placement per validator type

The naming is confusing — it doesn't disable errors, it disables the flattening of the error map, keeping validator sources distinct.