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

SKILL.md

252 lines5.5 KB

This skill builds on choosing-form-options-modes. Read it first to pick default, strict schema, or loose schema mode.

TanStack React Form - Schema Driven Forms

Put Standard Schema-compatible schemas in validators. Read parsed schema output from validatorOutputs; keep raw value as editable form state.

Setup

import { formOptions, useForm } from '@tanstack/react-form'
import { z } from 'zod'

const profileSchema = z.object({
  name: z.string().min(1, 'Name is required'),
  email: z.email('Email is invalid'),
})

const profileOptions = formOptions.strictSchema({
  defaultValues: {
    name: '',
    email: '',
  },
  validators: [{ run: profileSchema, triggers: ['blur'] }],
  onSubmit: ({ validatorOutputs }) => {
    const parsedProfile = validatorOutputs[0]
    console.log(parsedProfile.email)
  },
})

export function ProfileForm() {
  const form = useForm(profileOptions)

  return (
    <form.Field name="email">
      {(field) => (
        <label>
          <input
            value={field.value}
            onBlur={field.handleBlur}
            onChange={(event) => field.handleChange(event.target.value)}
          />
          <small>{field.errors.map((error) => error.message).join('\n')}</small>
        </label>
      )}
    </form.Field>
  )
}

Hooks And Components

Return server validation values from onSubmit

const form = useForm({
  defaultValues: {
    email: '',
  },
  onSubmit: async ({ value, createValidationError }) => {
    const result = await saveEmail(value.email)

    if (result.kind === 'validation') {
      return createValidationError({
        fields: {
          email: result.message,
        },
      })
    }
  },
})

async function saveEmail(email: string) {
  return email.endsWith('@taken.test')
    ? { kind: 'validation' as const, message: 'Email is already taken' }
    : { kind: 'ok' as const }
}

Validation errors are returned values. Throw only transient failures.

Convert Standard Schema issues from submit

onSubmit: ({ value, parseIssues }) => {
  const result = profileSchema.safeParse(value)

  if (!result.success) {
    return parseIssues(result.error.issues)
  }
}

Use parseIssues when an endpoint or local schema check returns Standard Schema-shaped issues.

Exclude a schema from submit output

const validateWhileEditing = {
  run: profileSchema,
  triggers: ['change'],
  skipOnSubmit: true,
}

skipOnSubmit: true means that validator does not contribute a parsed submit output.

Common Mistakes

HIGH Expecting schema output to replace value

Wrong:

onSubmit: ({ value }) => {
  console.log(value.nameLength)
}

Correct:

onSubmit: ({ validatorOutputs }) => {
  const parsed = validatorOutputs[0]
  console.log(parsed.nameLength)
}

Schema output is stored separately so form state can remain editable.

Source: TanStack/form-v2:packages/form-core/tests/validation.test.ts

HIGH Throwing validation errors

Wrong:

onSubmit: () => {
  throw new Error('Email is already taken')
}

Correct:

onSubmit: ({ createValidationError }) => {
  return createValidationError({
    fields: {
      email: 'Email is already taken',
    },
  })
}

Thrown errors are submit failures; validation errors must be returned values.

Source: TanStack/form-v2:packages/form-core/tests/FormApi/submission-handling.spec.ts

HIGH Returning raw schema errors

Wrong:

onSubmit: ({ value }) => {
  const result = profileSchema.safeParse(value)
  return result.success ? null : result.error
}

Correct:

onSubmit: ({ value, parseIssues }) => {
  const result = profileSchema.safeParse(value)
  return result.success ? null : parseIssues(result.error.issues)
}

parseIssues maps Standard Schema issue paths into form and field validation state.

Source: TanStack/form-v2:packages/form-core/src/FormApi/FormApi.public.ts

MEDIUM Mapping paths by hand

Wrong:

return createValidationError({
  fields: {
    users: 'Second user email is invalid',
  },
})

Correct:

return parseIssues([
  {
    message: 'Email is invalid',
    path: ['users', 1, 'email'],
  },
])

Let Standard Schema issue paths route nested and array errors when possible.

Source: TanStack/form-v2:packages/form-core/src/standardSchema.public.ts

MEDIUM Inferring UI metadata from Standard Schema

Wrong:

const required = Boolean(profileSchema.shape.email)

Correct:

const emailLabel = 'Email address'
const emailRequired = true

Standard Schema standardizes validation, not UI metadata such as required labels.

Source: maintainer interview

References