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

SKILL.md

238 lines5.3 KB

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

References