Tanstack Vue Form Skilld

Also changed: resetFieldMeta() new helper · insertFieldValue() array utility · moveFieldValues() array utility · swapFieldValues() array utility · FieldApi.getInfo() metadata helper · VueFieldApi interface stabilization · VueFormApi interface stabilization

Best Practices

• Use formOptions() to define type-safe, reusable form configurations that can be shared across components or used for better type inference source

const options = formOptions({
  defaultValues: { email: '' },
  validators: {
    onChange: z.object({ email: z.string().email() })
  }
})

const form = useForm(options)

• Link field validations with onChangeListenTo to trigger re-validation when dependent field values change, such as password confirmations source

<form.Field
  name="confirm_password"
  :validators="{
    onChangeListenTo: ['password'],
    onChange: ({ value, fieldApi }) =>
      value !== fieldApi.form.getFieldValue('password') ? 'Passwords do not match' : undefined
  }"
>

• Implement async-debounce-ms at the field or validator level to throttle expensive asynchronous validation calls like API checks source

<form.Field
  name="username"
  :async-debounce-ms="500"
  :validators="{
    onChangeAsync: async ({ value }) => checkUsername(value)
  }"
>

• Parse Standard Schemas manually within onSubmit to retrieve transformed values, as the form state preserves the raw input data source

const form = useForm({
  onSubmit: ({ value }) => {
    // schema.parse converts string to number if transform is defined
    const validatedData = loginSchema.parse(value)
    api.submit(validatedData)
  }
})

• Pass custom metadata via onSubmitMeta to differentiate between multiple submission actions within a single onSubmit handler source

<button @click="form.handleSubmit({ action: 'save_draft' })">Save Draft</button>
<button @click="form.handleSubmit({ action: 'publish' })">Publish</button>

• Combine canSubmit with isPristine to ensure the submit button remains disabled until the user has actually interacted with the form source

<template v-slot="{ canSubmit, isPristine }">
  <button :disabled="!canSubmit || isPristine">Submit</button>
</template>

• Use form.useStore with a selector in <script setup> for granular, reactive access to form state without re-rendering on unrelated changes source

const canSubmit = form.useStore((state) => state.canSubmit)

• Enable asyncAlways: true when you need asynchronous validators to execute regardless of whether synchronous validation has already failed source

// Runs async validation even if local regex check fails
const validators = {
  onChange: ({ value }) => !value.includes('@') ? 'Invalid' : undefined,
  onChangeAsync: async ({ value }) => api.check(value),
  asyncAlways: true
}

• Return a fields mapping from form-level validators to update errors across multiple fields simultaneously from a single validation logic source