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 submission
const submitHandler = (values, options /* Useful helpers */, e) => {
console.log("onSubmit: ", values);
};
// Asynchronous submission
const 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>
</>
);
};