Validation Guide

React Cool Form supports a wide range of synchronous and asynchronous validation strategies for built-in, form-level, and field-level validation to cover all the cases that you need.

Built-in Validation#

We support HTML5 form validation out of the box, a quick and easy way for form validation.

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

const App = () => {
  const { form } = useForm({
    defaultValues: { name: "", email: "", password: "" },
    onSubmit: (values) => console.log("onSubmit: ", values),
    onError: (errors) => console.log("onError: ", errors),
  });

  return (
    <form ref={form} noValidate>
      <input name="name" placeholder="Name" required />
      <input name="email" type="email" placeholder="Email" required />
      <input
        name="password"
        type="password"
        placeholder="Password"
        required
        minLength={6}
      />
      <input type="submit" />
    </form>
  );
};

Some validation attributes like minLength, maxLength, min, and max are designed to validate a field once it has been edited by the user. If your validation relies on the related methods, use the pattern attribute or custom validation instead.

<input name="password" required pattern=".{6,}" /> // 6 characters minimum

Form-level Validation#

Runs validation by accessing the complete values of the form (a.k.a formState.values). It's useful to validate dependent fields at the same time.

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

// Synchronous validation
const validate = (values, actions) => {
  const errors = {};

  if (!values.email.length) {
    errors.email = "Required";
  } else if (!/^[A-Z0-9._-]+@[A-Z0-9.-]+\.[A-Z]{2,4}$/i.test(values.email)) {
    errors.email = "Invalid email address";
  }

  // ...

  return errors;
};

// Asynchronous validation
const validate = async (values, actions) => {
  const errors = {};
  const hasUser = await validateOnServer(values.name);

  if (!hasUser) errors.name = "User doesn't exist";

  // ...

  return errors;
};

const App = () => {
  const { form } = useForm({
    defaultValues: { name: "", email: "" },
    validate,
    onSubmit: (values) => console.log("onSubmit: ", values),
    onError: (errors) => console.log("onError: ", errors),
  });

  return (
    <form ref={form} noValidate>
      <input name="name" placeholder="Name" />
      <input name="email" type="email" placeholder="Email" />
      <input type="submit" />
    </form>
  );
};

Field-level Validation#

Coming soon...

When Does Validation Run?#

By default, React Cool Form runs the above validation methods as below, you can tell React Cool Form when to run validation by the validateOnChange and/or validateOnBlur depends on your needs.

Event/method	Timing
`onChange`	Whenever the value of a field has been changed.
`setFieldValue`	Whenever the value of a field has been set.
`setValues`	Whenever the `values` of the formState has been set.
`onBlur`	Whenever a field has been touched. If a validation method has been run by the `onChange` event, it won't be run again.
`onSubmit`	Whenever a submission attempt is made.
`submit`	Whenever a submission attempt is made manually.
`validateField`	Manually run field-level validation.
`validateForm`	Manually run form-level validation.

Manually Triggering Validation#

Coming soon...

Displaying Error Messages#

Coming soon...