Async Validation

Form Wire supports per-field async validation — ideal for checking uniqueness, verifying data against APIs, or any async constraint.

Defining an Async Validator

createFormWire(schema, {
  fields: {
    username: {
      label: "Username",
      asyncValidate: async (value, values) => {
        const exists = await checkUsername(value);
        if (exists) return "That username is already taken";
        return undefined; // pass
      },
    },
  },
});

The validator receives the field value and all current form values. Return a string (error message), string array, or undefined (pass).

Validation Timing

Async validators run according to the configured timing:

Set timing at the provider level:

<FormWireProvider mapper={mapper} validationTiming="onBlur">

Or override per-form:

<Form action={submit} validationTiming="onChange">

Stale Response Protection

Form Wire tracks validation versions. If the user types "ada" → "adam" and the "ada" response arrives after "adam", the stale response is discarded.

Blocking Submit

While async validation is running, the submit button is disabled and shows "Validating..." (or your mapper's status/submit rendering).

Sync Validation First

Async validators only run after sync validation passes. If the field fails the Zod schema check (e.g., too short), the async validator is skipped entirely.

Error Display

Async errors are merged with sync errors and displayed in the same way. They persist until the next successful validation clears them.