gform-react
Back to Guides

Async Validation

Validate against a server with GValidator.withCustomValidationAsync - debounced checks like "is this username taken?" that gate submission while in flight.

Use withCustomValidationAsync for checks that need a server round-trip (e.g. "is this username taken?"). The handler returns a Promise resolving to the same true-means-error contract as a custom validator. Async validators are debounced (default 300 ms, configurable via the debounce prop on GInput) and registered on the same validators object.

const validators: GValidators<SignUpForm> = {
  username: new GValidator()
    .withRequiredMessage("Username is required")
    .withCustomValidationAsync(async (input) => {
      const taken = await checkUsernameTaken(input.value as string);
      if (taken) {
        input.errorText = "That username is taken";
        return true; // error
      }
      return false; // available
    }),
};
<GInput formKey="username" required debounce={500} element={/* … */} />
Pending checks gate submission

While an async check is in flight the field is held invalid with an empty errorText, so state.isInvalid keeps submit disabled until it resolves - you never have to track "is a check running?" yourself. You can surface this state as a hint with input.error && !input.errorText.

Try async validation live

In this sandbox, any username containing "admin" is treated as taken:

Loading playground…

Next