Server errors and value changes

Use Simulate server error to inject an error for email, then Clear error to remove it. The latest-value display uses onValuesChange. This demo does not send a network request.

Usage

Use your form instance from useForm. See the initial setup.

const message = "This email is already registered.";

form.setFieldMeta("email", (meta) => ({
  ...meta,
  errorMap: { ...meta.errorMap, onServer: message },
}));

<ErlForm
  form={form}
  schema={schema}
  serverErrors={{ email: message }}
/>

serverErrors is a record keyed by field name/path with a string or readonly array of strings for each value. Nested paths include profile.email or contacts[0].phone. Global request errors should be displayed through your application's own state.

Compatibility in 1.0.0

With the TanStack Form version used by this site, meta.errors is derived from errorMap. Erlangform 1.0.0 writes serverErrors directly to meta.errors, so the prop alone may not display the message. The demo also writes the message to errorMap.onServer through form.setFieldMeta. This is application-level compatibility code, not an automatic behavior of ErlForm. Use the same approach when mapping your API errors.

Mapping an API response

// Inside your useForm onSubmit callback:
const response = await fetch("/api/email", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(value),
});
if (response.status === 422) {
  // Application contract: { errors: { email: "This email is already registered" } }
  const result = await response.json() as { errors: ServerErrors };
  setErrors(result.errors);
  const emailError = result.errors.email;
  form.setFieldMeta("email", (meta) => ({
    ...meta,
    errorMap: { ...meta.errorMap, onServer: Array.isArray(emailError) ? emailError[0] : emailError },
  }));
  return;
}
if (!response.ok) throw new Error("Request failed");

Create your endpoint, import ServerErrors, and validate the response shape before using it in production. Catch request failures and display a retry message; use isSubmitting to prevent duplicate requests.

Clearing stale errors

The renderer writes meta.errors only for keys supplied in serverErrors. Replacing it with an empty object or undefined does not explicitly clear old messages. Supply an empty array for each key, such as { email: [] }, and clear errorMap.onServer to undefined if using the compatibility mapping above. Later validation may overwrite metadata; serverErrors is not a separate error store.

Observing values

onValuesChange runs in an effect with complete form values, including on mount and for hidden fields. Pass a stable callback, for example with useCallback. It receives values, not a DOM event.

For autosave, manage debouncing, pending requests, and cleanup in your application. Avoid unconditional state writes back into the same form callback, which can create update loops.