Custom submission behavior
Intercept a browser submission to perform custom client-side handling or prevent navigation.
Conform · Pipe
onSubmit
useForm's onSubmit callback runs before form submission and receives the submit event plus submission data. It is also the form-level handler required to enable Conform's client validation.
How it works
Pass onSubmit to useForm to run custom logic before a form submits. Conform invokes it with the submit event and submission details such as formData; when onValidate is configured, this callback runs only after client validation succeeds.
Syntax
useForm({ onSubmit(event, { formData, submission, action, encType, method }) { /* ... */ } })Parameters
| Name | Type | Description |
|---|---|---|
callback arguments | (event, { formData, submission, action, encType, method }) | The submit event and submission context, including formData for the submitted controls. |
Returns
useForm returns a form object whose onSubmit function is used as the form submission handler.
Key points
- The useForm onSubmit option is invoked before the browser submits the form.
- With onValidate configured, the callback is gated by successful client-side validation.
- useForm also returns form.onSubmit, the handler used to submit the form.
Common mistakes
- When client validation is configured, onSubmit is skipped until that validation succeeds.
Example: Intercept a form submission
import { useForm } from '@conform-to/react';
export function ContactForm() {
const [form] = useForm({
onSubmit(event, { formData }) {
event.preventDefault();
console.log(formData.get('email'));
},
});
return (
<form id={form.id} onSubmit={form.onSubmit}>
<label>
Email
<input name="email" type="email" />
</label>
<button type="submit">Send</button>
</form>
);
}The handler runs before submission and can inspect the submitted FormData. Calling preventDefault() keeps the browser submission from proceeding when client-side handling is needed.
When to use it
Inspect submitted values
Read submitted controls through the provided FormData before deciding how to proceed.
Enable client validation
Connect a form element to Conform's client validation lifecycle.
Interview questions
QWhat is the purpose of onSubmit in useForm?
onSubmit is a useForm option that receives the submit event and submission context before the form is submitted. Use it for custom client-side submission behavior, such as preventing the default request and reading formData.
Follow-up: What changes when onValidate is configured? The callback runs only after client validation passes.
QHow do you connect Conform's submission handling to markup?
The returned form object exposes an onSubmit function intended for the form element. Assigning it to the form's onSubmit prop lets Conform coordinate submission handling and client validation.
Follow-up: Why should the handler be attached to the form rather than only a button? Form submission can be triggered by multiple submit mechanisms, so the form-level handler consistently observes them.
QHow can onSubmit be used for custom submission logic?
The callback receives the native event plus an object containing formData. Calling event.preventDefault() stops the browser's default navigation, allowing application code to process the data itself.
Follow-up: How can validation be incorporated? Configure onValidate; onSubmit then runs only when that client validation succeeds.
Related
useFormonValidateform.onSubmitformDatashouldValidateshouldRevalidate