This skill builds on react-form-composition-setup. Read it first for adapter-first form structure.
TanStack React Form - Examples Authoring#
Write examples as user journeys, not as thin core behavior tests. Future users consume them as references.
Setup#
import { useForm } from '@tanstack/react-form'
type SignupValues = {
name: string
email: string
}
const emptySignupValues: SignupValues = {
name: '',
email: '',
}
export function SignupExample({
initialValues,
}: {
initialValues?: SignupValues
}) {
const form = useForm({
defaultValues: initialValues ?? emptySignupValues,
onSubmit: async ({ value }) => {
await Promise.resolve(value)
},
})
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}>Create account</button>
)}
</form.Subscribe>
</form>
)
}
Core Patterns#
Combine features when the workflow combines them#
const form = useForm({
defaultValues: profile ?? emptyProfileValues,
errorVisibility: ({ fieldState, state }) =>
fieldState.meta.isBlurred || state.submissionAttempts > 0,
onSubmit: async ({ value }) => {
await saveProfile(value)
},
})
Schema mode, async defaults, submit validation, and visibility can belong in one example when that is the real task.
Use ArrayField at list boundaries#
<form.ArrayField name="items">
{(array) =>
array.value.map((item, index) => (
<form.Field key={item.id} name={`items[${index}].label`}>
{(field) => <input value={field.value} />}
</form.Field>
))
}
</form.ArrayField>
Use Field for item values and ArrayField for the list boundary.
Subscribe buttons and summaries#
<form.Subscribe selector={(state) => [state.canSubmit, state.isSubmitting]}>
{([canSubmit, isSubmitting]) => (
<button disabled={!canSubmit || isSubmitting}>
{isSubmitting ? 'Saving' : 'Save'}
</button>
)}
</form.Subscribe>
Do not read submit state from the stable hook return without a subscription.
Common Mistakes#
HIGH Writing core-test examples#
Wrong:
const form = useForm({
defaultValues: { value: '' },
})
return <form.Field name="value">{() => null}</form.Field>
Correct:
const form = useForm({
defaultValues: profile ?? emptyProfileValues,
onSubmit: async ({ value }) => {
await saveProfile(value)
},
})
Examples should show how a user composes a real form, not just that an API exists.
Source: maintainer interview
HIGH Reading stable form state directly#
Wrong:
const disabled = !form.state.canSubmit || form.state.isSubmitting
return <button disabled={disabled}>Save</button>
Correct:
return (
<form.Subscribe selector={(state) => [state.canSubmit, state.isSubmitting]}>
{([canSubmit, isSubmitting]) => (
<button disabled={!canSubmit || isSubmitting}>Save</button>
)}
</form.Subscribe>
)
Example UI that changes with form state must use form.Subscribe or useSelector.
Source: TanStack/form-v2:examples/react/basic/src/index.tsx
HIGH Letting native reset fight form reset#
Wrong:
<button type="reset">Reset</button>
Correct:
<button
type="reset"
onClick={(event) => {
event.preventDefault()
form.reset()
}}
>
Reset
</button>
Prevent browser-native reset behavior when the example is teaching form reset semantics.
Source: TanStack/form-v2:examples/react/basic/src/index.tsx
MEDIUM Modeling multi-list DnD as one indexed array#
Wrong:
type BoardValues = {
items: Array<{ id: string; list: 'todo' | 'done'; label: string }>
}
Correct:
type BoardValues = {
itemsById: Record<string, { id: string; label: string }>
todoOrder: Array<string>
doneOrder: Array<string>
}
Cross-list movement needs stable item IDs and separate order arrays.
Source: TanStack/form-v2:examples/react/ui-integration-dnd-kit/src/twoLists/index.tsx