Overview TanStack Form is a headless form library with deep TypeScript integration. It provides field-level and form-level validation (sync/async), array fields, linked/dependent fields, fine-grained reactivity, and schema validation adapter support (Zod, Valibot, Yup). Package: @tanstack/react-form Adapters: @tanstack/zod-form-adapter , @tanstack/valibot-form-adapter Status: Stable (v1) Installation npm install @tanstack/react-form

Optional schema adapters:

npm install @tanstack/zod-form-adapter zod npm install @tanstack/valibot-form-adapter valibot Core: useForm import { useForm } from '@tanstack/react-form' function MyForm ( ) { const form = useForm ( { defaultValues : { firstName : '' , lastName : '' , email : '' , age : 0 , } , onSubmit : async ( { value } ) => { // value is fully typed await submitToServer ( value ) } , onSubmitInvalid : ( { value , formApi } ) => { console . log ( 'Validation failed:' , formApi . state . errors ) } , } ) return ( < form onSubmit = { ( e ) => { e . preventDefault ( ) e . stopPropagation ( ) form . handleSubmit ( ) } }

{ / Fields / } < form.Subscribe selector = { ( state ) => ( { canSubmit : state . canSubmit , isSubmitting : state . isSubmitting } ) } children = { ( { canSubmit , isSubmitting } ) => ( < button type = " submit " disabled = { ! canSubmit }

{ isSubmitting ? 'Submitting...' : 'Submit' } </ button

) } /> </ form

) } Fields (form.Field) < form.Field name = " firstName " validators = { { onChange : ( { value } ) => value . length < 3 ? 'Must be at least 3 characters' : undefined , } } children = { ( field ) => ( < div

< label htmlFor = { field . name }

First Name </ label

< input id = { field . name } name = { field . name } value = { field . state . value } onBlur = { field . handleBlur } onChange = { ( e ) => field . handleChange ( e . target . value ) } /> { field . state . meta . isTouched && field . state . meta . errors . length

0 && ( < em

{ field . state . meta . errors . join ( ', ' ) } </ em

) } </ div

) } /> < ! -- Nested fields use dot notation --

< form.Field name = " address.city "

{ ( field ) => ( < input value = { field . state . value } onChange = { ( e ) => field . handleChange ( e . target . value ) } onBlur = { field . handleBlur } /> ) } </ form.Field

Validation Validation Timing Cause When onChange After every value change onBlur When field loses focus onSubmit During submission onMount When field mounts Synchronous Validation < form.Field name = " age " validators = { { onChange : ( { value } ) => { if ( value < 18 ) return 'Must be 18 or older' return undefined // undefined = valid } , onBlur : ( { value } ) => { if ( ! value ) return 'Required' return undefined } , } } /> Asynchronous Validation < form . Field name = "username" asyncDebounceMs = { 500 } validators = { { onChangeAsync : async ( { value } ) => { const res = await fetch ( /api/check-username?q= ${ value } ) const { available } = await res . json ( ) if ( ! available ) return 'Username taken' return undefined } , } }

{ ( field ) => ( <

< input value = { field . state . value } onChange = { ( e ) => field . handleChange ( e . target . value ) } /> { field . state . meta . isValidating && < span

Checking... </ span

} </

) } </ form.Field

Schema Validation (Zod) import { zodValidator } from '@tanstack/zod-form-adapter' import { z } from 'zod' const form = useForm ( { defaultValues : { email : '' , age : 0 } , validatorAdapter : zodValidator ( ) , onSubmit : async ( { value } ) => { / ... / } , } ) < form.Field name = " email " validators = { { onChange : z . string ( ) . email ( 'Invalid email' ) , onBlur : z . string ( ) . min ( 1 , 'Required' ) , } } /> < form.Field name = " age " validators = { { onChange : z . number ( ) . min ( 18 , 'Must be 18+' ) , } } /> Form-Level Validation const form = useForm ( { defaultValues : { password : '' , confirmPassword : '' } , validators : { onChange : ( { value } ) => { if ( value . password !== value . confirmPassword ) { return 'Passwords do not match' } return undefined } , } , } ) Linked/Dependent Fields < form.Field name = " confirmPassword " validators = { { onChangeListenTo : [ 'password' ] , // Re-validate when password changes onChange : ( { value , fieldApi } ) => { const password = fieldApi . form . getFieldValue ( 'password' ) if ( value !== password ) return 'Passwords do not match' return undefined } , } } /> Array Fields < form.Field name = " people " mode = " array "

{ ( field ) => ( < div

{ field . state . value . map ( ( _ , index ) => ( < div key = { index }

< form.Field name = { people[ ${ index } ].name }

{ ( subField ) => ( < input value = { subField . state . value } onChange = { ( e ) => subField . handleChange ( e . target . value ) } /> ) } </ form.Field

< button type = " button " onClick = { ( ) => field . removeValue ( index ) }

Remove </ button

</ div

) ) } < button type = " button " onClick = { ( ) => field . pushValue ( { name : '' , age : 0 } ) }

Add Person </ button

</ div

) } </ form.Field

Array Methods field . pushValue ( item ) // Add to end field . insertValue ( index , item ) // Insert at index field . replaceValue ( index , item ) // Replace at index field . removeValue ( index ) // Remove at index field . swapValues ( indexA , indexB ) // Swap positions field . moveValue ( from , to ) // Move position Listeners (Side Effects) < form.Field name = " country " listeners = { { onChange : ( { value } ) => { // Side effect: reset dependent fields form . setFieldValue ( 'state' , '' ) form . setFieldValue ( 'postalCode' , '' ) } , } } /> Reactivity (form.Subscribe & useStore) // Render-prop subscription (fine-grained) < form.Subscribe selector = { ( state ) => ( { canSubmit : state . canSubmit , isDirty : state . isDirty } ) } children = { ( { canSubmit , isDirty } ) => ( < div

{ isDirty && < span

Unsaved changes </ span

} < button disabled = { ! canSubmit }

Save </ button

</ div

) } /> // Hook-based subscription function FormStatus ( ) { const isValid = form . useStore ( ( s ) => s . isValid ) return isValid ? null : < p

Fix errors </ p

} Form State interface FormState { values : TFormData errors : ValidationError [ ] errorMap : Record < string , ValidationError

isFormValid : boolean isFieldsValid : boolean isValid : boolean // isFormValid && isFieldsValid isTouched : boolean isPristine : boolean isDirty : boolean isSubmitting : boolean isSubmitted : boolean isSubmitSuccessful : boolean submissionAttempts : number canSubmit : boolean // isValid && !isSubmitting } Field State interface FieldState < TData

{ value : TData meta : { isTouched : boolean isDirty : boolean isPristine : boolean isValidating : boolean errors : ValidationError [ ] errorMap : Record < ValidationCause , ValidationError

} } FormApi Methods form . handleSubmit ( ) form . reset ( ) form . getFieldValue ( field ) form . setFieldValue ( field , value ) form . getFieldMeta ( field ) form . setFieldMeta ( field , updater ) form . validateAllFields ( cause ) form . validateField ( field , cause ) form . deleteField ( field ) Shared Form Options (formOptions) import { formOptions } from '@tanstack/react-form' const sharedOpts = formOptions ( { defaultValues : { firstName : '' , lastName : '' } , } ) // Reuse across components const form = useForm ( { ... sharedOpts , onSubmit : async ( { value } ) => { / ... / } , } ) Server-Side Validation // TanStack Start / Next.js server action import { ServerValidateError } from '@tanstack/react-form/nextjs' export async function validateForm ( data : FormData ) { const email = data . get ( 'email' ) as string if ( await checkEmailExists ( email ) ) { throw new ServerValidateError ( { form : 'Submission failed' , fields : { email : 'Email already registered' } , } ) } } TypeScript Integration // Type-safe field paths with DeepKeys interface UserForm { name : string address : { street : string ; city : string } tags : string [ ] contacts : Array < { name : string ; phone : string }

} // TypeScript auto-completes all valid paths: // 'name', 'address', 'address.street', 'address.city', 'tags', 'contacts' < form.Field name = " address.city " /> // OK < form.Field name = " nonexistent " /> // Type Error! Best Practices Always call e.preventDefault() and e.stopPropagation() on form submit Always attach onBlur={field.handleBlur} for blur validation and isTouched tracking Use mode="array" for array fields to get array methods Return undefined (not null/false) for valid validators Use asyncDebounceMs for async validators to prevent API spam Check isTouched before showing errors for better UX Use form.Subscribe with selectors to minimize re-renders Use formOptions for shared configuration across components Use schema validators (Zod/Valibot) for complex validation rules Use onChangeListenTo for cross-field validation dependencies Common Pitfalls Forgetting e.preventDefault() on form submit (causes page reload) Not attaching onBlur to inputs (breaks blur validation and isTouched) Returning null or false instead of undefined for valid fields Using mode="array" incorrectly (only needed on the array field itself, not sub-fields) Subscribing to entire form state instead of using selectors (unnecessary re-renders) Not using asyncDebounceMs with async validators (fires on every keystroke)