This skill builds on choosing-form-options-modes. Read it first to pick default, strict schema, or loose schema mode.
TanStack React Form - Schema Driven Forms#
Put Standard Schema-compatible schemas in validators. Read parsed schema output from validatorOutputs; keep raw value as editable form state.
Setup#
import { formOptions, useForm } from '@tanstack/react-form'
import { z } from 'zod'
const profileSchema = z.object({
name: z.string().min(1, 'Name is required'),
email: z.email('Email is invalid'),
})
const profileOptions = formOptions.strictSchema({
defaultValues: {
name: '',
email: '',
},
validators: [{ run: profileSchema, triggers: ['blur'] }],
onSubmit: ({ validatorOutputs }) => {
const parsedProfile = validatorOutputs[0]
console.log(parsedProfile.email)
},
})
export function ProfileForm() {
const form = useForm(profileOptions)
return (
<form.Field name="email">
{(field) => (
<label>
<input
value={field.value}
onBlur={field.handleBlur}
onChange={(event) => field.handleChange(event.target.value)}
/>
<small>{field.errors.map((error) => error.message).join('\n')}</small>
</label>
)}
</form.Field>
)
}
Hooks And Components#
Return server validation values from onSubmit#
const form = useForm({
defaultValues: {
email: '',
},
onSubmit: async ({ value, createValidationError }) => {
const result = await saveEmail(value.email)
if (result.kind === 'validation') {
return createValidationError({
fields: {
email: result.message,
},
})
}
},
})
async function saveEmail(email: string) {
return email.endsWith('@taken.test')
? { kind: 'validation' as const, message: 'Email is already taken' }
: { kind: 'ok' as const }
}
Validation errors are returned values. Throw only transient failures.
Convert Standard Schema issues from submit#
onSubmit: ({ value, parseIssues }) => {
const result = profileSchema.safeParse(value)
if (!result.success) {
return parseIssues(result.error.issues)
}
}
Use parseIssues when an endpoint or local schema check returns Standard Schema-shaped issues.
Exclude a schema from submit output#
const validateWhileEditing = {
run: profileSchema,
triggers: ['change'],
skipOnSubmit: true,
}
skipOnSubmit: true means that validator does not contribute a parsed submit output.
Common Mistakes#
HIGH Expecting schema output to replace value#
Wrong:
onSubmit: ({ value }) => {
console.log(value.nameLength)
}
Correct:
onSubmit: ({ validatorOutputs }) => {
const parsed = validatorOutputs[0]
console.log(parsed.nameLength)
}
Schema output is stored separately so form state can remain editable.
Source: TanStack/form-v2:packages/form-core/tests/validation.test.ts
HIGH Throwing validation errors#
Wrong:
onSubmit: () => {
throw new Error('Email is already taken')
}
Correct:
onSubmit: ({ createValidationError }) => {
return createValidationError({
fields: {
email: 'Email is already taken',
},
})
}
Thrown errors are submit failures; validation errors must be returned values.
Source: TanStack/form-v2:packages/form-core/tests/FormApi/submission-handling.spec.ts
HIGH Returning raw schema errors#
Wrong:
onSubmit: ({ value }) => {
const result = profileSchema.safeParse(value)
return result.success ? null : result.error
}
Correct:
onSubmit: ({ value, parseIssues }) => {
const result = profileSchema.safeParse(value)
return result.success ? null : parseIssues(result.error.issues)
}
parseIssues maps Standard Schema issue paths into form and field validation state.
Source: TanStack/form-v2:packages/form-core/src/FormApi/FormApi.public.ts
MEDIUM Mapping paths by hand#
Wrong:
return createValidationError({
fields: {
users: 'Second user email is invalid',
},
})
Correct:
return parseIssues([
{
message: 'Email is invalid',
path: ['users', 1, 'email'],
},
])
Let Standard Schema issue paths route nested and array errors when possible.
Source: TanStack/form-v2:packages/form-core/src/standardSchema.public.ts
MEDIUM Inferring UI metadata from Standard Schema#
Wrong:
const required = Boolean(profileSchema.shape.email)
Correct:
const emailLabel = 'Email address'
const emailRequired = true
Standard Schema standardizes validation, not UI metadata such as required labels.
Source: maintainer interview