Skip to content
Source
Sign inSign up
TanStack/form
Open History to see the last commit

SKILL.md

322 lines7.7 KB

TanStack React Form - Composition Setup

Start from @tanstack/react-form. Treat @tanstack/form-core as the behavior source, not the application entrypoint.

Setup

import { useForm } from '@tanstack/react-form'

export function PersonForm() {
  const form = useForm({
    defaultValues: {
      firstName: '',
      lastName: '',
      tags: [''],
    },
    onSubmit: ({ value }) => {
      console.log(value)
    },
  })

  return (
    <form
      onSubmit={(event) => {
        event.preventDefault()
        event.stopPropagation()
        void form.handleSubmit()
      }}
    >
      <form.Field name="firstName">
        {(field) => (
          <input
            name={field.name}
            value={field.value}
            onBlur={field.handleBlur}
            onChange={(event) => field.handleChange(event.target.value)}
          />
        )}
      </form.Field>

      <form.Subscribe
        selector={(state) => [state.canSubmit, state.isSubmitting]}
      >
        {([canSubmit, isSubmitting]) => (
          <button type="submit" disabled={!canSubmit || isSubmitting}>
            {isSubmitting ? 'Saving' : 'Save'}
          </button>
        )}
      </form.Subscribe>
    </form>
  )
}

Hooks And Components

Read form state reactively

<form.Subscribe selector={(state) => state.values.firstName}>
  {(firstName) => <output>{firstName}</output>}
</form.Subscribe>

useForm and useAppForm return stable form APIs. Use form.Subscribe or useSelector for UI that must update with state.

Split one known form with ReactFormType

import { formOptions, type ReactFormType } from '@tanstack/react-form'

export const sharedPersonOptions = formOptions({
  defaultValues: {
    firstName: '',
    lastName: '',
  },
})

type PersonFormApi = ReactFormType<typeof sharedPersonOptions>

export function NameSection({ form }: { form: PersonFormApi }) {
  return (
    <form.Field name="firstName">
      {(field) => (
        <input
          value={field.value}
          onBlur={field.handleBlur}
          onChange={(event) => field.handleChange(event.target.value)}
        />
      )}
    </form.Field>
  )
}

Use this when a child section belongs to one known form. Use field groups when the same section must bind into multiple different forms or paths.

Render arrays with ArrayField when child fields matter

<form.ArrayField name="tags">
  {(array) => (
    <ul>
      {array.value.map((_, index) => (
        <form.Field key={index} name={`tags[${index}]`}>
          {(field) => (
            <input
              value={field.value}
              onBlur={field.handleBlur}
              onChange={(event) => field.handleChange(event.target.value)}
            />
          )}
        </form.Field>
      ))}
    </ul>
  )}
</form.ArrayField>

form.Field can bind an array value, but it treats the array as one immutable value. Use form.ArrayField when the list renders child fields.

Reuse sections across forms with field groups

import { defineFieldGroup } from '@tanstack/react-form'

const dateRangeFieldGroup = defineFieldGroup(({ strict }) => ({
  start: strict<string>(),
  end: strict<string>(),
}))

function DateRangeImpl({
  fields,
}: {
  fields: typeof dateRangeFieldGroup.fields
}) {
  return (
    <>
      <fields.Field name="start">
        {(field) => <input value={field.value} />}
      </fields.Field>
      <fields.Field name="end">
        {(field) => <input value={field.value} />}
      </fields.Field>
    </>
  )
}

export const DateRange = dateRangeFieldGroup.bindComponent(
  DateRangeImpl,
  'fields',
)

Inside a field group, use virtual names such as start; callers bind those names to real paths.

Common Mistakes

HIGH Expecting useForm to be reactive

Wrong:

const form = useForm({ defaultValues: { name: '' } })
const canSubmit = form.state.canSubmit

return <button disabled={!canSubmit}>Save</button>

Correct:

const form = useForm({ defaultValues: { name: '' } })

return (
  <form.Subscribe selector={(state) => state.canSubmit}>
    {(canSubmit) => <button disabled={!canSubmit}>Save</button>}
  </form.Subscribe>
)

The hook result is stable; selectors and subscriptions are the reactive boundary.

Source: TanStack/form-v2:packages/react-form/src/ReactForm/ReactFormApi.lib.tsx

HIGH Asserting field names or children

Wrong:

<form.Field name={`users[${index}].name` as const}>
  {(field: any) => <input value={field.value} />}
</form.Field>

Correct:

<form.Field name={`users[${index}].name`}>
  {(field) => <input value={field.value} />}
</form.Field>

Field names and render-prop children are inferred; assertions usually hide the wrong boundary.

Source: maintainer interview, TanStack/form-v2:packages/react-form/src/ReactForm/Components.public.ts

HIGH Treating ArrayField as every array value

Wrong:

<form.ArrayField name="selectedIds">
  {(field) => <pre>{JSON.stringify(field.value)}</pre>}
</form.ArrayField>

Correct:

<form.Field name="selectedIds">
  {(field) => <pre>{JSON.stringify(field.value)}</pre>}
</form.Field>

Use ArrayField when rendering child fields from an array; a whole array value can be a normal Field.

Source: TanStack/form-v2:packages/react-form/src/ReactForm/fieldSubscriptions.lib.ts

HIGH Rendering list fields through Field

Wrong:

<form.Field name="items">
  {(field) =>
    field.value.map((_, index) => (
      <form.Field key={index} name={`items[${index}]`}>
        {(itemField) => <input value={itemField.value} />}
      </form.Field>
    ))
  }
</form.Field>

Correct:

<form.ArrayField name="items">
  {(array) =>
    array.value.map((_, index) => (
      <form.Field key={index} name={`items[${index}]`}>
        {(itemField) => <input value={itemField.value} />}
      </form.Field>
    ))
  }
</form.ArrayField>

The Field subscriber follows the whole array value; ArrayField follows array length and array version for list rendering.

Source: TanStack/form-v2:examples/react/array/src/index.tsx

HIGH Unioning ReactFormType forms

Wrong:

type FormA = ReactFormType<typeof formAOptions>
type FormB = ReactFormType<typeof formBOptions>

interface SharedSectionProps {
  form: FormA | FormB
}

Correct:

const sharedFieldGroup = defineFieldGroup(({ strict }) => ({
  value: strict<string>(),
}))

function SharedSection({ fields }: { fields: typeof sharedFieldGroup.fields }) {
  return (
    <fields.Field name="value">
      {(field) => <input value={field.value} />}
    </fields.Field>
  )
}

export const BoundSharedSection = sharedFieldGroup.bindComponent(
  SharedSection,
  'fields',
)

TypeScript cannot usefully narrow a union of different form APIs; field groups are the reusable cross-form abstraction.

Source: maintainer interview, TanStack/form-v2:packages/react-form/src/FieldGroup/withFields.public.ts