Skip to main content

Form Submission

It's dead simple to submit a form in React Cool Form. All we need to do is to use an <input type="submit"> or <button type="submit"> element to fire the form's onSubmit event. Moreover, we can also manually trigger a submission by the submit method of React Cool Form, which can help us overcome any kinds of design challenges easily.

Submit a Form#

This is the most common case that we submit a form in React Cool Form.

import { useForm } from "react-cool-form";
// Synchronous submissionconst submitHandler = (values, options /* Useful helpers */, e) => {  console.log("onSubmit: ", values);};
// Asynchronous submissionconst submitHandler = async (values, options, e) => {  await new Promise((r) => setTimeout(r, 2000));  console.log("onSubmit: ", values);};
const errorHandler = (errors, options, e) => {  console.log("onError: ", errors);};
const App = () => {  const { form, use } = useForm({    defaultValues: { username: "", email: "" },    onSubmit: submitHandler, // The event is triggered once the form is valid    onError: errorHandler, // The event is triggered once the form is invalid (optional)  });  const isSubmitting = use("isSubmitting");
  return (    <form ref={form} noValidate>      <input name="username" required />      <input name="email" required />      <input type="submit" disabled={isSubmitting} />    </form>  );};

Submission Phases#

You might be curious about what happened after we clicked the submit button? Whenever a form is attempting to be submitted, React Cool Form will execute the following procedures:

Pre-submit#

  • Touches all fields (for displaying errors)
  • Sets formState.isSubmitting to true
  • Increments formState.submitCount by 1

Validation#

Check for Errors#

Are there any errors?

  • Yes (Invalid): Runs the form's onError handler, jumps to "Post-submit"
  • No (Valid): Proceeds to "Submission"

Submission#

  • Runs the form's onSubmit handler
  • Once the submission is completed, sets formState.isSubmitted to true

Post-submit#

  • Sets formState.isSubmitting to false

👉🏻 See the Form State to learn more about it.

Manually Triggering Submission#

For some reasons (e.g. design requirement, auto-retry, etc.), we might need to trigger a submission manually. However, we can use the submit method to achieve it.

import { useForm } from "react-cool-form";
const App = () => {  const { form, use, submit } = useForm({    defaultValues: { username: "", email: "" },    onSubmit: (values) => console.log("onSubmit: ", values),    onError: (errors) => console.log("onError: ", errors),  });  const isSubmitting = use("isSubmitting");
  const handleSubmit = () => {    submit();  };
  // Handle submit with result, so we don't have to rely on the event handlers  const handleSubmit = async () => {    const { errors, values } = await submit();
    if (errors) {      // Do something for invalid case    } else {      // Do something for valid case    }  };
  return (    <>      <ActionBar>        <button onClick={handleSubmit} disabled={isSubmitting}>          Submit        </button>      </ActionBar>      <form ref={form} noValidate>        {/* ... */}      </form>    </>  );};