This skill builds on react-form-composition-setup. Read it first for React form wiring and subscriptions.
TanStack React Form - Query Backed Forms#
Always choose a default-values plan. Do not pass maybe-undefined query data alone into defaultValues.
Setup#
import { useForm } from '@tanstack/react-form'
type ProfileValues = {
name: string
email: string
}
const emptyProfileValues: ProfileValues = {
name: '',
email: '',
}
async function saveProfile(value: ProfileValues) {
if (value.email.endsWith('@taken.test')) {
return {
kind: 'validation' as const,
fields: {
email: 'Email is already taken',
},
}
}
return { kind: 'ok' as const }
}
export function ProfileForm({ profile }: { profile?: ProfileValues }) {
const form = useForm({
defaultValues: profile ?? emptyProfileValues,
onSubmit: async ({ value, createValidationError }) => {
const result = await saveProfile(value)
if (result.kind === 'validation') {
return createValidationError({
fields: result.fields,
})
}
},
})
return (
<form
onSubmit={(event) => {
event.preventDefault()
event.stopPropagation()
void form.handleSubmit()
}}
>
<form.Field name="email">
{(field) => (
<input
value={field.value}
onBlur={field.handleBlur}
onChange={(event) => field.handleChange(event.target.value)}
/>
)}
</form.Field>
<form.Subscribe selector={(state) => state.isSubmitting}>
{(isSubmitting) => <button disabled={isSubmitting}>Save</button>}
</form.Subscribe>
</form>
)
}
Core Integration Patterns#
Gate fields until data is ready#
export function GatedProfileForm({
profile,
isLoading,
}: {
profile?: ProfileValues
isLoading: boolean
}) {
if (isLoading || profile === undefined) {
return <p>Loading profile</p>
}
return <ProfileForm profile={profile} />
}
Gating means mounted fields start with the loaded data, but the visual loading language is different.
Render immediately with an empty fallback#
const form = useForm({
defaultValues: profile ?? emptyProfileValues,
onSubmit: async ({ value }) => {
await saveProfile(value)
},
})
The fallback object must be static and shape-complete.
Let transient failures stay transient#
onSubmit: async ({ value, createValidationError }) => {
const result = await saveProfile(value)
if (result.kind === 'validation') {
return createValidationError({ fields: result.fields })
}
}
Only catch or convert validation-shaped responses. Retryable network failures can reject so the query or framework layer keeps the transient error.
Common Mistakes#
HIGH Passing maybe-undefined data as defaults#
Wrong:
const form = useForm({
defaultValues: profile,
})
Correct:
const form = useForm({
defaultValues: profile ?? emptyProfileValues,
})
Initial query data is often undefined; the form needs either gated mounting or a shape-complete fallback.
Source: maintainer interview
HIGH Starting async submit without returning it#
Wrong:
onSubmit: ({ value }) => {
saveProfile(value)
}
Correct:
onSubmit: async ({ value }) => {
await saveProfile(value)
}
Return or await the endpoint promise so isSubmitting covers the request.
Source: TanStack/form-v2:packages/form-core/tests/FormApi/submission-handling.spec.ts
HIGH Storing transient failures as validation#
Wrong:
onSubmit: async ({ createValidationError }) => {
return createValidationError('The server is offline')
}
Correct:
onSubmit: async ({ value }) => {
await saveProfile(value)
}
Validation errors block submission. Keep transient query, network, and framework failures in the query/framework layer.
Source: maintainer interview
HIGH Throwing validation errors#
Wrong:
onSubmit: async () => {
throw new Error('Email is already taken')
}
Correct:
onSubmit: async ({ createValidationError }) => {
return createValidationError({
fields: {
email: 'Email is already taken',
},
})
}
Validation failures are returned values; thrown or rejected errors are submit failures.
Source: TanStack/form-v2:packages/form-core/src/FormApi/FormApi.public.ts
MEDIUM Ignoring the loading UI tradeoff#
Wrong:
return <ProfileForm profile={profile} />
Correct:
if (profile === undefined) {
return <p>Loading profile</p>
}
return <ProfileForm profile={profile} />
If you gate mounting, the UI must represent that fields do not exist until data is ready.
Source: maintainer interview