At the core of TanStack Form's functionalities is the concept of validation. TanStack Form makes validation highly customizable:
- You can control when to perform the validation (on change, on input, on blur, on submit...)
- Validation rules can be defined at the field level or at the form level
- Validation can be synchronous or asynchronous (for example, as a result of an API call)
When is validation performed?#
It's up to you! The <Field /> component accepts some callbacks as props such as onChange or onBlur. Those callbacks are passed the current value of the field, as well as the fieldAPI object, so that you can perform the validation. If you find a validation error, simply return the error message as string and it will be available in field.state.meta.errors.
Here is an example:
<template>
<!-- ... -->
<form.Field
name="age"
:validators="{
onChange: ({ value }) => value < 13 ? 'You must be 13 to make an account' : undefined,
}">
<template v-slot="{ field }">
<label :for="field.name">Age:</label>
<input
:id="field.name"
:name="field.name"
:value="field.state.value"
type="number"
@input="(e) => field.handleChange((e.target as HTMLInputElement).valueAsNumber)
"
/>
<em role="alert" v-if="field.state.meta.errors">{{ field.state.meta.errors.join(', ') }}</em>
</template>
</form.Field>
<!-- ... -->
</template>
In the example above, the validation is done at each keystroke (onChange). If, instead, we wanted the validation to be done when the field is blurred, we would change the code above like so:
<template>
<!-- ... -->
<form.Field
name="age"
:validators="{
onBlur: ({ value }) => value < 13 ? 'You must be 13 to make an account' : undefined,
}">
<template v-slot="{ field }">
<label :for="field.name">Age:</label>
<!-- We always need to implement onChange, so that TanStack Form receives the changes -->
<!-- Listen to the onBlur event on the field -->
<input
:id="field.name"
:name="field.name"
:value="field.state.value"
type="number"
@blur="field.handleBlur"
@input="(e) => field.handleChange((e.target as HTMLInputElement).valueAsNumber)
"
/>
<em role="alert" v-if="field.state.meta.errors">{{ field.state.meta.errors.join(', ') }}</em>
</template>
</form.Field>
<!-- ... -->
</template>
So you can control when the validation is done by implementing the desired callback. You can even perform different pieces of validation at different times:
<template>
<!-- ... -->
<form.Field
name="age"
:validators="{
onChange: ({ value }) => value < 13 ? 'You must be 13 to make an account' : undefined,
onBlur: ({ value }) => (value < 0 ? 'Invalid value' : undefined),
}">
<template v-slot="{ field }">
<label :for="field.name">Age:</label>
<!-- We always need to implement onChange, so that TanStack Form receives the changes -->
<!-- Listen to the onBlur event on the field -->
<input
:id="field.name"
:name="field.name"
:value="field.state.value"
type="number"
@blur="field.handleBlur"
@input="(e) => field.handleChange((e.target as HTMLInputElement).valueAsNumber)
"
/>
<em role="alert" v-if="field.state.meta.errors">{{ field.state.meta.errors.join(', ') }}</em>
</template>
</form.Field>
<!-- ... -->
</template>
In the example above, we are validating different things on the same field at different times (at each keystroke and when blurring the field). Since field.state.meta.errors is an array, all the relevant errors at a given time are displayed. You can also use field.state.meta.errorMap to get errors based on when the validation was done (onChange, onBlur etc...). More info about displaying errors below.
Displaying Errors#
Once you have your validation in place, you can map the errors from an array to be displayed in your UI:
<template>
<!-- ... -->
<form.Field
name="age"
:validators="{
onChange: ({ value }) => value < 13 ? 'You must be 13 to make an account' : undefined,
}">
<template v-slot="{ field }">
<!-- ... -->
<em role="alert" v-if="field.state.meta.errors">{{ field.state.meta.errors.join(', ') }}</em>
</template>
</form.Field>
<!-- ... -->
</template>
Or use the errorMap property to access the specific error you're looking for:
<template>
<!-- ... -->
<form.Field
name="age"
:validators="{
onChange: ({ value }) => value < 13 ? 'You must be 13 to make an account' : undefined,
}">
<template v-slot="{ field }">
<!-- ... -->
<em role="alert" v-if="field.state.meta.errorMap['onChange']">{{ field.state.meta.errorMap['onChange'] }}</em>
</template>
</form.Field>
<!-- ... -->
</template>
Validation at field level vs at form level#
As shown above, each <Field> accepts its own validation rules via the onChange, onBlur etc... callbacks. It is also possible to define validation rules at the form level (as opposed to field by field) by passing similar callbacks to the useForm() function.
Example:
<script setup lang="ts">
import { useForm } from '@tanstack/vue-form'
const form = useForm({
defaultValues: {
age: 0
},
onSubmit: async ({ value }) => {
console.log(value)
},
validators: {
// Add validators to the form the same way you would add them to a field
onChange({ value }) {
if (value.age < 13) {
return 'Must be 13 or older to sign'
}
return undefined
},
},
})
// Subscribe to the form's error map so that updates to it will render
// alternately, you can use `form.Subscribe`
const formErrorMap = form.useStore((state) => state.errorMap)
</script>
<template>
<!-- ... -->
<div v-if="formErrorMap.onChange">
<em role="alert">
There was an error on the form: {{formErrorMap.onChange }}
</em>
</div>
<!-- ... -->
</template>
Asynchronous Functional Validation#
While we suspect most validations will be synchronous, there are many instances where a network call or some other async operation would be useful to validate against.
To do this, we have dedicated onChangeAsync, onBlurAsync, and other methods that can be used to validate against:
<script setup lang="ts">
// ...
const onChangeAge = async ({ value }) => {
await new Promise((resolve) => setTimeout(resolve, 1000))
return value < 13 ? 'You must be 13 to make an account' : undefined
}
</script>
<template>
<!-- ... -->
<form.Field
name="age"
:validators="{
onChangeAsync: onChangeAge,
}">
<template v-slot="{ field }">
<label :for="field.name">Age:</label>
<input
:id="field.name"
:name="field.name"
:value="field.state.value"
type="number"
@input="(e) => field.handleChange((e.target as HTMLInputElement).valueAsNumber)
"
/>
<em role="alert" v-if="field.state.meta.errors">{{ field.state.meta.errors.join(', ') }}</em>
</template>
</form.Field>
<!-- ... -->
</template>
Synchronous and Asynchronous validations can coexist. For example, it is possible to define both onBlur and onBlurAsync on the same field:
<script setup lang="ts">
// ...
const onBlurAge = ({ value }) => value < 0 ? 'Invalid value' : undefined
const onBlurAgeAsync = async ({ value }) => {
const currentAge = await fetchCurrentAgeOnProfile()
return value < currentAge ? 'You can only increase the age' : undefined
}
</script>
<template>
<!-- ... -->
<form.Field
name="age"
:validators="{
onBlur: onBlurAge,
onBlurAsync: onBlurAgeAsync,
}"
>
<template v-slot="{ field }">
<label :for="field.name">Age:</label>
<input
:id="field.name"
:name="field.name"
:value="field.state.value"
type="number"
@blur="field.handleBlur"
@input="(e) => field.handleChange((e.target as HTMLInputElement).valueAsNumber)
"
/>
<em role="alert" v-if="field.state.meta.errors">{{ field.state.meta.errors.join(', ') }}</em>
</template>
</form.Field>
<!-- ... -->
</template>
The synchronous validation method (onBlur) is run first and the asynchronous method (onBlurAsync) is only run if the synchronous one (onBlur) succeeds. To change this behaviour, set the asyncAlways option to true, and the async method will be run regardless of the result of the sync method.
Built-in Debouncing#
While async calls are the way to go when validating against the database, running a network request on every keystroke is a good way to DDOS your database.
Instead, we enable an easy method for debouncing your async calls by adding a single property:
<template>
<!-- ... -->
<form.Field
name="age"
:async-debounce-ms="500"
:validators="{
onChangeAsync: async ({value}) => {
// ...
},
}">
<template v-slot="{ field }">
<!-- ... -->
</template>
</form.Field>
<!-- ... -->
</template>
This will debounce every async call with a 500ms delay. You can even override this property on a per-validation property:
<template>
<!-- ... -->
<form.Field
name="age"
:async-debounce-ms="500"
:validators="{
onChangeAsyncDebounceMs: 1500,
onChangeAsync: async ({value}) => {
// ...
},
onBlurAsync: async ({value}) => {
// ...
},
}">
<template v-slot="{ field }">
<!-- ... -->
</template>
</form.Field>
<!-- ... -->
</template>
This will run onChangeAsync every 1500ms while onBlurAsync will run every 500ms.
Adapter-Based Validation (Zod, Yup, Valibot)#
While functions provide more flexibility and customization over your validation, they can be a bit verbose. To help solve this, there are libraries like Valibot, Yup, and Zod that provide schema-based validation to make shorthand and type-strict validation substantially easier.
Luckily, we support all of these libraries through official adapters:
$ npm install @tanstack/zod-form-adapter zod
# or
$ npm install @tanstack/yup-form-adapter yup
# or
$ npm install @tanstack/valibot-form-adapter valibot
Once done, we can add the adapter to the validator property on the form or field:
<script setup lang="ts">
import { zodValidator } from '@tanstack/zod-form-adapter'
import { z } from 'zod'
// ...
const form = useForm({
// Either add the validator here or on `Field`
validatorAdapter: zodValidator(),
// ...
})
</script>
<template>
<!-- ... -->
<form.Field
name="age"
:validator-adapter="zodValidator()"
:validators="{
onChange: z.number().gte(13, 'You must be 13 to make an account')
}"
>
<template v-slot="{ field }">
<!-- ... -->
</template>
</form.Field>
<!-- ... -->
</template>
These adapters also support async operations using the proper property names:
<template>
<!-- ... -->
<form.Field
name="age"
:validators="{
onChange: z.number().gte(13, 'You must be 13 to make an account'),
onChangeAsyncDebounceMs: 500,
onChangeAsync: z.number().refine(
async (value) => {
const currentAge = await fetchCurrentAgeOnProfile()
return value >= currentAge
},
{
message: 'You can only increase the age',
},
),
}"
>
<template v-slot="{ field }">
<!-- ... -->
</template>
</form.Field>
<!-- ... -->
</template>
Form Level Adapter Validation#
You can also use the adapter at the form level:
import { zodValidator } from '@tanstack/zod-form-adapter'
import { z } from 'zod'
// ...
const form = useForm({
validatorAdapter: zodValidator(),
validators: {
onChange: z.object({
age: z.number().gte(13, 'You must be 13 to make an account'),
}),
},
})
If you use the adapter at the form level, it will pass the validation to the fields of the same name.
This means that:
<template>
<!-- ... -->
<form.Field
name="age"
>
<template v-slot="{ field }">
<!-- ... -->
</template>
</form.Field>
</template>
Will still display the error message from the form-level validation.
Preventing invalid forms from being submitted#
The onChange, onBlur etc... callbacks are also run when the form is submitted and the submission is blocked if the form is invalid.
The form state object has a canSubmit flag that is false when any field is invalid and the form has been touched (canSubmit is true until the form has been touched, even if some fields are "technically" invalid based on their onChange/onBlur props).
You can subscribe to it via form.Subscribe and use the value in order to, for example, disable the submit button when the form is invalid (in practice, disabled buttons are not accessible, use aria-disabled instead).
<script setup lang="ts">
const form = useForm(/* ... */)
</script>
<template>
<!-- ... -->
<!-- Dynamic submit button -->
<form.Subscribe>
<template v-slot="{ canSubmit, isSubmitting }">
<button type="submit" :disabled="!canSubmit">
{{ isSubmitting ? '...' : 'Submit' }}
</button>
</template>
</form.Subscribe>
<!-- ... -->
</template>