TanStack Form V2 Skill Spec#
Status: reviewed, Phase 5 finalized.
This reviewed artifact follows the pnpm intent:scaffold domain-discovery workflow. It is intentionally adapter-first: user-facing guidance starts from @tanstack/react-form, with @tanstack/form-core used as the source of concepts and behavior rather than as a workflow entrypoint.
Scope#
In scope:
- React form composition with
useForm,form.Field,form.ArrayField,form.Subscribe, app-form helpers, and field groups. - Standard Schema-compatible schema usage.
- Choosing between default form options,
strictSchema, andlooseSchema. - Query-like async defaults and mutation-like submit handling.
- Error visibility callback workflows.
- Split-form helper types and reusable validation or visibility policy modules.
- Type error diagnosis for schema/form composition.
- Authoring richer React examples.
Out of scope for this pass:
- Devtools as an entrypoint.
- Migration guidance.
- Schema metadata extraction, such as automatically deriving required labels.
- TanStack Form owning transient or non-validation error state.
- Teaching UI-library behavior as part of TanStack Form itself.
- Solid-first coverage.
Hard Do Nots#
- Do not type assert to make TanStack Form code compile. The library is built around inference, and assertions are usually a sign that the code is fighting the API.
- Do not write field names like
name={`users[${index}].name` as const};nameis inferred without the assertion. - Do not annotate render-prop children as
any; field children already receive inferred field APIs. - Do not shim field prop types by hand, such as
{ value: string }; use inferred render-prop types,FieldWithValue<T>, orAnyFieldApiwhen a reusable component needs an explicit field prop type. - Do not treat validation errors and transient errors as the same thing. Errors stored from validators or
onSubmitblock the user from submitting. - Do not store query/network/framework transient failures as form validation errors. Most query libraries already own transient error state; use that state instead.
- Do not throw validation errors from validators or
onSubmit; validation errors must be returned values, such ascreateValidationErrororparseIssues. - Do not type a shared section as
form: FormA | FormBwhere each form is a differentReactFormType; TypeScript cannot make sense of that union. Use field groups for shared sections that need to work across different forms.
Proposed Skills#
1. React Form Composition Setup#
Purpose: Help users build adapter-first React forms, reusable field components, app-form setups, field groups, arrays, and UI-library bindings.
Primary APIs:
useFormReactFormTypeFieldWithValueAnyFieldApiformOptionscreateFormHookform.Fieldform.ArrayFieldform.Subscribeform.FormGroupwithFields
Core guidance:
- Start from
@tanstack/react-form, not@tanstack/form-core. - Use render-prop field APIs and subscriptions for state reads.
- Treat
useFormanduseAppFormas stable form creation hooks, not reactive state reads by themselves. - Use
useSelectororform.Subscribewhen component output must update in response to form state. - Use app-form helpers when an application wants reusable field and form components.
- Keep shared form options submit-agnostic when child components need to accept forms with different
onSubmithandlers. - Use
ReactFormType<typeof sharedFormOptions>as one option for splitting a known form into child sections that receive the form as a prop. - Do not use unions like
ReactFormType<typeof formAOptions> | ReactFormType<typeof formBOptions>for shared sections; use field groups when one section should bind into multiple different forms. - Use AppForm to reduce repeated field JSX boilerplate. Use split form sections to reduce component nesting. Use field groups for reusable sections that bind to different form paths or different forms.
- Let field
nameprops and render-prop children infer their types; useFieldWithValue<T>orAnyFieldApifor explicit reusable field component props. form.Fieldmay bind to an array value. It treats that array immutably like any other field value, so changing one element changes the fieldvalueand rerenders consumers of the whole array field.- Use
form.ArrayFieldwhen the array is a rendering boundary for child fields or list items, and those child fields are the reactive units the example cares about. - Use array helpers for array mutations and reorders.
Important failure modes:
- Adding
as const,as any, render-propfield: any, or other assertions to force form code to compile. - Shimming field prop types by hand instead of using inferred field types,
FieldWithValue<T>, orAnyFieldApi. - Reading from the stable
useFormoruseAppFormreturn and expecting the component to re-render as form state changes. - Importing core directly in examples or application code.
- Rendering app field components outside their required app-form or field context.
- Making a reusable child form prop too specific by baking in an
onSubmittype. - Splitting a form by hand-writing a large form prop type instead of deriving it from shared options with
ReactFormType. - Typing a shared section as a union of multiple
ReactFormTypeforms instead of using field groups. - Using
form.Fieldto render a list of child fields, then being surprised that item changes rerender the whole array-value consumer. - Treating
form.ArrayFieldas required for every array-typed value, instead of using it when the array will render child fields or list items. - Mutating arrays manually and desynchronizing values from field meta.
Source trail:
packages/react-form/src/ReactForm/Components.public.tspackages/react-form/src/ReactForm/ReactFormApi.lib.tsxpackages/react-form/src/Subscribe.public.tsxpackages/react-form/src/ReactForm/fieldSubscriptions.lib.tspackages/react-form/src/AppForm/createFormHook.public.tspackages/react-form/src/AppForm/contexts.lib.tsdocs/reference/type-aliases/FieldWithValue.mddocs/reference/type-aliases/AnyFieldApi.mddocs/framework/react/reference/type-aliases/ReactFormType.mdpackages/react-form/tests/submit-return.test-d.tsxpackages/form-core/src/FormApi/array-methods.lib.tspackages/form-core/src/FormApi/FormApiArrayMethods.types.public.tspackages/form-core/src/FieldApi/fieldState.lib.tsexamples/react/array/src/index.tsxexamples/react/basic-splitting-form/src/index.tsxexamples/react/basic-splitting-form/src/FormSection.tsxexamples/react/basic-splitting-form/src/StringField.tsxexamples/react/basic-splitting-form/src/FieldError.tsxexamples/react/ui-integration-shadcn/src/components/form/app-form.ts
Cross-Cutting: Reusable Form Policies#
Purpose: Help agents recognize when form behavior should be extracted into a named reusable helper rather than repeated inline.
Primary APIs:
ReactFormTypecreateErrorVisibilitycreateValidatorcreateValidators- shared
formOptions/appFormOptions
Core guidance:
- Use
ReactFormType<typeof sharedFormOptions>as the helper type for split form sections that receive aformprop. - Treat
ReactFormTypesplitting as one composition option, not a general replacement for AppForm or field groups. - AppForm reduces repeated field JSX boilerplate; split sections reduce nesting in a known form; field groups cover shared sections across different forms or field paths.
- Prefer form-level
errorVisibilitycallbacks over scattered local patterns likeconst showErrors = field.meta.isTouched && field.meta.isInvalid. - Use helper functions mainly when a callback or validator config deserves a semantic name that preserves intent.
- Extract validator configs with
createValidatororcreateValidatorswhen trigger timing, debounce,bailIfInvalid, orrunOnSubmitpolicy is complex enough to name. - Use comments or JSDoc on named helpers to explain behavior intent, such as why errors wait for blur or submit, or why a validator uses a
rewardEarlyPunishLatepolicy. - Keep reusable policies value-agnostic unless they are intentionally tied to a specific form shape; inline callbacks are better when typed values are required.
Important failure modes:
- A split form loses field-name inference because the child prop type was hand-written.
- A shared section accepts
FormA | FormBand TypeScript cannot narrow field names or form methods enough to make the section usable. - Error display behavior is scattered through local
showErrorsvariables instead of being controlled by form-levelerrorVisibility. - A complex visibility workflow is duplicated inline and later examples preserve code shape but lose the user-workflow reason.
- Validator trigger settings are copied without explanation, so agents cannot tell whether
blur,change, debounce, orbailIfInvalidis intentional. - A reusable visibility function tries to read a concrete
state.values.nameeven though reusable visibility callbacks are form-agnostic.
Source trail:
examples/react/basic-splitting-form/src/FormSection.tsxexamples/react/basic-splitting-form/src/sharedForm.tspackages/react-form/tests/submit-return.test-d.tsxpackages/form-core/tests/validation.test.tspackages/form-core/tests/validation.test-d.tsexamples/react/ui-integration-shadcn/src/app/booking/shared-form.tsx
2. Choosing Form Options Modes#
Purpose: Help users decide between default formOptions, strictSchema, and looseSchema.
Primary APIs:
formOptionsformOptions.strictSchemaformOptions.looseSchemaappFormOptionsappFormOptions.strictSchemaappFormOptions.looseSchema
Core guidance:
- Treat the option helpers as runtime identity helpers with type-level meaning.
- Use default
formOptionswhen the form should be inferred fromdefaultValues; the default values are taken at face value and that type flows into validators and callbacks. - Default
formOptionsis especially useful for callback-based validation because callbackvalueis already typed from the form defaults. - Use
strictSchemawhen the schema is the source of typing and acts as a transforming pipeline from input type to output type. - In
strictSchema,defaultValuesshould type-check against the schema input type. If they do not align, the defaults should produce type errors. - Use
looseSchemawhen the schema is a ruleset for confirming valid output, but editable defaults need nullable or undefined values, such as a date field that starts asnull. - In
looseSchema, default values must still align with the schema shape, but properties may also benullorundefinedwhere editing requires it. - In both schema modes, callbacks may not have useful inference unless there is a schema in the validator array for the helper to infer from.
- In both schema modes,
onSubmitshould read the parsed transform output fromschemaOutputsrather than rawvalue. - Treat pipeline-vs-ruleset as TanStack Form guidance, not a Standard Schema concept. Standard Schema only gives the shared validation/typing interface.
- Explain the mental model as: is this schema a pipeline of constraints/transforms, or a firewall that only lets valid values through?
- List current Standard Schema-capable libraries as examples with a general leaning, not as hard categories.
- Zod generally leans ruleset/firewall for form work, while explicit transforms/codecs can still make a Zod schema pipeline-like.
- Valibot generally leans pipeline because its docs center
pipeand validation/transformation actions. - ArkType is mixed: structural constraints often read like a firewall, while morphs/pipes can make it pipeline-like.
- Effect Schema often leans pipeline/codec when used as an encoded-to-decoded boundary.
Important failure modes:
- Expecting
strictSchemaorlooseSchemato add runtime validation by itself. - Using default
formOptionswhile expecting the schema to be the source of the form type. - Using strict schema mode for a form whose editable UI states cannot satisfy the schema type.
- Using
looseSchemabut providing default values that no longer match the schema shape at all. - Using schema modes without putting a schema in the validator array, then expecting callbacks to infer from that schema.
- Using loose schema mode for a true pipeline and then reading raw
valueas if it were parsed output. - Reading
valueinonSubmitfor schema-mode forms instead of reading the correspondingschemaOutputsentry. - Treating all Zod
inputandoutputdifferences as a real pipeline decision.
Source trail:
packages/form-core/src/utils.public.tspackages/react-form/src/AppForm/appFormOptions.public.tspackages/form-core/tests/validation.test.tspackages/form-core/tests/validation.test-d.tsexamples/react/ui-integration-shadcn/src/app/booking/schema.tsexamples/react/ui-integration-shadcn/src/app/booking/shared-form.tsxhttps://standardschema.dev/https://zod.dev/library-authorshttps://valibot.dev/guides/integrate-valibot/https://arktype.io/docs/integrationshttps://effect.website/docs/schema/standard-schema/
3. Schema Driven Forms#
Purpose: Help users take a Standard Schema-compatible schema and wire it into validation, field errors, submit output, and type inference.
Primary APIs:
validatorsschemaOutputsparseIssuescreateValidationError
Core guidance:
- Configure schema validation through validators.
- Extract reusable validator trigger configs with
createValidatororcreateValidatorswhen the behavior is complex enough to need a semantic name. - Read parsed schema output from
schemaOutputs; rawvalueremains form state. - Route submit validation errors as returned values through
createValidationErrororparseIssues; do not throw them. - Let Standard Schema issue paths route nested and array field errors when possible.
- Keep UI metadata explicit or schema-library-specific; Standard Schema does not standardize it.
Important failure modes:
- Expecting schema output to replace form
value. - Returning or throwing raw schema errors from submit code and expecting field errors.
- Throwing validation errors instead of returning
createValidationErrororparseIssuesvalues. - Manually mapping nested issue paths incorrectly.
- Duplicating validator trigger, debounce, submit, or bail policy inline without documenting why that behavior exists.
- Trying to build general UI metadata extraction from Standard Schema.
Source trail:
packages/form-core/src/standardSchema.public.tspackages/form-core/src/standardSchema.lib.tspackages/form-core/src/FormApi/FormApi.public.tspackages/form-core/tests/validation.test.tspackages/form-core/tests/FormApi/submission-handling.spec.tsexamples/react/field-groups/src/index.tsx
4. Query Backed Forms#
Purpose: Help users combine form state with query-like async defaults and mutation-like submit calls.
Primary APIs:
useForm({ defaultValues })onSubmitform.resetcreateValidationErrorparseIssues
Core guidance:
- Do not feed maybe-undefined query data into the form by itself; choose an explicit default-values plan.
- Approach 1: do not mount the fields until the query is finished. The whole form can also be gated so the first mounted form state is populated with correct data.
- Approach 2: define a static shape-complete
emptyFormValuesobject and pass defaults asquery.data ?? emptyFormValues. - Neither approach is preferred globally; choose based on the desired loading and visual UI language.
- Gating fields changes the UI because fields or the whole form appear only after data is ready. The fallback approach can render the form immediately, often with loading or placeholder state around it.
- Update defaults when async data arrives and rely on touched-field preservation for user edits.
- Separate transient errors from validation errors.
- Use an async promise for the endpoint call inside
onSubmitsoisSubmittingreflects the request. - Catch submit failures only when the endpoint can return validation errors that should be converted into returned
createValidationErrororparseIssuesvalues. - Transient submit failures may throw or reject; the form will set
isSubmitSuccessfulto false, and query/framework state should preserve the transient error details. - Leave transient query, network, and framework failures in the query/framework error state instead of converting them into form validation errors.
- Use reset options deliberately when replacing both values and default baselines.
Important failure modes:
- Treating initial
undefinedquery data as a final form shape. - Passing
query.datadirectly as defaults without either gated mounting or anemptyFormValuesfallback. - Gating fields without accounting for the different loading UI, or rendering fallback values without communicating that query data is still loading.
- Overwriting touched user edits when async defaults arrive.
- Starting an endpoint call inside
onSubmitwithout returning or awaiting its promise, soisSubmittingdoes not cover the request. - Turning transient network or server failures into validation errors and accidentally blocking future submits.
- Throwing validation errors from
onSubmitinstead of returning validation values. - Treating a rejected transient
onSubmitas something that should produce visible field errors.
Source trail:
packages/react-form/tests/useForm.spec.tsxpackages/form-core/src/FormApi/FormApi.lib.tspackages/form-core/src/FormApi/FormApi.public.tspackages/form-core/tests/FormApi/default-value.spec.tspackages/form-core/tests/FormApi/submission-handling.spec.ts
Open evidence gap: the IDE referenced examples/react/tanstack-query/src/App.tsx, but this checkout did not contain examples/react/tanstack-query.
5. Error Visibility Workflows#
Purpose: Help users implement policies such as "show after blur", "show after submit", or "show after blur or submit".
Primary APIs:
errorVisibilitycreateErrorVisibilitycreateValidatorcreateValidatorsfieldState.metastate.submissionAttemptsform.FormGroup
Core guidance:
errorVisibilityis callback-based.- Use form-level
errorVisibilityto control default visible-error behavior instead of scattering local checks likefield.meta.isTouched && field.meta.isInvalid. - Reusable visibility policies created with
createErrorVisibilityshould be value-agnostic. - Use
createErrorVisibility,createValidator, andcreateValidatorsmainly when a policy benefits from a semantic name or intent-focused comments/JSDoc. - Inline callbacks can use the consuming form's typed values.
- Visibility callbacks receive pre-filter field meta, not visible errors or validity.
- Grouped forms scope submission attempts to the nearest group.
Important failure modes:
- Writing string presets such as
errorVisibility: 'touched'. - Repeating local
showErrorsexpressions across fields instead of setting the form's default error visibility behavior. - Inspecting
fieldState.meta.errorsor validity inside the visibility callback. - Expecting reusable
createErrorVisibilitycallbacks to know a concrete form value shape. - Copying complex visibility or validator policy inline without documenting the workflow intent.
- Forgetting group-scoped submission attempts in wizard or section-level flows.
Source trail:
packages/form-core/src/validation.public.tspackages/form-core/src/FieldApi/fieldState.lib.tspackages/form-core/tests/validation.test-d.tspackages/form-core/tests/FormApi/validation.spec.tspackages/form-core/tests/FormGroupApi/FormGroupApi.spec.tsexamples/react/ui-integration-shadcn/src/app/booking/shared-form.tsx
6. Type Error Debugging#
Purpose: Help users interpret large TypeScript errors from schemas, option modes, field groups, reusable forms, and adapter APIs.
Primary APIs and concepts:
ReactFormTypeformOptionsappFormOptionscreateErrorVisibilitycreateValidators- schema
strictSchema/looseSchema - field component
strict/loose - field group
strict/loose DeepKeysDeepValue- public
atomAPIs
Core guidance:
- Do not use type assertions to silence TanStack Form type errors; preserve inference and fix the mismatched boundary.
- Classify the error by boundary: schema option mode, schema output, submit return, reusable child form props, error visibility state, validator helper arity, form group scope, field group virtual path/binding, field component brand, deep-key path, or public/private API mismatch.
- Treat a
ReactFormTypeunion in a shared section as a design issue, not a TypeScript problem to assert through; reach for field groups instead. - Do not confuse schema strict/loose with field component or field group strict/loose.
- For long errors, find the first concrete path, value, validator, or submit-return mismatch and ignore the expanded generic machinery around it.
- Reusable
createErrorVisibilitycallbacks are form-agnostic; if a type error mentionsunknownvalues, use an inline callback for form-specific values. createValidatorstype errors often mean the number of run functions does not match the number of option configs.- FormGroup type errors often mean the code used a root-form path/value where the group expects group-scoped paths/values.
- Field-group type errors often mean the code used real form paths where virtual paths are expected, passed an incomplete binding map, or chose
strictwhen the real path is only loosely compatible. - Deep-key path errors usually point to path shape: arrays use bracket segments such as
users[${number}].name, and array helpers only accept paths whose value includes an array. - Look for the first meaningful generic mismatch rather than the full expanded error wall.
- Prefer source-backed explanation over broad TypeScript folklore.
Important failure modes:
- Adding assertions like
as const,as any, or(field: any)instead of letting form names and children infer. - Hand-writing shim field prop types instead of using inferred props,
FieldWithValue<T>, orAnyFieldApi. - Typing a shared section as
ReactFormType<typeof formAOptions> | ReactFormType<typeof formBOptions>. - Expecting a reusable
createErrorVisibilitycallback to read concrete form values. - Calling
createValidatorswith fewer or more run functions than option configs. - Using root-form field names or values inside a
FormGroupvalidator or grouped field. - Passing real form paths into a field group API where virtual paths are required.
- Providing an incomplete
withFieldsbinding map, passing the internal defined-fields object as a binding, or omitting the requiredformprop. - Reading
form.storeorfield.storeinstead of publicatomAPIs. - Treating
fieldComponent.strict/looseas schema mode selection. - Passing a submit-specific form type to a reusable child that should accept several submit handlers.
- Binding a strict field group slot to a field path whose value is only loosely compatible.
Source trail:
packages/form-core/tests/validation.test-d.tspackages/form-core/tests/deep-keys.test-d.tspackages/react-form/tests/submit-return.test-d.tsxpackages/react-form/tests/FormGroup.test-d.tsxpackages/react-form/tests/FieldGroupApi.test-d.tsxpackages/react-form/src/AppForm/getFormHookHelpers.public.tspackages/react-form/src/FieldGroup/withFields.public.ts
7. Examples Authoring#
Purpose: Help Codex scaffold substantial maintainer examples for testing, future documentation, and user reference.
Primary example areas:
- Basic form and submit handling.
- Schema-driven form.
- Query-backed form.
- Error visibility workflow.
- App-form and UI-library integration.
- Field groups.
- Arrays and reorder behavior.
Core guidance:
- Examples are scaffolding targets for maintainers in this private repository, and future users experience them as reference examples.
- Examples should be adapter-first and user-journey-shaped.
- Combine features when real workflows combine them, such as schema mode plus async defaults plus submit validation plus visibility policy.
- Keep boundaries explicit: TanStack Form handles validation and form state; query/framework code owns transient errors; UI libraries own visual behavior.
- Show reactive state reads with
useSelectororform.Subscribe; do not imply the stable hook return is itself reactive. - Prefer realistic examples over minimal API proofs once behavior has test coverage.
Important failure modes:
- Writing barren examples that resemble core tests more than user workflows.
- Modeling complex DnD multi-list state as a single indexed array and creating UI races.
- Letting native reset behavior fight form reset semantics.
- Reading form state from the stable hook return without a selector or subscription, then wondering why UI does not update.
- Reading submit state outside
form.Subscribeand missing updates.
Source trail:
examples/react/basic/src/index.tsxexamples/react/array/src/index.tsxexamples/react/basic-splitting-form/src/index.tsxexamples/react/field-groups/src/index.tsxexamples/react/ui-integration-shadcn/src/app/booking/shared-form.tsxexamples/react/ui-integration-shadcn/src/app/booking/booking-form.tsxexamples/react/ui-integration-dnd-kit/src/singleList/index.tsxexamples/react/ui-integration-dnd-kit/src/twoLists/index.tsx
Cross-Skill Relationships#
- React Form Composition Setup is the base skill for all example work.
- Reusable Form Policies sits between React Form Composition Setup, Error Visibility Workflows, and Type Error Debugging.
- Choosing Form Options Modes feeds Schema Driven Forms and Type Error Debugging.
- Schema Driven Forms feeds Query Backed Forms when submit returns server-side validation.
- Error Visibility Workflows is often layered on top of Schema Driven Forms and Query Backed Forms.
- Examples Authoring should compose the other skills into realistic maintainer scaffolds that can later serve as references.
Cross-Skill Tensions#
- Schema strictness vs editable defaults: strict schema typing helps submit output, but editable forms often need nullable or undefined intermediate values.
- Query loading UI vs form initialization: gated mounting gives correct first form state, while
emptyFormValueslets the UI render immediately. - Validation state vs transient state: validation errors block submit, while query/network/framework failures should remain outside form validation state.
- Reuse vs inference boundaries: reusable sections are valuable, but assertions, hand-written field props, or
ReactFormTypeunions break the intended inference model.
Remaining Gaps#
- Query Backed Forms: the IDE referenced
examples/react/tanstack-query/src/App.tsx, but this checkout did not containexamples/react/tanstack-query. Query-backed guidance is reviewed from tests and maintainer interview, and should be exercised by scaffolding a realistic example later.
Phase 5 Finalization#
Resolved in the detail interview:
- Hard do-nots, especially no type assertions and no transient errors as validation errors.
- Schema mode wording for default
formOptions,strictSchema, andlooseSchema. - Query-backed default-value strategies and their visual loading language.
- Async
onSubmitbehavior, includingisSubmitting,isSubmitSuccessful, returned validation values, and thrown transient failures. - Reusable policy helpers as semantic names for complex callbacks/configs.
- AppForm,
ReactFormTypesplit sections, and field groups as separate composition tools. - Field vs
ArrayField, especially array-as-immutable-value versus array-as-child-field-rendering-boundary. - Type-error debugging categories derived from the type tests.
- Examples authoring as maintainer scaffolding for testing and future reference examples.
- Standard Schema libraries as heuristic examples, with pipeline-vs-firewall/ruleset clearly marked as TanStack Form guidance rather than a Standard Schema concept.
Reviewed acceptance criteria:
- Skills never make
@tanstack/form-corethe user-facing workflow entrypoint. - Skills explain schemas through adapter APIs while preserving core semantics.
- Skills distinguish validation errors from transient async failures.
- Skills do not promise schema metadata extraction.
- Skills do not use devtools or migration as current entrypoints.
- Examples guidance is realistic enough for agents to build non-barren examples.