Chapter 17: Submission Handling

Core Idea

form.handleSubmit() triggers validation-then-onSubmit; passing extra context through submission (e.g. "which button was clicked") goes through onSubmitMeta + a per-call metadata argument, keeping onSubmit itself focused purely on already-validated values.

Key Concepts

• onSubmitMeta on useForm declares the default shape/value of metadata; handleSubmit(customMeta) overrides it for that specific call.
• If handleSubmit() is called with no argument, the onSubmitMeta default is used — callers never need to pass metadata just to satisfy the type.
• Schema output transforms don't survive automatically: a Standard Schema (Zod, etc.) can transform data on validation, but TanStack Form doesn't persist that transformed output on its own — re-parse with the schema inside onSubmit to get the transformed value.

Code Examples

const form = useForm({
  defaultValues: { data: '' },
  onSubmitMeta: { submitAction: null },
  onSubmit: async ({ value, meta }) => {
    console.log(`Action: ${meta.submitAction}`, value)
  },
})

<button onClick={() => form.handleSubmit({ submitAction: 'continue' })}>Continue</button>
<button onClick={() => form.handleSubmit({ submitAction: 'backToMenu' })}>Back</button>

• What it demonstrates: two different buttons driving the same onSubmit, disambiguated by meta.submitAction — one validation pipeline, multiple submission intents.

Key Takeaways

1. Use onSubmitMeta + per-call metadata for "which action triggered this submit," instead of maintaining separate onSubmit handlers per button.
2. If you validate with a schema that transforms data (e.g. trims/coerces), remember the transformed value isn't automatically what lands in value inside onSubmit — re-parse there if you need it.
3. form.handleSubmit() always runs validation first; it won't call onSubmit on an invalid form (see onSubmitInvalid, ch019 Focus Management, for handling the failure path).

Connects To

• Ch012 Form Groups: the final group step typically calls this same form.handleSubmit().
• Ch019 Focus Management: onSubmitInvalid, the failure-path counterpart.
• Ch022 SSR & Meta-Frameworks: server-side submission handling built on the same primitives.