React Hook Form 17 📋 Async Validation — Server-side checks and debounced validation - KandZ

⏱️ Estimated read: 15 min | |

The synchronous validation runs the client-side rules and returns the result immediately. The asynchronous validation sends the value to the server or the external service and waits for the response. The React Hook Form supports both, and the difference is not the API surface—the validate rule accepts the async function the same way it accepts the sync one. The difference is the timing, the race conditions, and the user experience. The async validation is the mechanism that lets the form check the value against the server, and the debounce is the mechanism that keeps the server from being flooded with the request on every keystroke.

Quick How-To Guides & Fast FixesNeed a quick fix or step-by-step solution? Browse our fast answers on HowTo.KandZ.me:

Operating Systems CLI →Dev Environment Languages →Web Network Tools →Security Accounts →Security Access Tech →Device Phone Basics →Social Messaging →Digital Files Media →

The validate rule is the built-in mechanism for the custom async check. The function returns the Promise<true | string>, and the resolver awaits the promise before it decides the field’s validity. The setError is the mechanism for the server error that the async check produces, and the formState.isValidating is the mechanism that the UI reads to show the pending state. The useForm‘s mode: "onChange" is the trigger that runs the validation on every change, and the useForm‘s delayError is the mechanism that postpones the error display until the async check settles.

The debounce is the separate concern. The lodash.debounce or the use-debounce hook is the mechanism that delays the validation call, and the delay is the reason the server is not hit on every keystroke. The React Hook Form documentation recommends the debounce for the async validation, and the useEffect with the setTimeout is the simple alternative. The debounce and the async check are the two halves of the pattern: the debounce reduces the request count, and the async check verifies the value.

Key point: The validate rule accepts the async function and returns the Promise<true | string>. The mode: "onChange" runs the validation on every change, and the delayError postpones the error display until the async check settles. The debounce is the mechanism that delays the validation call, and the race condition is the risk when the multiple requests are in flight. The useEffect cleanup or the AbortController is the mechanism that cancels the stale request, and the cancellation is the reason the older response cannot overwrite the newer one.

Why the async validation needs the debounce

The request-flood problem. The mode: "onChange" runs the validation on every keystroke. The synchronous validation is the cheap local check, and the repeated call is invisible. The asynchronous validation sends the network request, and the repeated call is the server load. The typing of the username field with the ten characters sends the ten requests, and the ten requests are the waste. The debounce is the mechanism that delays the call until the user pauses, and the pause is the reason the server sees the one request instead of the ten .

The race-condition problem. The user types the alice, and the request is sent. The user continues to the alice2, and the second request is sent. The first response arrives after the second, and the stale alice result overwrites the alice2 result. The race is the mechanism that produces the wrong error, and the wrong error is the confusing UX. The useEffect cleanup or the AbortController is the mechanism that cancels the stale request, and the cancellation is the reason the older response cannot overwrite .

The pending-state problem. The async validation takes the time, and the UI should show the pending state. The formState.isValidating is the mechanism that the UI reads, and the pending state is the reason the user knows the check is running. The delayError is the mechanism that postpones the error display until the check settles, and the delay is the reason the error does not flash while the user is still typing .

The server-error problem. The async validation can fail with the server’s validation error, the network error, or the unexpected exception. The setError is the mechanism that maps the server error to the field, and the mapping is the reason the server error appears in the same place as the client error . The errors.field.type is the mechanism that distinguishes the server error from the client error, and the distinction is the reason the UI can show the different messages.

The server-vs-client problem. The async validation is the network call, and the network call is the slow. The client validation should run first, and the async validation should run only when the client validation passes. The validate rule with the two functions is the mechanism that runs both, and the client-first is the reason the server is not hit with the obviously invalid value.

a. The async `validate` rule and the pending state

The validate rule accepts the async function, and the function returns the true for the valid value or the string for the invalid value. The mode: "onChange" is the trigger that runs the validation on every change.

// The async validate rule
import { useForm } from "react-hook-form";

type SignUpFormValues = {
  username: string;
};

function SignUpForm() {
  const {
    register,
    handleSubmit,
    formState: { errors, isValidating },
  } = useForm<SignUpFormValues>({
    // The onChange mode runs the validation on every change.
    mode: "onChange",
    // The delayError postpones the error display.
    delayError: 500,
    defaultValues: { username: "" },
  });

  return (
    <form onSubmit={handleSubmit((data) => console.log(data))}>
      <input
        {...register("username", {
          // The async validate function.
          validate: async (value) => {
            // The client check runs first.
            if (value.length < 3) return "At least 3 characters.";

            // The server check runs only when the client check passes.
            const response = await fetch(
              `/api/username-available?value=${encodeURIComponent(value)}`
            );
            const { available } = await response.json();
            return available || "This username is taken.";
          },
        })}
      />
      {/* The pending state is shown while the check runs. */}
      {isValidating && <p>Checking...</p>}
      {errors.username && <p role="alert">{errors.username.message}</p>}
      <button type="submit">Sign up</button>
    </form>
  );
}

The validate: async (value) => { ... } is the mechanism that runs the async check. The value.length < 3 is the client check that runs first, and the fetch is the server check that runs only when the client check passes . The isValidating is the mechanism that the UI reads to show the pending state, and the pending state is the reason the user knows the check is running.

The delayError: 500 is the mechanism that postpones the error display for the 500 milliseconds. The delay is the reason the error does not flash while the user is still typing, and the delay is the mechanism that makes the async validation feel less aggressive .

The errors.username.type is the mechanism that distinguishes the server error from the client error. The type is the rule name, and the "validate" is the type when the custom validate rule fails .

// The error type
{errors.username && (
  <p role="alert">
    {errors.username.type === "validate" ? "Server says: " : ""}
    {errors.username.message}
  </p>
)}

The errors.username.type is the mechanism that lets the UI show the different messages, and the different messages are the reason the user understands the source of the error.

b. The debounce and the race-condition handling

The debounce is the mechanism that delays the validation call. The lodash.debounce is the common implementation, and the use-debounce hook is the React-friendly alternative.

// The debounced async validation
import { useForm } from "react-hook-form";
import { useCallback } from "react";
import debounce from "lodash.debounce";

function SignUpForm() {
  const {
    register,
    handleSubmit,
    setError,
    clearErrors,
    formState: { errors, isValidating },
  } = useForm<SignUpFormValues>({
    mode: "onChange",
    delayError: 500,
  });

  // The debounced check runs 500ms after the last call.
  const checkUsername = useCallback(
    debounce(async (value: string) => {
      const response = await fetch(
        `/api/username-available?value=${encodeURIComponent(value)}`
      );
      const { available } = await response.json();

      if (!available) {
        // The setError maps the server error to the field.
        setError("username", {
          type: "server",
          message: "This username is taken.",
        });
      } else {
        clearErrors("username");
      }
    }, 500),
    [setError, clearErrors]
  );

  return (
    <form onSubmit={handleSubmit((data) => console.log(data))}>
      <input
        {...register("username", {
          validate: (value) => {
            // The debounced check runs in the background.
            checkUsername(value);
            // The validate returns true and the error is set later.
            return true;
          },
        })}
      />
      {isValidating && <p>Checking...</p>}
      {errors.username && <p role="alert">{errors.username.message}</p>}
    </form>
  );
}

The debounce(async (value) => { ... }, 500) is the mechanism that delays the call for the 500 milliseconds after the last keystroke. The setError is the mechanism that maps the server error, and the clearErrors is the mechanism that removes the error when the value becomes available . The validate: (value) => { checkUsername(value); return true; } is the mechanism that triggers the debounced check and returns the immediate valid result, and the later error is the mechanism that corrects the result.

The race condition is the separate problem. The useEffect cleanup or the AbortController is the mechanism that cancels the stale request, and the cancellation is the reason the older response cannot overwrite the newer one.

// The AbortController for the race condition
import { useEffect, useState } from "react";

function useUsernameAvailability(value: string) {
  const [available, setAvailable] = useState<boolean | null>(null);

  useEffect(() => {
    // The AbortController cancels the stale request.
    const controller = new AbortController();

    const check = async () => {
      try {
        const response = await fetch(
          `/api/username-available?value=${encodeURIComponent(value)}`,
          { signal: controller.signal }
        );
        const data = await response.json();
        setAvailable(data.available);
      } catch (error) {
        // The abort is the expected error when the value changes.
        if (error.name !== "AbortError") throw error;
      }
    };

    check();

    // The cleanup aborts the previous request.
    return () => controller.abort();
  }, [value]);

  return available;
}

The controller.abort() in the cleanup is the mechanism that cancels the previous request when the value changes. The signal: controller.signal is the mechanism that connects the fetch to the controller, and the connection is the reason the abort works. The error.name !== "AbortError" is the mechanism that distinguishes the expected abort from the real error, and the distinction is the reason the abort does not throw.

The formState.isValidating is the mechanism that the UI reads for the pending state, and the delayError is the mechanism that postpones the error display. The two are the reasons the async validation feels responsive, and the responsiveness is the reason the user does not abandon the form.

Complete Example Session

// ============================================
// PART 1: THE ASYNC VALIDATE RULE
// ============================================

import { useForm } from "react-hook-form";

function SignUpForm() {
  const { register, handleSubmit, formState: { errors, isValidating } } = useForm<SignUpFormValues>({
    mode: "onChange",
    delayError: 500,
  });

  return (
    <form onSubmit={handleSubmit((data) => console.log(data))}>
      <input
        {...register("username", {
          validate: async (value) => {
            if (value.length < 3) return "At least 3 characters.";
            const response = await fetch(`/api/username-available?value=${value}`);
            const { available } = await response.json();
            return available || "This username is taken.";
          },
        })}
      />
      {isValidating && <p>Checking...</p>}
      {errors.username && <p role="alert">{errors.username.message}</p>}
    </form>
  );
}

// ============================================
// PART 2: THE CLIENT-FIRST CHECK
// ============================================

// The client check runs first.
// The server check runs only when the client check passes.

// ============================================
// PART 3: THE DELAY ERROR
// ============================================

useForm({ mode: "onChange", delayError: 500 });

// The error display is postponed for 500ms.

// ============================================
// PART 4: THE DEBOUNCE
// ============================================

const checkUsername = useCallback(
  debounce(async (value: string) => {
    const response = await fetch(`/api/username-available?value=${value}`);
    const { available } = await response.json();
    if (!available) setError("username", { type: "server", message: "Taken." });
  }, 500),
  [setError]
);

// The debounce delays the call for 500ms.

// ============================================
// PART 5: THE ABORT CONTROLLER
// ============================================

useEffect(() => {
  const controller = new AbortController();
  const check = async () => {
    try {
      const response = await fetch(url, { signal: controller.signal });
      setAvailable((await response.json()).available);
    } catch (error) {
      if (error.name !== "AbortError") throw error;
    }
  };
  check();
  return () => controller.abort();
}, [value]);

// The AbortController cancels the stale request.

// ============================================
// PART 6: THE SERVER ERROR
// ============================================

setError("username", { type: "server", message: "This username is taken." });

// The setError maps the server error to the field.

// ============================================
// PART 7: THE ERROR TYPE
// ============================================

{errors.username?.type === "server" && <p>Server error</p>}

// The errors.username.type distinguishes the source.

// ============================================
// PART 8: THE PENDING STATE
// ============================================

{isValidating && <p>Checking...</p>}

// The isValidating is the pending state.

// ============================================
// PART 9: THE CLEANUP
// ============================================

useEffect(() => {
  checkUsername(value);
  return () => checkUsername.cancel();
}, [value, checkUsername]);

// The debounce cancel is the cleanup.

// ============================================
// PART 10: THE CHECKLIST
// ============================================

// [ ] The validate rule is the async function.
// [ ] The client check runs first.
// [ ] The mode is "onChange" for the live validation.
// [ ] The delayError postpones the error display.
// [ ] The debounce delays the validation call.
// [ ] The AbortController cancels the stale request.
// [ ] The setError maps the server error.
// [ ] The isValidating shows the pending state.

The ten parts covered the async validate rule, the client-first check, the delay error, the debounce, the AbortController, the server error, the error type, the pending state, the cleanup, and the checklist. The through-line is that the async validation is the network call, and the debounce and the cancellation are the mechanisms that keep it responsive and correct.

Quick Reference

The async validation options

Option	Purpose
`mode: "onChange"`	Run the validation on every change
`mode: "onBlur"`	Run the validation on blur
`delayError`	Postpone the error display
`validate`	The async or sync custom check

The form state

Property	Meaning
`isValidating`	The validation is running
`isSubmitting`	The submission is running
`errors.field.type`	The rule name

The debounce

Implementation	Purpose
`lodash.debounce`	The debounced function
`use-debounce`	The React hook
`setTimeout`	The manual delay

The race-condition handling

Mechanism	Purpose
`AbortController`	Cancel the stale request
The `useEffect` cleanup	Abort on the value change
The `signal` option	Connect the fetch to the controller

Best Practices

✅ Do This:

// Use the client check first
validate: async (value) => {
  if (value.length < 3) return "Too short.";
  return await checkServer(value);
}                                                                 // ✅

// Use the debounce for the server check
const check = useCallback(debounce(checkServer, 500), []);         // ✅

// Use the AbortController for the race condition
return () => controller.abort();                                  // ✅

// Use the isValidating for the pending state
{isValidating && <p>Checking...</p>}                              // ✅

❌ Don’t Do This:

// Send the server request on every keystroke
validate: async (value) => await checkServer(value) // the flood      // ❌

// Ignore the race condition
useEffect(() => { checkServer(value); }, [value]) // the stale response // ❌

// Show the error while the check is running
{errors.username && <p>{errors.username.message}</p>} // the flash  // ❌

Common Pitfalls

Pitfall	Why It Happens	Fix
The server is flooded	The validation runs on every keystroke	Use the debounce
The stale response overwrites	The race condition is not handled	Use the `AbortController`
The error flashes	The `delayError` is not set	Set the delay
The pending state is not shown	The `isValidating` is not read	Read the `isValidating`

Real-World Examples

1. The async validate

validate: async (value) => await checkServer(value)

2. The client-first check

validate: async (v) => v.length < 3 ? "Too short." : await checkServer(v)

3. The delay error

useForm({ delayError: 500 })

4. The debounce

const check = useCallback(debounce(checkServer, 500), [])

5. The AbortController

const controller = new AbortController();
fetch(url, { signal: controller.signal });

6. The cleanup

return () => controller.abort();

7. The setError

setError("username", { type: "server", message: "Taken." })

8. The error type

errors.username?.type === "server"

9. The pending state

{isValidating && <p>Checking...</p>}

10. The debounce cancel

return () => check.cancel();

Visual

The Async Validation Flow

┌──────────────────────────────────────────────────────────────┐
│  THE ASYNC VALIDATION FLOW                                   │
│                                                              │
│  The user types                                              │
│         │                                                    │
│         ▼                                                    │
│  ┌─────────────────────┐                                    │
│  │ The client check    │  The fast local validation         │
│  └──────────┬──────────┘                                    │
│             │                                                │
│             ▼                                                    │
│  ┌─────────────────────┐                                    │
│  │ The debounce        │  The 500ms delay                   │
│  └──────────┬──────────┘                                    │
│             │                                                │
│             ▼                                                    │
│  ┌─────────────────────┐                                    │
│  │ The server check    │  The network request               │
│  └──────────┬──────────┘                                    │
│             │                                                │
│             ▼                                                    │
│  ┌─────────────────────┐                                    │
│  │ The setError or     │  The result                        │
│  │ clearErrors         │                                    │
│  └─────────────────────┘                                    │
└──────────────────────────────────────────────────────────────┘

The Race Condition

┌──────────────────────────────────────────────────────────────┐
│  THE RACE CONDITION                                          │
│                                                              │
│  The type "alice" → the request 1                            │
│  The type "alice2" → the request 2                           │
│         │                                                    │
│         ▼                                                    │
│  ┌─────────────────────┐                                    │
│  │ The response 2      │  The newer result                  │
│  │ arrives first       │                                    │
│  └──────────┬──────────┘                                    │
│             │                                                │
│             ▼                                                    │
│  ┌─────────────────────┐                                    │
│  │ The response 1      │  The stale result                  │
│  │ arrives late        │  The overwrite without the abort   │
│  └─────────────────────┘                                    │
│                                                              │
│  The AbortController cancels the request 1.
└──────────────────────────────────────────────────────────────┘

The Debounce

┌──────────────────────────────────────────────────────────────┐
│  THE DEBOUNCE                                                │
│                                                              │
│  The keystroke 1 → the timer starts                          │
│  The keystroke 2 → the timer resets                          │
│  The keystroke 3 → the timer resets                          │
│  The pause → the timer fires → the request                   │
│                                                              │
│  The one request instead of the three.                       │
└──────────────────────────────────────────────────────────────┘

Summary

Item	Value
The async rule	The `validate` function returns the `Promise<true \| string>`
The trigger	The `mode: "onChange"`
The delay	The `delayError` postpones the error display
The pending state	The `formState.isValidating`
The debounce	The `lodash.debounce` or the `use-debounce`
The race condition	The `AbortController` cancels the stale request
The server error	The `setError` maps it to the field

Key takeaways:

The validate rule accepts the async function. The function returns the Promise<true | string>, and the resolver awaits the promise before it decides the field’s validity . The client check runs first, and the server check runs only when the client check passes.
The delayError postpones the error display. The delay is the mechanism that prevents the error from flashing while the user is still typing, and the delay is the reason the async validation feels less aggressive .
The debounce is the mechanism that reduces the request count. The lodash.debounce or the use-debounce delays the call until the user pauses, and the pause is the reason the server sees the one request instead of the ten.
The race condition is the risk when the multiple requests are in flight. The AbortController or the useEffect cleanup is the mechanism that cancels the stale request, and the cancellation is the reason the older response cannot overwrite the newer one.
The isValidating is the pending-state mechanism. The UI reads the isValidating to show the pending state, and the pending state is the reason the user knows the check is running.

Remember: The React Hook Form async validation is the validate rule and the debounce. The validate rule is the async check, and the mode: "onChange" is the trigger. The delayError postpones the error display, and the isValidating shows the pending state. The debounce reduces the request count, and the AbortController cancels the stale request. The async validation is the network call, and the debounce and the cancellation are the mechanisms that keep it responsive and correct.

Was this helpful?

Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!