# Formik Field-Level Validation

When should a Formik form validate a field with its own validate function instead of the form’s Yup validationSchema — and how do you make a field-level async check (username availability, coupon validity) that does not fire on every keystroke, does not let an old response overwrite a newer one, and does not steal focus? Formik runs field-level validators alongside the schema and merges their results into the same errors map, which makes them the right tool for rules that need their own timing or context. This recipe builds a debounced, cancellable availability check as a field-level validator, adds a dependent-field rule, and renders every error accessibly, with focus on submit handled the same way the native Constraint Validation API would handle it.

# When to Use Field-Level Validation in Formik

Keep most rules in the Yup schema — it is declarative, testable and shareable. Reach for field-level validate when a rule:

• Is asynchronous and expensive, such as a server lookup that should run on blur, not with every schema pass.
• Needs its own caching or debouncing, which a schema cannot express.
• Belongs to a reusable field component that should validate itself regardless of which form it sits in.
• Depends on context outside the values, such as the current user or feature flags.

Cross-field rules that only need other values can live in the schema with yup.ref or .test; the dependent rule below uses field-level validation only to show how Formik passes values. The form-level setup is covered in the Formik and Yup validation topic.

# Minimal Working Field-Level Async Validator

import { Formik, Form, Field, getIn, type FieldProps } from "formik";
import * as yup from "yup";

const schema = yup.object({
  username: yup.string().trim().min(3, "Username must be at least 3 characters.").required("Choose a username."),
  email: yup.string().email("Enter an email address like name@example.com.").required("Enter your email address."),
});

/** Debounced, cancellable, cached availability check usable as a Formik field validator. */
function createAvailabilityValidator(delay = 400) {
  const cache = new Map<string, string>();          // value → error ("" = available)
  let controller: AbortController | undefined;
  let timer: ReturnType<typeof setTimeout> | undefined;

  return (value: string): Promise<string | undefined> => {
    const v = value.trim().toLowerCase();
    if (v.length < 3) return Promise.resolve(undefined);   // schema reports length; skip network
    if (cache.has(v)) return Promise.resolve(cache.get(v) || undefined);
    controller?.abort();
    clearTimeout(timer);
    return new Promise((resolve) => {
      timer = setTimeout(async () => {
        controller = new AbortController();
        try {
          const res = await fetch(`/api/usernames/available?u=${encodeURIComponent(v)}`, { signal: controller.signal });
          const error = (await res.json()).available ? "" : "That username is taken. Try adding a number.";
          cache.set(v, error);
          resolve(error || undefined);
        } catch (e) {
          // Aborted: a newer check supersedes this one; unknown: let the server decide on submit.
          resolve(undefined);
        }
      }, delay);
    });
  };
}

const validateUsername = createAvailabilityValidator();

function TextField({ name, label, validate }: { name: string; label: string; validate?: (v: string) => Promise<string | undefined> | string | undefined }) {
  return (
    <Field name={name} validate={validate}>
      {({ field, form }: FieldProps) => {
        const error = (getIn(form.touched, name) || form.submitCount > 0) && getIn(form.errors, name);
        return (
          <div className="field">
            <label htmlFor={name}>{label}</label>
            <input id={name} {...field} aria-invalid={error ? true : undefined} aria-describedby={`${name}-err`} />
            <p id={`${name}-err`} className="field-error" hidden={!error}>{error || ""}</p>
          </div>
        );
      }}
    </Field>
  );
}

export function SignupForm() {
  return (
    <Formik initialValues={{ username: "", email: "" }} validationSchema={schema}
            validateOnChange={false} onSubmit={submitSignup}>
      {({ isValidating, isSubmitting }) => (
        <Form noValidate aria-busy={isValidating || isSubmitting}>
          <TextField name="username" label="Username" validate={validateUsername} />
          <TextField name="email" label="Email address" />
          <button type="submit" aria-disabled={isSubmitting}>Create account</button>
        </Form>
      )}
    </Formik>
  );
}

Formik awaits field-level validators on submit, so a pending availability check is resolved before onSubmit runs — the submit cannot slip through with an unchecked username. With validateOnChange: false, the check runs on blur and on submit rather than on every keystroke, and the cache means a user who tabs back and forth does not trigger repeated requests.

# Field-Level Validator Option Reference

# Verification Steps

• Type a taken username and tab away: after a short pause, the error appears with aria-invalid="true".
• Tab back and forth without changing the value: no new network requests (cache).
• Type quickly and blur, then change the value and blur again: the first request is cancelled and only the newer verdict shows.
• Press Enter immediately after typing a taken username: submission waits for the check and then shows the error.
• Take the API offline: the field is not blocked; the server check on submit decides.

import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { http, HttpResponse } from "msw";
import { setupServer } from "msw/node";
import { expect, it, beforeAll, afterAll } from "vitest";

const server = setupServer(http.get("/api/usernames/available", () => HttpResponse.json({ available: false })));
beforeAll(() => server.listen());
afterAll(() => server.close());

it("shows the availability error after blur", async () => {
  render(<SignupForm />);
  await userEvent.type(screen.getByLabelText("Username"), "ada_l");
  await userEvent.tab();
  expect(await screen.findByText("That username is taken. Try adding a number.")).toBeVisible();
  expect(screen.getByLabelText("Username")).toHaveAttribute("aria-invalid", "true");
});

# Edge Cases and Failure Modes

Races without cancellation. A field validator that simply awaits fetch can resolve out of order: the response for “ada” arrives after the one for “ada_lovelace” and overwrites it. The abort plus debounce in the validator prevents it; a value comparison before resolving is an extra safeguard.

Validators running on every keystroke. With validateOnChange: true (the default), Formik calls field validators on every change. For async validators that means a request per keystroke unless the validator debounces internally — another reason the debounce lives inside it.

Validators recreated on every render. Creating the validator inside the component body gives each render a new debounce timer and an empty cache. Create it once — at module level or with useMemo — so its state survives re-renders.

Returning "" versus undefined. Formik treats an empty string as “no error”, but some helper code checks truthiness differently. Return undefined for valid values to be safe.

Focus stealing when the check completes. Do not call .focus() when an async verdict arrives; the user may already be typing in another field. Let the submit flow move focus, as explained in restoring focus after async validation.

# Showing a Pending State Accessibly

A field-level async validator takes time, and users need to know something is happening. Formik exposes isValidating for the whole form, which is too coarse for one field; track pending state per field inside the validator factory (for example, a small useState in the field component set before the fetch and cleared after) and render “Checking availability…” in a status element referenced by the input’s aria-describedby. Keep the input enabled and focused while checking — disabling it blurs it — and announce the final verdict once through a polite live region only if the user has moved to another field. The same pending and announcement rules are described in restoring focus after async validation; Formik changes nothing about them except where the pending flag lives.

# Dependent Fields at the Field Level

Field-level validators receive only the field’s value, but Formik’s <Field validate> can close over form values through the render prop or a custom hook, which lets a rule depend on another field. A common example: a “state or province” field required only for some countries. Declare it in the schema with yup.string().when("country", …) where possible; when the rule depends on data fetched at runtime (the list of countries that require a state, loaded from an API), a field-level validator that reads that data is clearer. Remember to re-validate the dependent field when its dependency changes, with validateField("state") in the country field’s change handler, or the dependent error stays stale until the user touches the field again.

function StateField({ countriesRequiringState }: { countriesRequiringState: Set<string> }) {
  const { values, validateField } = useFormikContext<{ country: string; state: string }>();
  useEffect(() => { void validateField("state"); }, [values.country]);        // re-check when country changes
  return (
    <TextField name="state" label="State, province or region"
      validate={(v) => (countriesRequiringState.has(values.country) && !v ? "Enter a state, province or region." : undefined)} />
  );
}

# Related Guides

• Formik and Yup Validation — form-level setup and accessibility.
• Migrating from Formik to React Hook Form — moving these validators to a new library.
• Cancelling Stale Requests with AbortController — the cancellation pattern in depth.
• Rate Limiting Async Validation Endpoints — protecting the endpoint the validator calls.

← Back to Formik and Yup Validation