================================================
FILE: docs/src/pages/api/composition-helpers.mdx
================================================
---
layout: ../../layouts/PageLayout.astro
title: Composition Helpers
description: Various composable functions to compose validation logic into your components
order: 9
---
import DocTip from '@/components/DocTip.vue';
import CodeTitle from '@/components/CodeTitle.vue';
# Composition Helpers
The composition helpers are various functions that you can use to craft specialized form components, like a submission indicator component or a custom error messages component.
These functions expose validation state to child components, most of these functions expose 2 variants of each state. On a form level and a field level.
## API Reference
All of the following code snippets assume you are using them inside a `setup` function.
`useFieldError(field?: string): ComputedRef`
Returns a computed ref to a single field's error message, returns `undefined` if no errors were found for that field or if the field does not exist.
```js
import { useFieldError } from 'vee-validate';
const message = useFieldError('fieldName');
message.value; // string or `undefined`
```
You can also use it in a child component that has a parent that used `useField`, The `useFieldError` will automatically pick up the field and produce its error messages.
```js
import { useFieldError } from 'vee-validate';
// Will look for the first parent that used `useField`
const message = useFieldError();
message.value;
```
`useFormErrors(): ComputedRef>`
Returns a computed ref to the error bag of the entire form, fields with no errors will not be included in the error bag object.
```js
import { useFormErrors } from 'vee-validate';
const errors = useFormErrors();
message.value; // {}
```
`useIsFieldDirty(field?: string): ComputedRef`
Returns a computed ref to the specified field's `dirty` meta state.
```js
import { useIsFieldDirty } from 'vee-validate';
const isDirty = useIsFieldDirty();
isDirty.value; // true or false
```
You can also use it in a child component that has a parent that used `useField`, The `useIsFieldDirty` will automatically pick up the field and produce its meta `dirty` value
```js
import { useIsFieldDirty } from 'vee-validate';
// Will look for the first parent that used `useField`
const isDirty = useIsFieldDirty();
```
`useIsFormDirty(): ComputedRef`
Returns a computed ref to the context form `dirty` meta state.
```js
import { useIsFormDirty } from 'vee-validate';
const isDirty = useIsFormDirty();
isDirty.value; // true or false
```
`useIsFieldTouched(field?: string): ComputedRef`
Returns a computed ref to the specified field's `touched` meta state.
```js
import { useIsFieldTouched } from 'vee-validate';
const isTouched = useIsFieldTouched('fieldName');
isTouched.value; // true or false
```
You can also use it in a child component that has a parent that used `useField`, The `useIsFieldTouched` will automatically pick up the field and produce its meta `touched` value
```js
import { useIsFieldTouched } from 'vee-validate';
// Will look for the first parent that used `useField`
const isTouched = useIsFieldTouched();
```
`useIsFormTouched(): ComputedRef`
Returns a computed ref to the context form `touched` meta state.
```js
import { useIsFormTouched } from 'vee-validate';
const isTouched = useIsFormTouched();
isTouched.value; // true or false
```
`useIsFieldValid(field?: string): ComputedRef`
Returns a computed ref to the specified field's `valid` meta state, inner `value` will be `true` if the field has no errors, and `false` if it has any error message.
```js
import { useIsFieldValid } from 'vee-validate';
const isValid = useIsFieldValid('fieldName');
isValid.value; // true or false
```
You can also use it in a child component that has a parent that used `useField`, The `useIsFieldValid` will automatically pick up the field and produce its meta `valid` value
```js
import { useIsFieldValid } from 'vee-validate';
// Will look for the first parent that used `useField`
const isValid = useIsFieldValid();
```
Creating disabled buttons based on the `valid` attribute isn't accurate, because if the field hasn't been validated yet it, the `valid` property will be `true` which isn't accurate. You should combine `valid` checks with `dirty` state to get the most accuracy.
`useIsFormValid(): ComputedRef`
Returns a computed ref to the context form `valid` meta state.
```js
import { useIsFormValid } from 'vee-validate';
const isValid = useIsFormValid();
isValid.value; // true or false
```
Creating disabled buttons based on the `valid` attribute isn't accurate, because if the form hasn't been validated yet it, the `valid` property will be `true` which isn't accurate. You should combine `valid` checks with `dirty` state to get the most accuracy.
`useValidateField(field?: string): () => Promise`
Returns a function that validates the field and returns a validation result object containing any errors, if the `errors` field is empty then it means the field is valid. If a field doesn't not exist it will return an empty `errors` field with a warning.
```js
import { useValidateField } from 'vee-validate';
const validate = useValidateField('fieldName');
await validate();
```
You can also use it in a child component that has a parent that used `useField`, The `useValidateField` will automatically pick up the field and will return the function that validates it.
```js
import { useValidateField } from 'vee-validate';
// Will look for the first parent that used `useField`
const validate = useValidateField();
```
`useValidateForm(): () => Promise`
Returns a function that validates the form and returns a `Form`.
```js
import { useValidateForm } from 'vee-validate';
const validate = useValidateForm();
await validate();
```
`useIsSubmitting(): ComputedRef`
Returns a computed ref to the form's `isSubmitting` state.
```js
import { useIsSubmitting } from 'vee-validate';
const isSubmitting = useIsSubmitting();
isSubmitting.value; // true or false
```
`useIsValidating(): ComputedRef`
Returns a computed ref to the form's `isValidating` state.
```js
import { useIsValidating } from 'vee-validate';
const isValidating = useIsValidating();
isValidating.value; // true or false
```
`useSubmitCount(): ComputedRef`
Returns a computed ref to the form's `submitCount` state.
```js
import { useSubmitCount } from 'vee-validate';
const count = useSubmitCount();
count.value;
```
`useResetForm(): () => void`
Returns a function that you can use to reset the form
```js
import { useResetForm } from 'vee-validate';
const resetForm = useResetForm();
resetForm(); // resets the form
```
`useSubmitForm(cb: SubmissionHandler): () => void`
Returns a function that you can use to validate the form and submit if it turns out valid. It does this by accepting a function that should handle the submission logic like sending data to your API. That function will not run unless the form is valid and it receives all the fields current values packed in an object.
```js
import { useSubmitForm } from 'vee-validate';
const submitForm = useSubmitForm((values, actions) => {
// Send data to your api ...
alert(JSON.stringify(values, null, 2));
// You can perform any of the form actions using the actions object
// set a single field value
actions.setFieldValue('field', 'hello');
// set multiple fields values
actions.setValues({ email: 'value', password: 'hi' });
// set a single field error
actions.setFieldError('field', 'this field is bad');
// set multiple fields errors
actions.setErrors({ email: 'bad email', password: 'bad password' });
// reset the form
actions.resetForm();
});
```
While it is recommended to use actual `form` elements for accessibility, you could still use `useSubmitForm` to submit any group of data which may or may not be involved with a `form` element.
`useFieldValue(field?: string): ComputedRef`
Returns a computed ref to the specified field's current value.
```js
import { useFieldValue } from 'vee-validate';
const currentValue = useFieldValue('fieldName');
currentValue.value;
```
You can also use it in a child component that has a parent that used `useField`, The `useFieldValue` will automatically pick up the field and produce its current value.
```js
import { useFieldValue } from 'vee-validate';
// Will look for the first parent that used `useField`
const currentValue = useFieldValue();
```
`useFormValues(): ComputedRef>`
Returns a computed ref to the context form current values.
```js
import { useFormValues } from 'vee-validate';
const values = useFormValues();
values.value;
```
================================================
FILE: docs/src/pages/api/configuration.mdx
================================================
---
layout: ../../layouts/PageLayout.astro
title: Configuration
description: VeeValidate Global Config Reference
order: 8
---
import DocTip from '@/components/DocTip.vue';
# Configuration
vee-validate exposes global configs to help with a few repeated or certain behaviors that needs to be set app-wide.
## Config Options
| Option | Type | Description |
| --------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| bails | `boolean` | Whether to run validations to completion or quit on the first, default is `true`. Doesn't affect `yup` schemas |
| generateMessage | `(ctx: FieldValidationMetaInfo) => string` | A message generator function for i18n libraries and a fallback for rules with no messages. For more information about the [`FieldValidationMetaInfo`](https://github.com/logaretm/vee-validate/blob/main/packages/shared/types.ts#L1-L9) type and the purpose of this, see the [Global Message Generator Guide](/guide/i18n#global-message-generator) |
| validateOnBlur | `boolean` | If validation should be triggered on `blur` event, default is `true` |
| validateOnChange | `boolean` | If validation should be triggered on `change` event, default is `true` |
| validateOnInput | `boolean` | If validation should be triggered on `input` event, default is `false` |
| validateOnModelUpdate | `boolean` | If validation should be triggered on `update:modelValue` (v-model) event, default is `true` |
This is slightly verbose, but this gives you exact control on which events triggers validation.
## Updating The Config
You can change the global config using the `configure` function exposed by vee-validate passing any options that you need to change. You can call that function at any time during runtime but the changes will take effect for new `Field` and `useField` afterwards.
Here is an example:
```js
import { configure } from 'vee-validate';
configure({
bails: false,
});
```
Note that the following config do not affect `useField`, they only apply to the `` component:
- `validateOnBlur`
- `validateOnChange`
- `validateOnInput`
- `validateOnModelUpdate`
================================================
FILE: docs/src/pages/api/error-message.mdx
================================================
---
layout: ../../layouts/PageLayout.astro
title: ErrorMessage
description: API reference for the ErrorMessage component
menuTitle: ''
order: 3
---
import DocTip from '@/components/DocTip.vue';
# ErrorMessage
The `ErrorMessage` component is used to conveniently display error messages without resorting to scoped slots on either the `Form` and `Field` components. It also renders nothing if there are no messages for the associated field.
The basic usage looks like this:
```vue
```
## Rendering Messages
The `ErrorMessage` component accepts an `as` prop that allows to control the root node to render for your error messages, by default it will render a `span` if none provided if there is an error message for the field.
```vue-html
```
For more flexible markup and the ability to render multiple root nodes, you can use the `ErrorMessage` component's default scoped slot
```vue-html
Error:
{{ message }}
```
If an `as` prop is not provided while having a slot, it will render the slot contents only. _Effectively becoming a renderless-component._
You can use a combination of both to render a root node with children:
```vue-html
Error:
{{ message }}
```
When there are not any error messages for the field the `` component will render nothing, even if you used the slot or `as` prop.
## API
### Props
| Prop | Type | Required/Default | Description |
| :--- | :------- | :--------------- | :--------------------------------------- |
| as | `string` | `"span"` | The element to render as a root node |
| name | `string` | Required | The field's name to display messages for |
### Slots
#### default
The default slot gives you access to the following props:
| Scoped Prop | Type | Description |
| :---------- | :------- | :-------------------------- |
| message | `string` | The element's error message |
Check the sample above for rendering with scoped slots
## Caveats
- The ErrorMessage component must be used inside a `Form` component otherwise it won't be able to find the errors.
- ErrorMessage component can only display errors for a field that exists within the same form, it cannot reference fields outside its own form.
================================================
FILE: docs/src/pages/api/field-array.mdx
================================================
---
layout: ../../layouts/PageLayout.astro
title: FieldArray
description: API reference for the Field Array component
menuTitle: ''
order: 4
---
import DocTip from '@/components/DocTip.vue';
import DocBadge from '@/components/DocBadge.vue';
import CodeTitle from '@/components/CodeTitle.vue';
# FieldArray
The `` component requires being used inside a `Form` component or a `useForm` to be called at its parent tree.
The `` component is used to manage repeatable array fields. It is a renderless component, meaning it doesn't render anything of its own.
```vue
```
## API Reference
### Props
| Prop | Type | Required/Default | Description |
| :---------- | :------- | :--------------- | :------------------------------------- |
| `arrayPath` | `string` | Yes | The form array path you wish to manage |
### Slots
#### default
The default slot gives you access to the following props:
`fields: FieldArrayEntry`
This is a **read-only** version of your array items, wrapped inside a `FieldArrayEntry` object which has the following interface:
```ts
interface FieldEntry {
// The actual value of the item, this is what exists in the form values
value: TValue;
// a value you can use as a key for iteration, automatically generated.
key: string | number;
// true if this is the first array item
isFirst: boolean;
// true if this is the last array item
isLast: boolean;
}
```
`push(item: any)`
Adds an item to the end of the array.
`prepend(item: any)`
Adds an item to the start of the array.
`remove(idx: number)`
Removes the item at the specified index from the array if it exists.
`swap(idxA: number, idxB: number)`
Swaps the items at the given indexes with each other. Both indexes must exist in the array or it won't have an effect.
`insert(idx: number, item: any)`
Adds an item at the specified index. If the specified index will place the item out of bounds (i.e: larger than length) the operation will be ignored, you still can add items as the last item of the array.
`update(idx: number, value: any)`
Updates the value at the specified index, note that it doesn't merge the values if they are objects. If the specified index is outside the array boundary the operation will be ignored.
`replace(items: any[])`
Replaces the entire array of fields.
`move(oldIdx: number, newIdx: number)`
Moves an array item to a different position within the array. If one of the indices is outside of the array boundaries the operation will be ignored.
================================================
FILE: docs/src/pages/api/field.mdx
================================================
---
layout: ../../layouts/PageLayout.astro
title: Field
description: API reference for the Field component
menuTitle: ''
order: 1
---
import DocTip from '@/components/DocTip.vue';
import CodeTitle from '@/components/CodeTitle.vue';
# Field
The `` component is an extremely flexible component that makes rendering input fields easy and intuitive, By default it renders an HTML `input` tag. So a simple text input can be rendered like this:
```vue
```
## Rendering Fields
The `Field` component allows you to render practically anything and gives you complete flexibility and control over how your fields are rendered. The `Field` component renders an HTML `input` tag if not specified otherwise. Which can be done in two ways.
### Rendering simple fields with 'as' prop
The `as` prop tells the Field component which tag to render in its place, you can pass any additional attributes like `type="text"` and it will be passed to the rendered `input` tag as well as any listeners and slots.
For example you could render a `select` input like this:
```vue-html
```
The `Field` component has partial support for native `select[multiple]` element, while it picks up the multiple values correctly, it doesn't set the initial values UI state on the element itself. You may use `v-model` here or bind the `selected` attributes on the options which is straightforward with the `value` prop exposed on the slot props.
```vue-html
```
You can also render any globally defined components:
```vue-html
```
For validation to work, the rendered tag with `as` prop must conform to the events that the `Field` component listens for, you can view a list of these in the [Validation Behavior](/guide/components/validation#validation-behavior)
### Rendering Complex Fields with Scoped Slots
The `as` prop is very easy to use but also limited as you cannot render a group of markup. Fortunately the `Field` component makes use of the scoped-slots (v-slot) feature to allow you to render complex markup:
```vue-html
Hint: Enter a secure password you can remember
```
The most crucial part of rendering fields with `v-slot` is that you **bind the `field` object to your input element/input**, the `field` object contains all the common attributes and listeners required for the field to be validated, this is done automatically if you are using the `as` prop.
When rendering File inputs and custom components, binding the `field` object may not be a good idea in these cases as generally you need to pick the suitable attributes that you should bind. In the case of `input[type="file"]` you could do something like this:
```vue-html
```
This is because the file input doesn't work with two-way binding since you cannot really force pick a file from a user's device. Custom components may emit different events and may have additional requirements for two-way binding to work. You can check the [UI Libraries](/examples/ui-libraries) section for a few examples on how to do that.
When using `v-slot` on the `Field` component you no longer have to provide an `as` prop and then it will become a renderless component.
Whichever element/component you chose to render with `` you can pass also any props or attributes the element/component would normally receive for example if you render `input` elements you can pass any of it's attributes like `type` or `disabled` to just name a few.
### Using v-model
The `` component uses a different way to apply input values to your rendered inputs using the `v-bind="field"` syntax which adds various listeners and attributes to your rendered inputs.
Because of this, using `v-model` will conflict with `v-bind="field"` because both will attempt to update the input value.
For simple inputs this is not an issue:
```vue-html
```
But for complex inputs rendered with scoped slots (v-slot), you need to place it on the `Field` component tag itself, not the rendered input.
```vue-html
```
Note that you no longer should use `v-model` on your input as `v-bind="field"` will take care of the rest.
## API Reference
### Props
| Prop | Type | Required/Default | Description |
| :-------------------- | :----------------------------- | :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| as | `string` | `"span"` | The element to render as a root node, defaults to `input` |
| name | `string` | Required | The field's name, must be inside `` |
| rules | `object \| string \| Function` | `null` | The field's validation rules |
| validateOnMount | `boolean` | `false` | If true, field will be validated when the component is mounted |
| validateOnInput | `boolean` | `false` | If true, field will be validated when `input` event is dispatched/emitted |
| validateOnChange | `boolean` | `true` | If true, field will be validated when `change` event is dispatched/emitted |
| validateOnBlur | `boolean` | `true` | If true, field will be validated when `blur` event is dispatched/emitted |
| validateOnModelUpdate | `boolean` | `true` | If true, field will be validated when `update:modelValue` event is emitted |
| bails | `boolean` | `true` | Stops validating as soon as a rule fails the validation |
| label | `string` | `undefined` | A different string to override the field `name` prop in error messages, useful for display better or formatted names. The generated message won't be updated if this prop changes, you will need to re-validate the input. |
| value | `any` | `undefined` | The field's initial value, optional as long as the field type is not `checkbox` or `radio`. |
| type | `string` | `undefined` | The field type, must be provided if you want your field to behave as a `checkbox` or a `radio` input. |
| unchecked-value | `any` | `undefined` | Only useful when the `type="checkbox"` and the field is a single checkbox field (not bound to an array value). Controls the input's value when it's unchecked. |
| standalone | `boolean` | `false` | Excludes the field from participating in any `Form` or `useForm` contexts, useful for creating inputs that do contribute to the `values` object. In other words, the form won't pick up or validate fields marked as standalone |
| keepValue | `boolean` | `undefined` | If the field value should be kept in the form when it gets unmounted, default follows the form's configuration |
### Slots
#### default
The default slot gives you access to the following props:
`meta: FieldMeta`
Contains useful information/flags about the field status.
```ts
interface FieldMeta {
touched: boolean; // if the field has been blurred (via handleBlur)
dirty: boolean; // if the field has been manipulated (via handleChange)
valid: boolean; // if the field doesn't have any errors
validated: boolean; // if the field has been validated
pending: boolean; // if validation is in progress
initialValue?: any; // the field's initial value
}
```
The `valid` flag on the meta object can be tricky, because by default it stars off with `true` for a few moments, only then it is updated to its proper state.
Combining your `valid` flag checks with `dirty` will yield the expected result based on user interaction.
`errors: string[]`
An array containing all error messages for the field.
`value: unknown`
The current value of the field, useful to compare and do conditional rendering based on the field value. **You should not use it as a target of `v-model` or `:value` binding**. Instead use the `field` prop.
`errorMessage: ComputedRef`
The first error in the `errors` array if available, a handy shortcut to display error messages
`resetField: (state?: Partial) => void`
Resets the field's validation state, reverts all `meta` object to their default values and clears out the error messages, it will also reset the field value to it's initial value. Note that no error messages will be generated if the initial value is invalid after reset, the `valid` flag will be then set to `true` in that case.
Note that it is unsafe to use this function as an event handler directly, check the following snippet:
```vue-html
```
You can use `resetField` to update the fields' current value to something other than its initial value,
```vue-html
```
`handleReset: () => void`
Similar to `resetField` but it doesn't accept any arguments and can be safely used as an event handler. The values won't be validated after reset.
`validate: () => Promise<{ errors: string[] }>`
Validates the field's current value and returns a promise that resolves with an object containing the error messages emitted by the various rule(s).
```js
const { validate } = useField('field', value => !!value);
// trigger validation
await validate();
```
`handleChange: (evt: Event | any, shouldValidate?: boolean) => void`
Updates the field value, and validates the field by default. Can be used as an event handler to bind on the field. If the passed argument isn't an event object it will be used as the new value for that field.
You can update the field value without validation by passing `false` as a second argument.
`handleBlur: (evt: Event | any) => void`
Validates the field by default unless explicitly [specified by validation triggers](/guide/components/validation#customizing-validation-triggers). Can be used as an event handler to bind on the field. If the passed argument isn't an event object it will be used as the new value for that field.
It sets the `touched` meta flag to true
Because this handler doesn't set the field value, it might not report validation correctly if other events are unspecified or disabled.
`setTouched: (isTouched: boolean) => void`
Sets the `touched` meta flag for this field, useful to create your own `blur` handlers
#### `field`
Contains a few properties that you can use `v-bind` with to get all vee-validate features on that input. The following is a description of the properties
`field.value: any`
The field's current value, you can bind it with `value` prop on your inputs to sync both values. Don't use it with `v-model` otherwise your input will freeze.
`field.name: string`
The field name.
`field.onBlur: (e: Event | unknown) => void`
An array containing a few listeners for the `blur` event, it involves updating some meta information and triggers validation by default.
`field.onInput: (e: Event | unknown) => void`
An array containing a few listeners for the `input` event, it involves updating the field value and some meta information.
`field.onChange: (e: Event | unknown) => void`
An array containing a few listeners for the `change` event, it involves updating the field value and triggering validation.
#### `componentField`
Same as `field`, but provides value as `modelValue` to use with components
================================================
FILE: docs/src/pages/api/form.mdx
================================================
---
layout: ../../layouts/PageLayout.astro
title: Form
description: API reference for the Form component
menuTitle: ''
order: 2
---
import DocTip from '@/components/DocTip.vue';
import CodeTitle from '@/components/CodeTitle.vue';
# Form
## Form Component
The `` component is like its name, a simple HTML form but with a few adjustments and DX improvements, By default it will render a native HTML `form` element.
```vue-html
```
## Rendering Forms
Just like the `Field` component you can pass whatever you want to render in its place, for example a custom `v-form` component that is registered globally:
```vue-html
```
By default a `submit` and `reset` listeners are added to the rendered tag specified by the `as` prop.
For more complex form markup, you can render a `div` and inline your forms in the `Form` component's slots.
```vue-html
```
Notice the character-case difference between `Form` and `form`, the uppercased one is the component provided by vee-validate while the lowercased one is the native `form` element, you might run into issues when not using Vue compiler workflow like script tags. In these cases it is recommended to rename the `Form` component to something that will not conflict with native HTML.
```js
// Using named imports
import { Form as ValidationForm } from 'vee-validate';
const component = {
components: {
// If you have VeeValidate globally via a CDN script
ValidationForm: VeeValidate.Form,
},
};
```
Lastly, you can use the `Form` component slot props to access various aspects of the form state:
```vue-html
```
## Renderless Forms
While not recommended, you can make the `Form` component a renderless component by passing an empty string to the as prop, this is useful if you already need to add a form inside the scoped slot:
```vue-html
```
## API Reference
### Props
| Prop | Type | Default | Description |
| :--------------- | :----------------------------------- | :---------- | :----------------------------------------------------------------------------------------------------------- |
| as | `string` | `"form"` | The element to render as a root node |
| validationSchema | `Record` | `undefined` | An object describing a schema to validate fields with, can be a plain object or a `yup` object schema |
| initialValues | `Record` | `undefined` | Initial values to fill the fields with, when provided the fields will be validated on mounted |
| initialErrors | `Record` | `undefined` | Initial form errors to fill the fields with, the errors will be added when the form component is mounted |
| initialTouched | `Record` | `undefined` | Initial touched fields, the status will be applied when the form component is mounted |
| validateOnMount | `boolean` | `false` | If true, the fields currently present in the form will be validated when the `` component is mounted |
| keepValues | `boolean` | `false` | If the fields values should be deleted when they get unmounted, default is false |
| name | `string` | `"Form"` | The name of the form that is displayed in the devtools. |
### Slots
#### default
The default slot gives you access to the following props:
`errors: Record`
An object that maps field names to their error messages, it only takes the first error message of each field if multiple exists.
Here is an example of its shape:
```js
{
email: "this field must be a valid email",
password: "too short"
}
```
Any fields without error messages will not be included in the object. So you can safely iterate over it with `Object.keys()` knowing all the included fields are invalid.
`errorBag: Record`
An object that maps field names to all of their error messages.
Here is an example of its shape:
```js
{
email: ["this field is required", "this field must be a valid email"],
password: "too short"
}
```
Any fields without error messages will not be included in the object. So be careful when accessing the errors array for each field
`isSubmitting: boolean`
Indicates if the submission handler is still running, once it resolves/rejects it will be automatically set to `false` again.
`isValidating: boolean`
Indicates if the validate function is still running, once validate function is done it will be automatically set to `false` again.
`meta: FormMeta`
Contains an aggregated meta information/flags reflecting the state of all the fields inside the form.
```ts
interface FormMeta {
touched: boolean; // if at least one field is touched (was blurred)
dirty: boolean; // if at least one field is dirty (manipulated)
valid: boolean; // if all fields are valid
pending: boolean; // if at least one field is pending validation
initialValues?: Record; // a map of the form's initial values
}
```
`values: Record`
Contains the current form values
`setFieldError: (field: string, message: string) => void`
Sets a field's error message, useful for setting messages form an API or that are not available as a validation rule.
If you try to set an error for a field that doesn't exist, it will be added to the form's errors object and it will change the form's `valid` state
`setErrors: (fields: Record) => void`
Sets multiple fields error messages, uses `setFieldError` internally.
`setFieldValue: (field: string, value: any) => void`
Sets a field's value, if a field does not exist it will not be reflected in the `values` ref. This will trigger validation on the field whose value changed.
If you try to set a value for a field that doesn't exist, it will be added to the form's values object and will stay there until the next `resetForm` is called.
`setValues: (fields: Record) => void`
Sets all fields values, will trigger validation for the changed fields.
`setFieldTouched: (field: string, isTouched: boolean) => void`
Sets a field's `touched` meta flag, if you set it for a non-existing field it will have no effect.
`setTouched: (fields: Record) => void`
Sets multiple fields `touched` meta flag, does not validate.
`validate: () => Promise<{ valid: boolean; errors: Record}>`
Validates all the fields and populates the `errors` object, returns a promise that resolves to an object containing aggregated validation result of all fields.
`validateField: (field: string) => Promise<{ valid: boolean; errors: string[] }>`
Validates a specific field inside the form, returns a promise that resolves to an object containing the validation result.
`handleSubmit: (evt: Event, cb: (values: Record, ctx: SubmissionContext) => any) => Promise`
This can be used as an event handler for `submit` events, it accepts the event object and a callback function that will run if the form is valid. If an event object is provided, `preventDefault` and `stopPropagation` will be automatically called on it.
Note that this is only useful if you are not rendering a form tag on the `` component. By default the `Form` component uses this handler to handle any `submit` events.
`submitForm: (evt: Event) => void`
This function can also be used as an event handler for form `submit` event, the different that it will prevent the propagation and submission of the form as long as they are invalid. Once all the fields are valid it will submit the form with the native HTML behavior following the `form` element's `action` and `method` attributes.
This is useful if you plan to handle form submissions using a backend API like Laravel.
`submitCount: number`
The number of submission attempts by the user, it increments whenever `submitForm` or `handleSubmit` callback are called.
`handleReset: () => void`
Clears error messages, resets the meta state for all fields and reverts their values to their initial state and resets the `submitCount` to `0`. You can use this function as handler for the `reset` events on native form elements.
`resetForm: (state?: Partial) => void`
Clears error messages, resets the meta state for all fields and reverts their values to their initial state and resets the `submitCount`.
Accepts an optional object containing the new form state, useful if you need to reset the form values to different values other than their initial state.
This is the shape of the `state` object:
```ts
interface FormState {
// any error messages
errors: Record;
// touched meta flags
touched: Record;
// Form Values
values: Record;
// The form submit attempts count
submitCount: number;
}
```
In the following example the form is resetting the `email` field value to another value, this will change the field current value as well as it's initial value. Meaning any future calls of `resetForm` without arguments or `handleReset` will use `example@example.com` as their value. This also applies if fields are reset individually using `resetField` on either `useField` return value or `` component's slot props.
```vue-html
```
================================================
FILE: docs/src/pages/api/use-field-array.mdx
================================================
---
layout: ../../layouts/PageLayout.astro
title: useFieldArray
description: API reference for the useFieldArray composition API function
menuTitle: useFieldArray()
order: 7
---
import DocBadge from '@/components/DocBadge.vue';
import CodeTitle from '@/components/CodeTitle.vue';
# useFieldArray
`useFieldArray` is a custom composition API function that allows you to manage repeatable fields and forms entries and provides common operation helpers.
Basic usage:
```vue
```
## API Reference
The full signature of the `useFieldArray` function looks like this:
```ts
interface FieldEntry {
value: Ref;
key: string | number;
isFirst: boolean;
isLast: boolean;
}
interface FieldArrayContext {
fields: Ref[]>;
remove(idx: number): void;
replace(newArray: TValue[]): void;
update(idx: number, value: TValue): void;
push(value: TValue): void;
swap(indexA: number, indexB: number): void;
insert(idx: number, value: TValue): void;
prepend(value: TValue): void;
move(oldIdx: number, newIdx: number): void;
}
function useFieldArray: (arrayPath: string): FieldArrayContext;
```
### Composable API
The following sections documents each available property on the `useFieldArray` composable.
`fields: Ref[]>`
This is a **read-only** version of your array items, wrapped inside a `FieldArrayEntry` object which has the following interface:
```ts
interface FieldEntry {
// The actual value of the item as readonly, this is what exists in the form values
value: TValue;
// a value you can use as a key for iteration, automatically generated
key: string | number;
// true if this is the first array item
isFirst: boolean;
// true if this is the last array item
isLast: boolean;
}
```
```js
// call composable in component setup to get readable version of links array
const { fields } = useFieldArray('links');
```
`push(item: any)`
Adds an item to the end of the array.
```js
// get push function from composable in component setup
const { push } = useFieldArray('links');
// call push function within custom function
const myPushFunction = () => {
// adds a new item to the array
push({ url: '' });
};
```
`prepend(item: any)`
Adds an item to the start of the array.
```js
// get prepend function from composable in component setup
const { prepend } = useFieldArray('links');
// call prepend function within custom function
const myPrependFunction = () => {
// adds a new item to the array
prepend({ url: '' });
};
```
`remove(idx: number)`
Removes the item at the specified index from the array if it exists.
```js
// get remove function from composable in component setup
const { remove } = useFieldArray('links');
// call remove function within custom function
const myRemoveFunction = () => {
// removes the second item from the array
remove(1);
};
```
`swap(idxA: number, idxB: number)`
Swaps the items at the given indexes with each other. Both indexes must exist in the array or it won't have an effect.
```js
// get swap function from composable in component setup
const { swap } = useFieldArray('links');
// call swap function within custom function
const mySwapFunction = () => {
// Swaps the 4th item with the 5th
swap(3, 4);
};
```
`insert(idx: number, item: any)`
Adds an item at the specified index. If the specified index will place the item out of bounds (i.e: larger than length) the operation will be ignored, you still can add items as the last item of the array.
```js
// get insert function from composable in component setup
const { insert } = useFieldArray('links');
// call insert function within custom function
const myInsertFunction = () => {
// inserts a new item to the array at the second index
insert(1, { url: '' });
};
```
`update(idx: number, value: any)`
Updates the value at the specified index, note that it doesn't merge the values if they are objects. If the specified index is outside the array boundary the operation will be ignored.
```js
// get update function from composable in component setup
const { update } = useFieldArray('links');
// call update function within custom function
const myUpdateFunction = () => {
// updates the 2nd item value
update(1, { url: '' });
};
```
`replace(items: any[])`
Replaces the entire array of fields.
```js
// get replace function from composable in component setup
const { replace } = useFieldArray('links');
// call replace function within custom function
const myReplaceFunction = () => {
// replace the entire array with these items
replace([{ url: 'https://google.com' }, { url: 'https://vuejs.org' }]);
};
```
`move(oldIdx:number, newIdx: number)`
Moves an array item to a different position within the array.
```js
// get move function from composable in component setup
const { move } = useFieldArray('links');
// call move function within custom function
const myMoveFunction = () => {
// move array item to a different position
move(2, 1);
};
```
================================================
FILE: docs/src/pages/api/use-field.mdx
================================================
---
layout: ../../layouts/PageLayout.astro
title: useField
description: API reference for the useField composition API function
menuTitle: useField()
order: 5
---
import DocTip from '@/components/DocTip.vue';
import CodeTitle from '@/components/CodeTitle.vue';
# useField
`useField` is a custom composition API function that allows you to create data models that's automatically validated that you can then use to build your own custom input components with validation capabilities. It is very useful if you plan to build a UI component library that needs to have validation capabilities. In other words it acts as a primitive to allow you to compose validation logic into your components.
The most basic usage looks like this:
```vue
{{ errorMessage }}
```
Whenever the `value` ref is updated it will be validated and the `errorMessage` ref will be automatically filled with the first error message. Usually you would bind the `value` ref to your inputs using `v-model` or any other means and whenever you want to validate your field you update the `value` binding with the new value.
Additionally you can use `yup` as a validator:
```vue
```
You are responsible for when the field validates, blurs or when its value changes. This gives you greater control over the `Field` component which may include or implement sensible defaults for most common use cases.
## Usage with TypeScript
You can use `useField` with typescript and type the field's value type to ensure safety when manipulating it's value. The `useField` function is a generic function that receives the value type and applies it on the various interactions you have with its API.
```ts
const { value, resetField } = useField('email', yup.string().email());
value.value = 1; // ⛔️ Error
value.value = 'test@example.com'; // ✅
resetField({
value: 1, // ⛔️ Error
});
resetField({
value: 'test@example.com', // ✅
});
```
The validation rules can be either a string, object, function or a yup schema:
```js
// Globally defined rules with `defineRule`, Laravel-like syntax
useField('password', 'required|min:8');
// Globally defined rules object
useField('password', { required: true, min: 8 });
// Simple validation function
useField('password', value => {
if (!value) {
return 'password is required';
}
if (value.length < 8) {
return 'password must be at least 8 characters long';
}
return true;
});
// Yup validation
useField('password', yup.string().required().min(8));
```
## API Reference
### Composable API
The following sections documents each available property on the `useField` composable.
`name: string | Ref | () => string`
The field name, it can be a string or a reactive ref to a string or a getter than returns a string. It is used to identify the field and specify its value path.
`value: Ref`
A reactive reference to the field's current value, can be changed and will trigger validation by default unless disabled by the `validateOnValueUpdate` option.
```js
const { value } = useField('field', value => !!value);
value.value = 'hello world'; // sets the value and validates the field
```
You can also bind it with `v-model` to get two-way value binding with validation.
`setValue: Ref`
A method to update the fields value.
```js
const { setValue } = useField('field', value => !!value);
setValue('hello world') // sets the value and validates the field
```
`meta: FieldMeta`
Contains useful information/flags about the field status, should be treated as **read only**.
```ts
interface FieldMeta {
touched: boolean; // if the field has been blurred (via handleBlur)
dirty: boolean; // if the field has been manipulated (via handleChange)
valid: boolean; // if the field doesn't have any errors
pending: boolean; // if validation is in progress
initialValue?: any; // the field's initial value
}
```
The `valid` flag on the meta object can be tricky, because by default it stars off with `true` for a few moments, only then it is updated to its proper state.
Combining your `valid` flag checks with `dirty` will yield the expected result based on user interaction.
**usage**
```js
const { meta } = useField('field', value => !!value);
meta; // { valid: true, dirty: true, .... }
```
`errors: Ref`
A reactive reference containing all error messages for the field, should be treated as **read only**
```js
const { errors } = useField('field', value => !!value);
errors.value; // ['field is not valid']
```
`errorMessage: ComputedRef`
A computed reference that returns the first error in the `errors` array, a handy shortcut to display error messages
```js
const { errorMessage } = useField('field', value => !!value);
errorMessage.value; // 'field is not valid' or undefined
```
`resetField: (state?: Partial) => void`
Resets the field's validation state, by default it reverts all `meta` object to their default values and clears out the error messages. It also updates the field value to its initial value without validating them.
```js
const { resetField } = useField('field', value => !!value);
// reset the field meta and its initial value and clears errors
resetField();
// reset the meta state, clears errors and updates the field value and its initial value
resetField({
value: 'new value',
});
// resets the meta state, resets the field to its initial value and sets the errors
resetField({
errors: ['bad field'],
});
// Marks the field as touched, while resetting its value and errors.
resetField({
touched: true,
});
// Changes the meta, initial and current values and sets the errors for the field
resetField({
value: 'new value',
touched: true,
errors: ['bad field'],
});
```
Note that it is unsafe to use this function as an event handler directly, check the following snippet:
```vue-html
```
You can also use `handleReset` which is a safe alternative for `resetField`.
`setErrors: (errors: string | string[]) => void`
Sets then field errors, you can pass a single message string or an array of errors.
```js
const { setErrors } = useField('field', value => !!value);
// Sets the errors to a single error message
setErrors('field is required');
// sets the errors to multiple error messages
setErrors(['field is required', 'field must be valid']);
// clears the errors
setErrors([]);
```
`handleReset: () => void`
Similar to `resetField` but it doesn't accept any arguments and can be safely used as an event handler. The values won't be validated after reset.
```js
const { handleReset } = useField('field', value => !!value);
// reset the field validation state and its initial value
handleReset();
```
`validate: () => Promise<{ errors: string[] }>`
Validates the field's current value and returns a promise that resolves with an object containing the error messages emitted by the various rule(s).
```js
const { validate } = useField('field', value => !!value);
// trigger validation
await validate();
```
`handleChange: (evt: Event | any) => void`
Updates the field value, and validates the field. Can be used as an event handler to bind on the field. If the passed argument isn't an event object it will be used as the new value for that field.
It sets the `dirty` meta flag to `true`
```vue
```
`handleBlur: (evt: Event | any) => void`
Sets the `touched` meta flag to `true`
```vue
```
`setTouched: (isTouched: boolean) => void`
Sets the `touched` meta flag for this field, useful to create your own `blur` handlers
```js
const { setTouched } = useField('field', value => !!value);
// mark the field as touched
setTouched(true);
```
`checked: ComputedRef | undefined`
A computed property that indicates if the field should be checked or unchecked, only available if `type=checkbox` or `type=radio` in field options. Useful if you are creating [custom checkboxes](/examples/custom-checkboxes).
```js
const { checked } = useField('field', ..., {
type: 'checkbox',
valueProp: 'Checkbox value'
});
checked.value; // true or false
```
For more information on how you might use the `checked` property, check the [custom checkboxes example](/examples/custom-checkboxes).
## Additional options
To pass additional configuration to your fields you can use more options.
```vue
{{ errorMessage }}
```
| Field options |
| -------------------------------------- |
| `type` |
| `label` |
| `initialValue` |
| `validateOnMount` |
| `bails ` |
| `standalone` |
| `validateOnValueUpdate` |
| `keepValueOnUnmount` |
| `syncVModel` |
| `checkedValue` (checkbox/radio only) |
| `uncheckedValue` (checkbox/radio only) |
================================================
FILE: docs/src/pages/api/use-form.mdx
================================================
---
layout: ../../layouts/PageLayout.astro
title: useForm
description: API reference for the useForm composition API function
menuTitle: useForm()
order: 6
---
import DocTip from '@/components/DocTip.vue';
import CodeTitle from '@/components/CodeTitle.vue';
import DocBadge from '@/components/DocBadge.vue';
# useForm
`useForm` is a custom composition API function that allows you to group fields created by `useField` and aggregates their state. It should be used to create logical forms or custom form components similar to the `` component which is just a consumer of `useForm`.
Note that you can only have one `useForm` per component. See this issue: https://github.com/logaretm/vee-validate/issues/4550
## Field Types
The `useForm` function has field typing capabilities if you need it, getting type information for your fields and their values can be very powerful when building complex forms.
By unlocking the field type you automatically get more strict information for the various properties/methods exposed by `useForm` like `setErrors` and `setTouched`. There are two ways you can get the advanced typing information for your fields, the first is to provide a generic type to `useForm`.
```ts
import { useForm } from 'vee-validate';
interface LoginForm {
email: string;
password: string;
}
// in your setup
const { errors } = useForm();
```
Or simply provide initial values to `useForm` and it will automatically pick up the type of `initialValues` and use it for the field types.
```ts
import { useForm } from 'vee-validate';
const { errors, setErrors, setFieldValue } = useForm({
initialValues: {
email: '',
password: '',
},
});
```
Alternatively, you can use a [standard schema](https://standardschema.dev/) to infer the form types from the validation schema if you are using yup or zod.
Whichever approach you prefer, you get full type information for your fields for all the functions exposed by `useForm`, here are a few examples.
```ts
import { useForm } from 'vee-validate';
interface LoginForm {
email: string;
password: string;
}
// in your setup
const { errors, setErrors, setFieldValue } = useForm();
errors.value; // typed as { email?: string; password?: string }
setErrors({
email: 'This field is invalid', // auto-complete for `email` and `password`
});
setFieldValue('email', 'example@gmail.com'); // auto-complete for the field name and its value type
```
For example if you were to do this in the previous example:
```ts
setFieldValue('age', 5); // ⛔️ TypeScript error
setFieldValue('email', 5); // ⛔️ TypeScript error
```
It will error out because `age` is not defined in the `LoginForm` type you defined. The second line errors out because the `email` field is typed as a `string`.
## API Reference
### Arguments
`validationSchema?: any`
Enables form-level validation, uses the specified schema to validate the fields. The schema can be either valid vee-validate global validators or functions or a yup object schema.
`initialValues?: Record`
The initial values for the form.
```js
const { ... } = useForm({
initialValues: {
email: 'example@gmail.com',
password: 'p@$$w0rd',
}
});
```
`initialErrors?: Record`
The initial errors for the fields, useful for non hydrated SSR applications like Laravel, errors are applied on mounted.
```js
const { ... } = useForm({
initialErrors: {
email: 'This email is invalid',
password: 'Password too short',
}
});
```
`initialTouched?: Record`
The initial touched status for the form fields, applied on mounted.
```js
const { ... } = useForm({
initialTouched: {
email: true, // touched
password: false, // non-touched
}
});
```
`validateOnMount?: boolean`
If true, it will trigger validation for all fields once the form component is mounted.
`name?: string`
If set, it will be used as the form's name in the devtools.
```js
const { ... } = useForm({
name: 'LoginForm', // Defaults to "Form"
});
```
### Composable API
The following sections documents each available property on the `useForm` composable.
`errors: Ref>`
An object that maps field names to their error messages, it only takes the first error message of each field if multiple exists.
```js
const { errors } = useForm();
errors.value; // access the errors value
```
`errorBag: Ref>`
An object that maps field names to all of their error messages.
```js
const { errorBag } = useForm();
errorBag.value.email; // email field errors
```
Here is an example of its shape:
```js
{
email: ["this field is required", "this field must be a valid email"],
password: "too short"
}
```
Any fields without error messages will not be included in the object. So you can safely iterate over it with `Object.keys()` knowing all the included fields are invalid.
`isSubmitting: Ref`
Indicates if the submission handler is still running, once it resolves/rejects it will be automatically set to false again.
```js
const { isSubmitting } = useForm();
isSubmitting.value; // true or false
```
`isValidating: Ref`
Indicates if the validate function is still running, once validate function is done it will be automatically set to `false` again.
```js
const { isValidating } = useForm();
isValidating.value; // true or false
```
`meta: ComputedRef`
A computed property that contains an aggregated meta information/flags reflecting the state of all the fields inside the form.
```ts
interface FormMeta {
touched: boolean; // if at least one field is touched (was blurred)
dirty: boolean; // if at least one field is dirty (manipulated)
valid: boolean; // if the form doesn't have any error messages
pending: boolean; // if at least one field is pending validation
initialValues?: Record; // a map of the form's initial values
}
```
**usage**
```js
const { meta } = useForm();
meta.value; // { valid: false, invalid: true, dirty: true, .... }
```
`values: Record`
A reactive property that contains the current form values, you should not try to mutate it directly.
```js
const { values } = useForm();
values; // { email: 'something@gmail.com', .... }
```
`setFieldError: (field: string, message: string | undefined) => void`
Sets a field's error message, useful for setting messages form an API or that are not available as a validation rule. Setting the message to `undefined` or an empty string clears the errors and marks the field as valid.
```js
const { setFieldError } = useForm();
setFieldError('email', 'this email is already taken');
// Mark field as valid
setFieldError('email', undefined);
```
If you try to set an error for a field that doesn't exist, it will be added to the form's errors object and it will change the form's `valid` state
`setErrors: (fields: Record) => void`
Sets multiple fields error messages, uses `setFieldError` internally.
```js
const { setErrors } = useForm();
setErrors({
email: 'this email is already taken',
password: 'someone already has this password 🤪',
firstName: undefined, // clears errors and marks the field as valid
});
```
Any missing fields you didn't pass to `setErrors` will be unaffected and their state will not change
`setFieldValue: (field: string, value: any) => void`
Sets a field's value, if a field does not exist it will not be reflected in the `values` ref. This will trigger validation on the field whose value changed.
```js
const { setFieldValue } = useForm();
setFieldValue('email', 'example@gmail.com');
```
If you try to set a value for a field that doesn't exist, it will be added to the form's values object and will stay there until the next `resetForm` is called.
`setValues: (fields: Record) => void`
Sets all fields values, will trigger validation for the changed fields.
```js
const { setValues } = useForm();
setValues({
email: 'example@gmail.com',
password: 'p@a$$W0rD',
});
```
`setFieldTouched: (field: string, isTouched: boolean) => void`
Sets a field's `touched` meta flag, if you set it for a non-existing field it will have no effect.
```js
const { setFieldTouched } = useForm();
setFieldTouched('email', true);
```
`setTouched: (fields: Record) => void`
Sets multiple fields `touched` meta flag, does not validate.
```js
const { setTouched } = useForm();
setTouched({
email: true,
password: false,
});
```
`validate: () => Promise<{ valid: boolean; errors: Record}>`
Validates all the fields and populates the `errors` object, returns a promise that resolves to an object containing aggregated validation result of all fields.
```js
const { validate } = useForm();
const { valid, errors } = await validate();
```
`validateField: (field: string) => Promise<{ valid: boolean; errors: string[] }>`
Validates a specific field inside the form, returns a promise that resolves to an object containing the validation result.
```js
const { validateField } = useForm();
const { valid, errors } = await validateField('email');
```
`handleSubmit: (cb: SubmissionHandler) => (evt?: Event) => Promise`
This is a higher order function used to create `submit` event handlers, You shouldn't use it as a handler for the events directly but rather use it to create those handlers.
The handlers created using this function will automatically prevent form submission and stop the propagation of the submit event.
It accepts a function which runs after validating the form and if all fields are valid. The callback you pass will receive the form values as the first argument, which is an object containing the fields' values.
```vue
```
For advanced forms, you may need to trigger various actions on the form in the `submit` handler. Your callback receives a `FormActions` object as part of the second argument along with the event object that triggered the submission if available.
```js
const { handleSubmit } = useForm();
const onSubmit = handleSubmit((values, actions) => {
// Send data to API
alert(JSON.stringify(values, null, 2));
// the form object contains useful methods
// set a single field value
actions.setFieldValue('field', 'hello');
// set multiple fields values
actions.setValues({ email: 'value', password: 'hi' });
// set a single field error
actions.setFieldError('field', 'this field is bad');
// set multiple fields errors
actions.setErrors({ email: 'bad email', password: 'bad password' });
// reset the form
actions.resetForm();
});
```
`handleSubmit` contains a `withControlled` function that you can use to only submit fields controlled by `useField` or `useFieldModel`. Read the [guide](/guide/composition-api/handling-forms) for more information.
```vue
```
You can use `handleSubmit` to submit **virtual forms** that may use `form` elements or not. As you may have noticed the snippet above doesn't really care if you are using forms or not.
`submitForm: (evt: Event) => void`
Unlike `handleSubmit` this function can be used as an event handler for form `submit` event, it will prevent the propagation and submission of the forms using it as long as they are invalid. Once all the fields are valid it will submit the form with the native HTML behavior following the `form` element's `action` and `method` attributes.
This is useful if you plan to handle form submissions using a backend API like Laravel or whatever.
```vue
```
`submitCount: number`
The number of submission attempts by the user, it increments whenever `submitForm` or `handleSubmit` callback are called.
`resetForm: (state?: Partial, opts?: ResetFormOpts) => void`
Clears error messages, resets the meta state for all fields and reverts their values to their initial state as well as the `submitCount` state. Accepts an optional object containing the new form state, useful if you need to reset the form values to different values other than their initial state.
This is the `FormState` interface:
```ts
type TouchedFlags = { [k: string]: boolean };
interface FormState {
// any error messages
errors: Record;
// touched meta flags
touched: TouchedFlags;
// Form Values
values: Record;
// The form submit attempts count
submitCount: number;
}
```
In this example, the `resetForm` function is updating the fields current values to the ones provided, these values will be used as the new initial values for future `resetForm` or `handleReset` calls. This also applies if the `Field` component or `useField` used their individual `resetField` function.
```js
const { resetForm } = useForm();
// ...
function onSubmit(values) {
// send values to the API
// ...
// Reset the form values
resetForm({
values: {
firstName: '',
lastName: '',
email: '',
password: '',
},
});
}
```
By default `resetForm` merges the previous initial values with the new one provided, meaning only the provided ones will be overwritten. You can overwrite all the fields by passing `force: true` in the second argument.
```js
const { values, resetForm } = useForm({
initialValues: { fname: '123', lname: '456' },
});
// values: { fname: 'test', lname: '456' }
resetForm({ values: { fname: 'test' } });
// values: { fname: 'test' }
resetForm({ values: { fname: 'test' } }, { force: true });
```
`handleReset: () => void`
Clears error messages, resets the meta state for all fields and reverts their values to their initial state as well as the `submitCount` state. you can use this function as handler for the `reset` events on native form elements.
```vue
```
`useFieldModel`
This is deprecated, please use `defineField` instead.
This creates a bindable two-way model value for the specified fields, there are a couple of signatures for `useFieldModel`. Must be called in the `setup` function.
`useFieldModel` accepts either a single field path or multiple via an array. You can use either root field paths or nested paths like `some.user.path` with dot notation.
```vue
{{ errors.email }}{{ errors.password }}
```
`defineInputBinds`
This is deprecated, please use `defineField` instead.
This creates a bindable object for the specified field. The bindable object only works with native HTML input elements, for components use `defineComponentBinds` instead.
The `defineInputBinds` must be called in the `setup` function.
`defineInputBinds` accepts a single field path, You can use either root field paths or nested paths like `some.user.path` with dot notation.
```vue
{{ errors.email }}{{ errors.password }}
```
`defineComponentBinds`
This is deprecated, please use `defineField` instead.
This creates a bindable object for the specified field. The bindable object only works with components, for native HTML input elements use `defineInputBinds` instead.
The `defineComponentBinds` must be called in the `setup` function.
`defineComponentBinds` accepts a single field path, You can use either root field paths or nested paths like `some.user.path` with dot notation.
```vue
{{ errors.email }}{{ errors.password }}
```
`defineField`
This function returns a model and a props/attributes pair.
The `defineField` must be called in the `setup` function.
`defineField` accepts a single field path, You can use either root field paths or nested paths like `some.user.path` with dot notation.
```vue
{{ errors.email }}{{ errors.password }}
```
This function also works with custom components.
You can configure the props/attributes that are bound to the component by passing a second argument to `defineField`. You can use this configuration to adjust the `field` validation behavior and more with the individual elements you are using or the component library of your choice. Check the [UI library examples](/examples/ui-libraries) for live examples.
```ts
const [field, props] = defineField('field', {
// A getter that computes and adds any additional props to the component
// It receives the current field state as an argument
props(state) {
// This is just an example, by default this is an empty object
return {
'aria-invalid': state.errors.length > 0 ? 'true' : 'false',
};
},
// A label for the field, only used with global validation rules
label: 'a label',
// Validates when `blur` event is emitted from the element/component
validateOnBlur: true,
// Validates when `change` event is emitted from the element/component
validateOnChange: true,
// Validates when `input` event is emitted from the element/component
validateOnInput: false,
// Validates when the returned model value changes
validateOnModelUpdate: true,
});
```
You can also have a lazy configuration by passing a function that returns the configuration object. The only difference is `props` is now a plain object instead of a getter function.
This means you can change any of the configuration based on the field state:
```ts
const [field, props] = defineField('field', state => {
return {
// A getter that computes and adds any additional props to the component
props: {
// This is just an example, by default this is an empty object
'aria-invalid': state.errors.length > 0 ? 'true' : 'false',
},
// Validates when `blur` event is emitted from the element/component
validateOnBlur: true,
// Validates when `change` event is emitted from the element/component
validateOnChange: true,
// Validates when `input` event is emitted from the element/component
validateOnInput: false,
// Validates when the returned model value changes
validateOnModelUpdate: true,
};
});
```
================================================
FILE: docs/src/pages/examples/array-fields.mdx
================================================
---
layout: ../../layouts/PageLayout.astro
title: Array Fields
description: How to implement array fields in vee-validate
order: 5
---
import LiveExample from '@/components/LiveExample.vue';
# Array Fields
This example shows how to implement array fields in vee-validate
================================================
FILE: docs/src/pages/examples/async-validation.mdx
================================================
---
layout: ../../layouts/PageLayout.astro
title: Async Validation
description: Using async validation with vee-validate
order: 3
---
import LiveExample from '@/components/LiveExample.vue';
# Async Validation
This is an example of field that uses an async rule to check if an email is available.
================================================
FILE: docs/src/pages/examples/checkboxes-and-radio.mdx
================================================
---
layout: ../../layouts/PageLayout.astro
title: Checkbox and Radio Inputs
description: Validating checkboxes and Radio inputs
order: 1
---
import DocTip from '@/components/DocTip.vue';
import LiveExample from '@/components/LiveExample.vue';
# Checkbox and Radio Inputs
The documentation has so far avoided using `type="radio"` and `type="checkbox"` inputs because of their complex nature, however vee-validate supports both HTML checkboxes and radio inputs as well as your custom components that act as such (with caveats).
The only requirements are that the fields:
- Must be inside a `Form` component or a [derivative (using useForm)](/api/use-form#creating-custom-form-components)
- Must Have the same `name` prop
- Should have a `type` attribute
When using `Field` slot props with checkbox/radio components, you still need to provide the `type` and `value` props to the `Field` node itself.
```vue-html
```
The same caveat applies if you are rendering another component with `as` prop:
```vue-html
```
## Validating Radio Inputs
vee-validate handles radio input groups as long as they have the `type="radio"` and the same `name` prop value. The selected value will be present in the `values` object.
## Validating Checkbox Inputs
vee-validate handles checkboxes as long as they have the `type="checkbox"` prop and the same `name` prop value. The selected values will be collected in an array similar to what `v-model` does.
If there is only one checkbox then its value will be directly assigned in the `values` object without binding it in an array.
================================================
FILE: docs/src/pages/examples/cross-field-validation.mdx
================================================
---
layout: ../../layouts/PageLayout.astro
title: Cross-Field Validation
description: Validating input values depending on other inputs' values
order: 4
---
import LiveExample from '@/components/LiveExample.vue';
# Cross-Field Validation
This example shows how to create a password-confirmation-like rules using either `yup` or global validators.
================================================
FILE: docs/src/pages/examples/custom-checkboxes.mdx
================================================
---
layout: ../../layouts/PageLayout.astro
title: Custom Checkboxes
description: Creating validatable checkbox inputs
order: 6
---
import DocTip from '@/components/DocTip.vue';
import LiveExample from '@/components/LiveExample.vue';
# Custom Checkboxes
Checkboxes are more complex than regular text inputs, because there is always two states to keep track of which can be confusing at first. Mainly you should keep track of:
- Each individual input's value
- Which inputs are current selected
To make this easier, remember that native checkboxes behave as a group while each input maintains it's own value. Then a checkbox said to be checked when either:
- It's value is the one currently selected
- It's value is included in the ones selected
This is because of the nature of checkboxes behaving as **"multi-value"** form inputs, so you need to keep track of each input's value and the currently selected one(s).
With all of that in mind, vee-validate offers simple abstractions for checkboxes. You can build your own checkboxes with vee-validate's `useField` function which gives you the full capabilities of validation in a composable fashion.
Because `useField` isn't aware of what kind of input will be composed with it, you will need to specify that the input is of type `checkbox` and pass a `checkedValue` as well which represents that single field's value. By doing so, you gain access to `checked` prop which tells you if the checkbox should be selected.
```js
import { useField } from 'vee-validate';
export default {
props: {
// The group's value
modelValue: {
type: null,
},
// Field's own value
value: {
type: null,
},
name: {
type: String,
},
rules: {
type: String,
default: undefined,
},
},
setup(props) {
// We pass a function to make sure the name stays reactive
const { checked, handleChange } = useField(() => props.name, props.rules, {
// 👇 These are important
type: 'checkbox',
checkedValue: props.value,
});
// select/unselect the input
handleChange(props.value);
return {
checked, // readonly
handleChange,
};
},
};
```
vee-validate handles some of the complexities of the checkbox inputs nature, by default if a checkbox field is registered it will be treated as a single input until another checkbox with the same name is registered. Then they will be treated as a group, and their values will affect the group value when they are selected or not.
Here is a live example of a custom checkbox input:
You can also specify a custom `uncheckedValue` which sets the input value to when it is unchecked.
```js
const { checked, handleChange } = useField('toa', undefined, {
// Will make the checkbox set its value to true/false if it was checked or not
type: 'checkbox',
checkedValue: true,
uncheckedValue: false,
});
```
================================================
FILE: docs/src/pages/examples/custom-inputs.mdx
================================================
---
layout: ../../layouts/PageLayout.astro
title: Custom Inputs
description: Building custom inputs with useField()
order: 2
---
import LiveExample from '@/components/LiveExample.vue';
# Custom Inputs
More often than not, you will have complex requirements for your inputs. Like a custom design, multiple UI states, validation and more. You can easily build your custom components with `useField()` composable function. While it is possible to build your inputs with `` component it is not recommended as you won't have access to many of the underlying features to manage your UI state and you would rely on scoped slot props which is only available in the template.
`useField` allows you to hook into the many underlying features of the `Field` component in a composable manner that you can easily integrate it in your UI, and on top of that your custom components will work seamlessly with `` component or `useForm` without any intervention on your part.
In the following example we have a complex `TextInput` component that we use for many types of fields.
================================================
FILE: docs/src/pages/examples/dynamic-validation-triggers.mdx
================================================
---
layout: ../../layouts/PageLayout.astro
title: Dynamic validation triggers
description: Dynamic interaction for your inputs
order: 11
---
import LiveExample from '@/components/LiveExample.vue';
# Dynamic validation triggers
In previous versions of vee-validate you could configure what events trigger the validation based on the field state. This feature was called "interaction modes". In vee-validate v4 this feature was removed because it is now possible to implement it with the composition API.
This example should help you figure out how to migrate this feature from older vee-validate versions.
================================================
FILE: docs/src/pages/examples/multistep-form-wizard.mdx
================================================
---
layout: ../../layouts/PageLayout.astro
title: Multi-step Form Wizard
description: a multi-step form wizard
order: 7
---
import LiveExample from '@/components/LiveExample.vue';
# Multi-step Form Wizard
These examples showcases a simple multi-step form (form wizard), with `next` and `previous` step navigation.
## Higher Order Components
This example uses the higher-order components only.
## Composition API
This example uses the composition API to construct a system of `` and `` components to make building form steps easier.
================================================
FILE: docs/src/pages/examples/ui-libraries.mdx
================================================
---
layout: ../../layouts/PageLayout.astro
title: Popular UI Libraries
description: Validating popular Vue.js UI libraries with examples
order: 10
---
import LiveExample from '@/components/LiveExample.vue';
# UI Libraries Examples
Most popular Vue.js UI libraries come with their own built-in form logic and some may tackle a lot of what vee-validate tackles. If you find yourself not satisfied with said library's logic, you can add vee-validate power up these components.
vee-validate is UI-agnostic, it doesn't offer any special treatment for the elements/components as long as they emit the right events.
Integrating vee-validate can be different for each UI library, it mostly depends on the library's ability to outsource the form logic to 3rd party logic and how it tracks the form field values.
In the next few examples you will find examples on how to do that in various ways with the most popular Vue.js libraries in no particular order.
## Shadcn Vue
> Beautifully designed components that you can copy and paste into your apps. Accessible. Customizable. Open Source.
ShadCN has an official guide on how to use vee-validate with their components, check it out [here](https://www.shadcn-vue.com/docs/components/form).
## Vuetify
> [Vuetify](https://vuetifyjs.com/en/) is a no design skills required UI Library with beautifully handcrafted Vue Components.
Check their [official example here](https://vuetifyjs.com/en/components/forms/#vee-validate).
## PrimeVue
> [PrimeVue](https://primevue.org/) is a rich set of open source UI Components for Vue.
Check their [official example here](https://primevue.org/inputtext/#veevalidate).
## Quasar
[Quasar framework](https://quasar.dev/) aims to:
> Effortlessly build high-performance & high-quality Vue 3 user interfaces in record time
## Element Plus
> [Element Plus](https://element-plus.org/#/en-US), a Vue 3.0 based component library for developers, designers and product managers
## Headless UI
> [Headless UI](https://headlessui.dev/), a completely unstyled, fully accessible UI components, designed to integrate beautifully with Tailwind CSS.
## Ionic Framework
> [Ionic Framework](https://ionicframework.com/), An open source mobile toolkit for building high quality, cross-platform native and web app experiences.
This example is originally forked from another example created by [Aaron Saunders](https://twitter.com/aaronksaunders).
## Ant Design
> [Ant Design](https://next.antdv.com/) provides plenty of UI components to enrich your web applications, and we will improve components experience consistently.
## Nuxt UI
> [Nuxt UI](https://ui.nuxtlabs.com/) is a Fully styled and customizable components for Nuxt.js
## Naive UI
> [Naïve UI](https://www.naiveui.com/en-US/os-theme) Fairly Complete, Theme Customizable, Uses TypeScript, Fast, Kinda Interesting
## Bootstrap Vue
> With [BootstrapVue](https://bootstrap-vue.org/) you can build responsive, mobile-first, and ARIA accessible projects on the web using Vue.js and the world's most popular front-end CSS library
## Request a UI library
Can't find your favorite UI library here? You can request adding an example for it by creating an [issue here](https://github.com/logaretm/vee-validate/issues/new/choose) and we will consider adding it here.
================================================
FILE: docs/src/pages/examples/using-stores.mdx
================================================
---
layout: ../../layouts/PageLayout.astro
title: State Stores
description: using vee-validate with state stores
order: 8
new: true
---
import DocTip from '@/components/DocTip.vue';
import LiveExample from '@/components/LiveExample.vue';
# Stores
If you want to integrate vee-validate with state management solutions you can do that with the composition API.
## Pinia
[Pinia](https://pinia.esm.dev/) is a data store for Vue.js and it is the recommended solution to your Vue.js state management.
The example integrates a form state into the store by utilizing a setup function when defining a store. This makes vee-validate act as a state provider for the form where the form values become your store state and submit function becomes your store action.
Using `useForm` inside Pinia stores may cause unwanted behavior as lifecycle hooks only execute against the component that first initialized the store.
================================================
FILE: docs/src/pages/examples/value-formatting.mdx
================================================
---
layout: ../../layouts/PageLayout.astro
title: Value formatting and Masks
description: using vee-validate with masked and formatted inputs
order: 9
new: true
---
import LiveExample from '@/components/LiveExample.vue';
# Value Formatting and Masks
Some inputs may have a mask applied to them, that is their value is displayed in a different way than the actual value to make it more friendly towards the user.
For example, a currency input could insert a thousand separator to make it easier for the user to enter and read large numbers.
```sh
# hard to read
10000000
# Much easier
10,000,000
```
It can be confusing as to how would you run your numeric validation rules on such inputs. The following examples show you how to handle such inputs by separating the "display value" from the actual value.
## Currency Format Example
The following example integrates [`vue-currency-input`](https://github.com/dm4t2/vue-currency-input) using the composition API. While it is still possible to do it with the `` component, it is significantly easier to work with the composition API in this case.
The main key to getting this right is to sync the value in multiple formats, the formatted one, and the non-formatted value.
Ideally, vee-validate should be synced with the non-formatted one, you can do this by updating the value manually using `setValue` or `handleChange`.
================================================
FILE: docs/src/pages/guide/components/handling-forms.mdx
================================================
---
layout: ../../../layouts/PageLayout.astro
title: Handling Forms
description: Handling form state and submissions
order: 3
next:
path: guide/components/nested-objects-and-arrays
title: Nested Objects and Arrays
description: Structuring forms in nested paths in objects or arrays
---
import DocTip from '@/components/DocTip.vue';
# Handling Forms
vee-validate offers many helpers to handle form submissions, resets, and DX to make your forms much easier to reason about and less of a burden to maintain. The `Form` component handles the following form cases:
- Submitting forms with JavaScript listeners (AJAX)
- Submitting forms using the classic/native approach (page reload)
- Handling form resets
## Form Values
So far you probably noticed we didn't use `v-model` once in the examples. This is because in most cases you don't need the model values until you submit them to your API or not at all if you are submitting an HTML form without JavaScript.
Having to create models just to be able to reference them later is redundant and vee-validate goes around this by creating an internal model for the `` field component instances and tracks them and keeps them in sync with the input. You can still use `v-model` if you need it but vee-validate doesn't require it.
You may access your form's values using the `values` scoped slot prop on the `Form` component:
```vue
```
You will rarely need to access the form values inside the template, but it is there if you ever need it. What's interesting is that vee-validate follows the assumption that most likely you will need the form values at the submission phase.
So if you were to add a `submit` handler on the `` component, vee-validate will automatically pass the form values to your handler as the first argument.
```vue
```
## Handling Submissions
vee-validate exposes useful defaults to help you handle form submissions whether you submit them using JavaScript or native HTML submissions, in most cases, you would like to make sure all your fields are valid before you submit the form, this is done for you by default.
Consider the last example, if you tried submitting the form, it won't be submitted unless all fields are valid. When rendering a form using the `as` prop, vee-validate will automatically listen for the `submit` event and prevent the execution of any `submit` listener you may have on the form.
If you have a `submit` listener on the `Form` component, vee-validate assumes you will be handling submissions via JavaScript (AJAX) and automatically calls `event.preventDefault()` for you and once the form is finished validating and turned out to be valid it will pass all the values of the `` components.
But in the case when you don't have a `submit` listener on your form, vee-validate assumes that the form will be submitted using the native HTML submission that causes the page to "reload". However vee-validate will make sure the form is not submitted unless all fields are valid, here is an example:
```vue-html
```
## Manually Handling Submissions
If you have complex markup requirements in your forms, you can use any of those `` component slot props:
- `handleSubmit`: automatically prevents native submission at all times, use for AJAX submissions
- `submitForm`: prevents native submissions as long as the form is invalid, use for native submissions
- `validate`: triggers validation on all fields belonging to the form
### Using handleSubmit
The `handleSubmit` slot prop is probably the most common method you will use to handle form submissions manually, it accepts a callback that will be executed with the form values if the form is valid.
```vue
```
### Using submitForm
Alternatively if you plan to submit forms natively which will cause a page "reload" then use `submitForm` as an event handler:
```vue
```
This will prevent submitting the form until all fields are valid.
### Using validate()
You can validate the form without submissions using the `validate()` slot prop function:
```vue-html
```
That form doesn't render a `form` tag, so vee-validate doesn't handle submissions for that group of fields. But you can still validate them using the `validate` function present on the `Form` component slot props.
## Submission Progress
Quite often you need to show your users a submission indicator, or you might want to disable the submit button entirely until the submission attempt is done. The `Form` component offers an `isSubmitting` slot prop that you can use to show such UI indicators.
The `isSubmitting` state will be set to `true` once the validation of the form starts (as a result of a submit event) and will keep track of the submission handler you passed to either `onSubmit` or until it calls `submitForm`. If the submission handler throws any errors or completes successfully it will be set to `false` afterward.
Here is small example:
Note that calling `validate` from the `Form` slot props will not cause the `isSubmitting` state to change, it will only change if either `submitForm` or `handleSubmit` are called or when a submit event is triggered.
The `Form` component exposes a `submitCount` state that you can use to track the number of submission attempts done by the user. For more information check the [API Reference](/api/form).
## Handling Invalid Submissions
In case you want to perform some logic after a form fails to submit due to validation errors (e.g: focusing the first invalid field), you can listen for the `onInvalidSubmit` event emitted by the `` component.
```vue
```
Specifying a `onInvalidSubmit` prop or `@invalid-submit` will run your handler if you submit your form using either `handleSubmit` or the regular form submit event but not the `submitForm` function.
## Initial Values
Since with vee-validate you don't have to use `v-model` to track your values, the `Form` component allows you to define the starting values for your fields, by default all fields start with `undefined` as a value.
Using the `initialValues` prop you can send an object that contains the field names as keys and their values:
```vue
```
Doing so will trigger initial validation on the form and it will generate messages for fields that fail the initial validation. You can still use `v-model` on your fields to define model-based initial values.
You can use `validateOnMount` prop present on the `` component to force an initial validation when the component is mounted.
Note that **only the non-dirty fields will be updated**. In other words, **only the fields that were not manipulated by the user will be updated**. For information on how to set the values for all fields regardless of their dirty status check the following [Setting Form Values section](#setting-form-values)
It's generally recommended that you provide the `initialValues`, this is because vee-validate cannot assume a reasonable initial value for your fields other than `undefined` which may cause unexpected behavior when using a 3rd-party validator that does not deal with `undefined`.
## Setting Form Values
You can set any field's value using either `setFieldValue` or `setValues`, both methods are exposed on the `` component scoped slot props, and as component instance methods.
You can call them with template `$refs` and for an added convenience you can call them in the submit handler callback.
**Using scoped slot props**
```vue-html
```
**Using submit callback**
```vue
```
**Using template `$refs`**
```vue
```
Note that setting any field's value using this way will trigger validation
## Submission Behavior
vee-validate does the following when you submit a form rendered by `` or when calling either `handleSubmit` or `submitForm`:
### Before validation stage
- Sets all fields `touched` meta to `true`
- Sets `isSubmitting` form state to `true`
- Increments the `submitCount` form state by `1`
### Validation stage
- Sets form and individual fields meta `pending` to `true` to indicate validation is in progress
- Runs the validation function/schema/rule against the current form values asynchronously
- Checks for any errors in the validation result
- If there are errors then it will skip the next stage and update the validation state (meta, errors) for the form and fields
- If there aren't any errors then it will set the `pending` meta flag to `false` and proceed to the next stage
### After validation stage
- Calls the `@submit` handler you specified, or calls the `handleSubmit` callback you provided.
- After the callbacks in either method finish (it will wait if the result is asynchronous), then it will set `isSubmitting` to `false`
Note that there isn't a need to have `isSubmitting` set back to false if you've used `submitForm`, as this submission method will perform a full-page refresh (native forms behavior).
## Handling Resets
vee-validate also handles form resets in a similar way to submissions. When resetting the form, all fields' errors and meta flags will be reset to their original state, including the fields' values.
Form reset is handled automatically if you are using the `as` prop to render a `form` element, like shown in this example:
```vue
```
Alternatively if you plan to use the scoped slot for complex markup, you can use the `handleReset` slot prop function to trigger the reset manually:
```vue-html
```
### Resetting Forms After Submit
Usually you will reset your forms after a successful submission, the `onSubmit` handler receives an additional `FormActions` object in the second argument that allows you do some actions on the form after submissions, this is the shape of the `FormActions` object:
```ts
export interface FormActions {
setFieldValue: (field: T, value: any) => void;
setFieldError: (field: string, message: string | undefined) => void;
setErrors: (fields: Partial>) => void;
setValues: (fields: Partial>) => void;
setFieldTouched: (field: string, isTouched: boolean) => void;
setTouched: (fields: Partial>) => void;
resetForm: (state?: Partial) => void;
}
```
This is an example of using the form actions object to reset the form:
```vue
```
The `resetForm` accepts an optional `state` object that allows you to specify the new initial values for any of the fields state, this is the shape of the `FormState` object:
```ts
interface FormState {
// any error messages
errors: Record;
// dirty meta flags
dirty: Record;
// touched meta flags
touched: Record;
// Form Values
values: Record;
}
```
In the following snippet, `resetForm` is used to update the form values to specific ones other than their original values. This is useful if your receive your form state asynchronously
```js
resetForm({
values: {
email: 'example@example.com',
password: '',
},
});
```
You can also use template `$refs` to reset the form whenever you need:
```vue
```
## Initial Errors
If you are building a non-SPA application it is very common to pre-fill form errors using server-side rendering, frameworks like Laravel make this very easy to do. vee-validate supports filling the errors initially before any validation is done using the `initialErrors` prop which is present on the `` component scoped slot props.
The `initialErrors` property accepts an object containing the field names as keys with their corresponding error message string.
```vue
```
`initialErrors` are applied once the `Form` component is mounted and is ignored after, so any changes to the `initialErrors` props won't affect the messages.
See the next section for setting errors manually.
## Setting Errors Manually
Quite often you will find yourself unable to replicate some validation rules on the client-side due to natural limitations. For example, `unique` email validation is complex to implement on the client-side, which is why the `` component allows you to set errors manually.
You can set messages for fields by using either `setFieldError` which sets an error message for one field at a time, and the `setErrors` function which allows you to set error messages for multiple fields at once.
Both functions are available on the `Form` component scoped slot props, and also on the `Form` component instance which enables you to use it with template `$refs`, and also for added convenience on the `submit` event handler since it would be the most common place for its usage.
Here are a few snippets showcasing its usage in these various scenarios:
**Using scoped slot props (recommended)**
```vue-html
```
**Using submit callback (recommended)**
```vue
```
**Using template `$refs`**
```vue
```
Always try to avoid using the template `$refs` to gain access to the `` component methods, template `$refs` are designed to be an escape hatch of sorts when all else fails.
So treat them as such and don't reach out for template `$refs` if you can help it.
================================================
FILE: docs/src/pages/guide/components/nested-objects-and-arrays.mdx
================================================
---
layout: ../../../layouts/PageLayout.astro
title: Nested Objects and Arrays
description: Structuring forms in nested paths in objects or arrays
order: 4
next:
path: guide/global-validators
title: Global Validators
description: Defining global rules to be used throughout your web app
---
import DocTip from '@/components/DocTip.vue';
import DocBadge from '@/components/DocBadge.vue';
# Nested Objects and Arrays
vee-validate supports nested objects and arrays, using field name syntax to indicate a field's path. This allows you to structure forms easily to make data mapping straightforward without having to deal with flat form values.
## Nested Objects
You can specify a field to be nested in an object using dot paths, like what you would normally do in JavaScript to access a nested property. The field `name` prop acts as the path for that field:
```vue
```
Submitting the previous form would result in the following values being passed to your handler:
```js
{
"links": {
"twitter": "https://twitter.com/logaretm",
"github": "https://github.com/logaretm"
}
}
```
You are not limited to a specific depth, you can nest as much as you like.
## Nested Arrays
Similar to objects, you can also nest your values in an array, using square brackets just like how you would do it in JavaScript.
Here is the same example as above but in array format:
```vue
```
Submitting the previous form would result in the following values being passed to your handler:
```js
{
"links": [
"https://twitter.com/logaretm",
"https://github.com/logaretm"
]
}
```
vee-validate will only create nested arrays if the path expression is a complete number, for example, paths like `some.nested[0path]` will not create any arrays because the `0path` key is not a number. However `some.nested[0].path` will create the array with an object as the first item.
## Avoiding Nesting
If your fields' names are using the dot notation and you want to avoid the nesting behavior which is enabled by default, all you need to do is wrap your field names in square brackets (`[]`) to disable nesting for those fields.
```vue
```
Submitting the previous form would result in the following values being passed to your handler:
```js
{
"links.twitter": "https://twitter.com/logaretm",
"links.github": "https://github.com/logaretm"
}
```
## Field Arrays
Field arrays are a special type of nested array fields, they are often used to collect repeatable pieces of data or repeatable forms. They are often called "repeatable fields".
When dealing with those fields it is better to use `` component which gives you a few helpers you can use to manage the array fields.
Here is a small example that shows how easy it is to create a repeatable `URL` field:
```vue
```
The `` component requires being used inside a `Form` component or a `useForm` to be called at its parent tree.
### Field Array Paths
When planning to use `` you need to provide a `name` prop which is the path of the array starting from the root form value, you can use dot notation for object paths or indices for array paths.
Here are a few examples:
_*Iterate over the `users` array:*_
```vue-html
```
_*Iterate over the `domains` inside `settings.dns` object:*_
```vue-html
```
_*Iterate over both `users` and `links`:*_
```vue-html
```
### Iteration Keys
The `FieldArrayEntry` item exposes a `key` property, this property is unique and is auto-generated for you so you can use it as an iteration key.
```vue-html
```
This auto-generated `key` property is very convenient as you no longer have to provide your own unique key for each item.
The `key` property is not an index. It is a unique identifier for the array item that is independent of the array index, so you should not be using it to reference field names.
### Array Helpers
The `` slot provides the following properties and functions:
- `fields`: a **read-only** version of your array field items, it includes some useful properties like `key`, `isFirst` and `isLast`, the actual item value is inside `.value` property. You should use it to iterate with `v-for`.
- `push(item: any)`: adds an item to the end of the array.
- `insert(idx: number, item: any)`: Inserts an array item at the specified index.
- `prepend(item: any)`: adds an item to the start of the array.
- `remove(idx: number)`: removes the item with the given index from the array.
- `swap(idxA: number, idxB: number)`: Swaps two array elements by their indexes.
- `replace(items: any[])`: Replaces the entire array values with the given items.
- `update(idx: number, value: any)`: Updates an array item value at the specified index.
- `move(oldIdx: number, newIdx: number)`: Moves an array item to a different position within the array.
[Read the API reference](/api/field-array) for more information.
## Caveats
### Paths creation and destruction
vee-validate creates the paths inside the form data automatically but lazily, so initially, your form values won't contain the values of the fields unless you provide initial values for them. It might be worthwhile to provide initial data for your forms with nested paths.
When fields get unmounted like in the case of conditional rendered fields with `v-if` or `v-for`, their path will be destroyed just as it was created if they are the last field in that path. So you need to be careful while accessing the nested field in `values` inside your submission handler or the `Form` component `values` slot prop.
Path destruction can be annoying when dealing with multi-step forms or tabbed forms where you want all the values to be available even when the fields are unmounted. You can control this behavior by passing `keepValue` prop to the `` component or you can do it for all the fields by passing `keepValues` to the `` component.
Note that the priority of this configuration follows the field config first then it fallbacks to the form's config.
```vue
```
### Referencing Errors
When referencing errors using `errors` object on the `Form` slot props or the `ErrorMessage` component, make sure to reference the field name in the same way you set it on the `name` prop for that field. So even if you avoid nesting you should always include the square brackets. In other words `errors` do not get nested, they are always flat.
### Nested Fields With Validation Schema
Since vee-validate supports [form-level validation](/guide/components/validation#form-level-validation), referencing the nested fields may vary depending on how you are specifying the schema.
If you are using yup, you can utilize the nested `yup.object` or `yup.array` schemas to provide validation for your nested fields, here is a quick example:
```vue
```
You can [visit this link](/examples/array-fields) for a practical example using nested arrays.
================================================
FILE: docs/src/pages/guide/components/validation.mdx
================================================
---
layout: ../../../layouts/PageLayout.astro
title: Validation
description: Field-level and form-level validation and validation behavior and error messages
order: 2
next:
path: guide/components/handling-forms
title: Handling Forms
description: Handling form state and submissions
---
import DocTip from '@/components/DocTip.vue';
import LiveExample from '@/components/LiveExample.vue';
# Validation
vee-validate handles complex validations in a very easy way, it supports synchronous and asynchronous validation and allows defining rules on the field-level or the form level using validation schemas with built-in support for [yup](https://github.com/jquense/yup).
You will be using the following components to validate your forms:
- A `Field` component represents a single form input and can be used to render any kind of HTML elements or Vue components.
- A `Form` component that renders a form. Do not confuse the `` component using the `validation-schema` prop:
```vue
```
For more information on the `Form` component, read [the API reference](/api/form).
### Reactive Form Schema
You can have reactive form schemas using `computed` if you are looking to create dynamic schemas using either `yup` or a validation object.
```js
import * as yup from 'yup';
export default {
data: () => ({
min: 6,
}),
computed: {
schema() {
return yup.object({
password: yup.string().min(this.min),
});
},
},
};
```
```vue
```
When the validation schema changes, only the fields that were validated at least once will be re-validated, the other fields won't be validated to avoid aggressive validation behavior.
## Validation Behavior
By default vee-validate runs validation in these scenarios:
**After field value change**
- When a `change` event is dispatched/emitted
- value changed externally (model update or others)
Note that `input` event is not considered to be a trigger because it would make it too aggressive, you can configure the triggers in the next section to suit your needs.
**After Rules change**
- Only if the field was validated before via user interaction
**After field is blurred**
- Field has been blurred (`blur` event was emitted)
**After form submissions**
- When the form has been submitted with either `handleSubmit` or `submitForm` on the `` component slot props
### Customizing Validation Triggers
By default vee-validate adds multiple event listeners to your fields:
- **input:** Adds a `handleChange` handler that updates the field value, and it may validate if configured to do so (may update `meta.dirty` flag if the value changed).
- **change:** Adds a `handleChange` handler that updates the field value and validates the field (may update `meta.dirty` flag if the value changed).
- **blur:** Adds a `handleBlur` handler that updates the `meta.touched` flag.
- **update:modelValue** Adds a `handleChange` handler to components emitting the `update:modelValue` event
Notice that in all of these, the `handleChange` handler is the only one that triggers validation. You can configure if a handler should validate by using the `configure` helper:
```js
import { configure } from 'vee-validate';
// Default values
configure({
validateOnBlur: true, // controls if `blur` events should trigger validation with `handleChange` handler
validateOnChange: true, // controls if `change` events should trigger validation with `handleChange` handler
validateOnInput: false, // controls if `input` events should trigger validation with `handleChange` handler
validateOnModelUpdate: true, // controls if `update:modelValue` events should trigger validation with `handleChange` handler
});
```
Note that configuring any of these options to `false` will not remove all the events, they only control if each event triggers a validation check or not.
This might not be flexible enough for your needs, which is why you can define the same config per `Field` component instance:
```vue-html
```
Additionally if you need to use different events or have specific needs in mind, you can control which events to listen to by using the scoped-slot `handleChange` prop of the `` component and binding it to the desired event:
```vue-html
```
In addition to those events, you can also validate when the `` or `` components are mounted with `validateOnMount` prop present on both components:
```vue-html
```
You can also specify if a `handleChange` call should trigger validation or not by providing the second argument:
```vue-html
```
When applying `v-bind="field"` to a Vue component, be careful that the listeners will both be applied for Vue and native DOM events, meaning you might trigger validation unintentionally.
An example of that could be `input[type="file"]` inputs, because you cannot bind the `value` attribute to a file instance which means two-way binding won't work there. In that case, only listing to handful of events makes more sense:
```vue-html
```
For custom components, it is recommended that you listen to the proper events when using `v-bind` with custom components, the following sample uses `modelValue` events.
```vue-html
```
For 3rd party components you may consult their documentation to figure which events to trigger validation for. Here are a few examples for the common UI frameworks [here](/examples/ui-libraries).
## Displaying Error Messages
### Using the Field slot-props
If you intend to use the scoped slot on the `Field` component, you can access `errors` or `errorMessage` on the scoped slot props to render your messages:
```vue-html
{{ errors[0] }}{{ errorMessage }}
```
This is convenient if you have a complex markup for your input and would like to keep everything contained within, it also allows you to create input components with built-in validation.
### Using the Form slot-props
As you noticed the `` component gives you access to the `errors` on its scoped-slot props which you can use to display any error messages for any `` within that form:
```vue-html
```
and if you would like, you could display all error messages for your fields by iterating over the `errors` object:
```vue-html
```
### Using ErrorMessage component
You've seen how the `ErrorMessage` works in the previous examples, by default the `ErrorMessage` component renders a `span` but you can specify any kind of HTML element or global component to the `as` prop.
```vue-html
```
The `` component is very flexible and you can customize its render output with scoped slots to build complex messages markup, read the [ErrorMessage API reference](/api/error-message) for more information.
### Custom Field Labels
More often than not, your fields will have names with underscores or shorthands which isn't very nice when showing in error messages, for example, you might have specific encoding to your field names because they might be generated by the backend. Ideally, you want to avoid having messages like:
```txt
The down_p is required
```
And instead, show something more meaningful to the user
```txt
The down payment is required
```
You can do this in two ways depending on which validators you are using (yup or [global validators](/guide/global-validators)).
With yup it is very straightforward, you just need to call `label()` after defining your field's validations either in field level or form level:
```js
const schema = Yup.object({
email_addr: Yup.string().email().required().label('Email Address'),
acc_pazzword: Yup.string().min(5).required().label('Your Password'),
});
```
Here is a live example:
If you are interested in how to do the same for global validators check the [i18n guide](/guide/i18n#custom-labels)
## Validation Metadata
### Field-level Meta
Each field has metadata associated with it, the `meta` property available on the `` component contains additional information about the field:
- `valid`: The current field validity, automatically updated for you.
- `touched`: If the field was blurred (unfocused), can be updated with the `handleBlur` function or `setTouched` on the field's slot scope props.
- `dirty`: If the field value was updated, you cannot change its value.
- `pending`: If the field's validations are still running, useful for long-running async validation.
- `initialValue`: The field's initial value, is `undefined` if you didn't specify any.
```vue-html
{{ meta }}
```
This is the typescript interface for a field's meta-object value
```ts
interface FieldMeta {
dirty: boolean;
pending: boolean;
touched: boolean;
valid: boolean;
initialValue: any;
}
```
The default value is `undefined` unless specified which may cause unexpected `meta.dirty` results. To get accurate results for the `meta.dirty` flag, you must provide an initial value to your field even if the values are empty.
```vue-html
{{ meta }}
```
To reduce the verbosity of adding a `value` prop to each field, you could provide the `initial-values` prop to your `` component instead.
Since the `meta.valid` flag is initially `true` (because it just means there are no errors yet), it would cause problems if you have a "success" UI state an indicator.
To avoid this case you could combine the `valid` flag with either `meta.dirty` or `meta.touched` to get accurate representation:
```vue-html
⛔️ {{ errorMessage }}✅ Field is valid
```
### Form-level Meta
Forms also have their own `meta` value containing useful information about the form, it is an aggregation of the metadata for the fields inside that form.
The form's metadata properties are:
- `valid`: The form's validity status, will be `true` if the errors array is empty. After the form is mounted, vee-validate will update the flag to its accurate state
- `touched`: If at least one field was blurred (unfocused) inside the form.
- `dirty`: If at least one field's value was updated.
- `pending`: If at least one field's validation is still pending.
- `initialValues`: All fields' initial values, packed into an object where the keys are the field names.
```vue-html
```
Here is a similar example where we disable the form's submit button if no value was changed, we will check the `dirty` flag on the form's scoped slot props which should tell us if the form values have changed or not.
```vue
```
Notice that the `initial-values` in the previous example were provided, like mentioned for the `meta.dirty` accuracy for fields, to get accurate results for the `meta.dirty` flag, you must provide initial values to your forms even if the values are empty.
Forms `meta.valid` flag is also initially `true` (because it just means there are no errors yet), it would cause problems if you have a "success" UI state or an indicator.
To avoid this case you could combine the form's `valid` flag with either `meta.dirty` or `meta.touched` to get accurate representation:
```vue-html
```
================================================
FILE: docs/src/pages/guide/composition-api/caveats.mdx
================================================
---
layout: ../../../layouts/PageLayout.astro
title: Caveats and best practices
description: Things to watch out for when using the composition API
order: 7
menuTitle: Best practices
---
# Composition API Caveats
When using the composition API, there are a few things that are not clear when first starting to use it. This page will contain these topics and help you understand how to workaround or address them.
## Function Field Names with `useField`
You might've noticed that some examples in the docs pass the field name as a function to `useField`:
```js
import { useField } from 'vee-validate';
export default {
props: {
name: String,
},
setup(props) {
const { value, errorMessage } = useField(() => props.name);
},
};
```
This is mainly because the `props` in Vue.js is a reactive object, meaning if you access or destruct any of its properties they will lose the reactivity aspect. Let's say you did the following:
```js
import { useField } from 'vee-validate';
export default {
props: {
name: String,
},
setup(props) {
// ❌ Don't do this in custom input components
const { value, errorMessage } = useField(props.name);
},
};
```
The implications are that vee-validate is no longer able to tell when the field name changes, which is crucial for syncing values when they do.
A common example where field names change frequently is in a array field where `v-for` loops field names use the index or the iterated value to generate the field name
```vue{4}
```
To address this issue, you need to get a reactive reference to the `name` property. Vue offers a few ways to do this, so you can use any of the following methods:
```js
import { toRef, toRefs, computed } from 'vue';
// ✅ using a function that returns the name
const { value, errorMessage } = useField(() => props.name);
// ✅ using `toRef`
const { value, errorMessage } = useField(toRef(props, 'name'));
// ✅ using `toRefs`
const { name } = toRefs(props);
const { value, errorMessage } = useField(name);
// ✅ using `computed`
const name = computed(() => props.name);
const { value, errorMessage } = useField(name);
```
## Destructing composable
The composition API examples in the docs have always used the left-hand side destructing syntax when assigning component data with any of the composable functions vee-validate offers. To quickly refresh your memory:
```js
const { value } = useField('field');
const { handleChange } = useForm();
const { fields } = useFieldArray('users');
```
This is required by default, because each of these functions assumes you might never need the entire features each one provides and such each state/function is exposed independently as a `Ref` or a `Function`.
This means if you try the following, it won't work as expected when used in your template:
```vue
{{ form.meta.valid }}
```
This is because the `setup` function doesn't recursively expose the refs inside of these objects. If you prefer to use the composition API like shown above, then you can fix most of the issues by wrapping the function calls with `reactive()`.
```vue
{{ form.meta.valid }}
```
You can read more on that behavior in [Vue.js docs](https://vuejs.org/guide/reusability/composables.html#conventions-and-best-practices). Note that once you wrap the composable calls with `reactive` you no longer can destruct them and preserve the reactivity.
================================================
FILE: docs/src/pages/guide/composition-api/custom-inputs.mdx
================================================
---
layout: ../../../layouts/PageLayout.astro
title: Custom inputs
description: Field-level and form-level validation and validation behavior and error messages with composition API
order: 4
next:
path: guide/composition-api/helpers
title: Composable Helpers
description: Access any field or form state within child components with these composable helpers.
intro: |
You've learned to build your form, your custom inputs. Now it is a quick one to figure out how to build special components like submission buttons, reset buttons, error displays and more with these composable helpers.
---
# Building Custom inputs
import DocTip from '@/components/DocTip.vue';
import Repl from '@/components/MdxRepl.vue';
## Imperative vs Declarative
So far we've been using `useForm` to create forms and use `defineField` to create field-binding objects to integrate them with our fields. However, that usually requires a lot of boilerplate code to create the binding object and the field component.
For example, this is how a 5-field form looks like with `useForm` and `defineField`:
```js
const { defineField } = useForm();
const email = defineField('email');
const firstName = defineField('firstName');
const lastName = defineField('lastName');
const password = defineField('password');
const passwordConfirm = defineField('passwordConfirm');
```
This can get ugly very quickly especially if you have a lot of field arrays or nested fields involved. This is one of the downsides of using an imperative API, but with `useField` you can switch to declarative API and get rid of all that boilerplate code.
`useField` is a composition function that is similar to `useForm`. it makes it easier to create and manage input components. You should use it when creating custom input components and that means you've made the choice that vee-validate will be an integral part of your input component system.
## Creating a custom input component
Let's start with a simple example, we will create a `InputText` component that represents a text field. It can be as simple as this:
```vue
{{ errorMessage }}
```
This works exactly the same way as with `defineField`, but now since you have a vee-validate field component, you can use it directly in any component with a form context and it will just work:
Here is a live example:
Notice how much of the burden of defining fields went away as soon as switched to the declarative approach. This is where `useField` really shines, but that's just us getting started. Follow along in this guide to make the most out of `useField`.
## Validation
All previous examples have used the form's validation schema to validate the individual fields, however, you can also define a validation schema for each field individually.
### Validating with yup
You can use Yup schemas to validate fields individually by passing the schema as the second argument to `useField`.
### Validating with Zod
You can use [Zod](https://github.com/colinhacks/zod) directly with vee-validate.
### Validating with Valibot
You can use [Valibot](https://valibot.dev/) to validate your fields.
### Other validation providers
#### Standard Schema
vee-validate supports [standard schema](https://standardschema.dev/) libraries, which includes all the previous validation providers and more.
#### Validating with global validators
Another option is using `@vee-validate/rules` which have been historically bundled with past versions of vee-validate. It includes rules that can be defined globally and then used anywhere using Laravel-like string expressions.
You can refer to the full guide on global rules [here](/guide/global-validators).
#### Validating with functions
Another option is to just use any 3rd party validation tool you prefer.
### Triggers
#### Default Behavior
By default, vee-validate runs validation whenever the `value` ref changes whether it was bound by a `v-model` or changed in your code:
```js
const { value } = useField('fieldName', yup.string().required());
// validation WILL be triggered
value.value = 'something';
```
You can disable that behavior by passing a `validateOnValueUpdate` option set to `false`:
```js
const { value } = useField('fieldName', yup.string().required(), {
validateOnValueUpdate: false,
});
// validation WILL NOT trigger
value.value = 'something';
```
#### Handling Events
`useField()` composition function is not concerned with any events, it only validates whenever the `value` ref changes. However, it gives you everything you need to set up your own validation experience.
The `useField` function exposes some handler functions, each handling a specific aspect of the validation experience:
- `handleChange`: Updates the field value, can be configured to trigger validation or silently update the value
- `handleBlur`: Updates the `meta.touched` flag, doesn't trigger validation.
```js
const { handleChange, handleBlur } = useField('someField');
```
In this example, we are validating on the `input` event (when the user types), which would make the validation aggressive:
With a slight adjustment we can make our validation lazy by changing the listener to `@change` (validates when the user leaves the control):
```vue-html
{{ errorMessage }}
```
Note that `handleChange` can be called anywhere, not just in the template, and not as just an event handler. You can use it to mutate the field value whenever you want, as an added bonus you can choose if `handleChange` should trigger a validation or not.
```js
const { handleChange } = useField('someField');
// validates by default
handleChange('new value');
// validates
handleChange('new value', true);
// Doesn't validate
handleChange('new value', false);
```
Let's say you want to validate on `blur` instead. You can use the `handleBlur` in a similar way. The main differences are:
- `handleBlur` doesn't mutate the `value` of the field. It only sets the `meta.touched` to `true`.
- `handleBlur` does not validate the current value by default, you have to pass `true` as a second argument to trigger validation.
With that info in mind, you can validate on `blur` like so:
```vue-html
{{ errorMessage }}
```
As you can see, the `useField` doesn't care which events you use `handleChange` for. This allows for greater flexibility that's not possible with the `` component, not as straightforward at least.
Consider this validation experience:
- Validate on Change/Blur initially (when the user leaves the control), let's call this lazy mode.
- If the field is invalid, switch the validation to validate on input (when the user types), let's call this aggressive mode.
- If the field is valid, go back to "lazy" mode, otherwise, be "aggressive".
Implementing this requires some knowledge about how the `v-on` (we can bind objects on it) handler works.
```js
const { errorMessage, value, handleChange } = useField(() => props.name, undefined, {
validateOnValueUpdate: false,
});
const validationListeners = {
blur: evt => handleBlur(evt, true),
change: handleChange,
input: evt => handleChange(evt, !!errorMessage.value),
};
```
Then in your template, you can use `v-on` to add your listener object:
```vue-html
```
Here is a full example:
## v-model Support
The `useField` function can automatically manage `v-model` integration for you. Usually, you will need to do this in every component you create:
```js
const props = defineProps({
modelValue: String,
});
const emit = defineEmits(['update:modelValue']);
```
Instead, you can let `useField` do that for you by telling it to enable `v-model` syncing:
```js
const props = defineProps({
modelValue: String,
});
const { value, errorMessage } = useField('fieldName', undefined, {
syncVModel: true,
});
```
Now whenever `value` changes, you will emit an `update:modelValue` event with the new value. This is useful when you want to use `v-model` with your custom input component:
You can also use different prop names for the `modelValue`, for example, `v-model:text` can be implemented by passing the model name directly to `syncVModel`.
```js
const props = defineProps({
text: String,
});
const { value, errorMessage } = useField('fieldName', undefined, {
syncVModel: 'text',
});
```
This will emit `onUpdate:text` instead of `onUpdate:modelValue` whenever the `value` changes.
## Displaying Error Messages
You've already seen how to display errors with `useForm`. With `useField` you can use `errorMessage` ref:
```js
const { errorMessage, value } = useField('fieldName', yup.string().required());
// contains the error message if available
errorMessage.value;
```
In addition to this, you can get all errors for the field using the `errors` ref which contains multiple error messages if applicable:
```js
const { errors, value } = useField('fieldName', yup.string().required());
// contains an array of error messages, otherwise empty array
errors.value;
```
Here is an example where each field displays its entire range of error messages:
### Custom Field Labels
More often than not, your fields will have names with underscores or shorthands which isn't very nice when showing in error messages, for example, you might have specific encoding to your field names because they might be generated by the backend. Ideally, you want to avoid having messages like:
```txt
The down_p is required
```
And instead show something more meaningful to the user
```txt
The down payment is required
```
You can do this in two ways depending on which validators you are using (yup or [global validators](/guide/global-validators)).
#### Custom Labels with Yup
With yup it is very straightforward, you just need to call `label()` after defining your field's validations either at the field level or form level:
```js
const schema = Yup.object({
email_addr: Yup.string().email().required().label('Email Address'),
acc_password: Yup.string().min(5).required().label('Your Password'),
});
```
#### Custom Labels with Zod
Zod does not have a built-in `label` method, but you can override the default error messages by passing a custom message to the chained validator.
```js
const schema = z.object({
email_addr: z.string().email({ message: 'Email Address be a valid email address' });
acc_password: z.string().min(5, { message: 'Password be at least 5 characters long' });
});
```
If you are interested in how to do the same for global validators check the [i18n guide](/guide/i18n#custom-labels)
## Field-level Meta
Each field has metadata associated with it, the `meta` property returned from `useField` contains information about the field:
- `valid`: The current field validity, is automatically updated for you.
- `touched`: If the field was **touched**, can be updated with `setTouched` on `useField`'s return value.
- `dirty`: If the field value was updated, you cannot change its value.
- `pending`: If the field's validations are still running, useful for long-running async validation.
- `initialValue`: The field's initial value, is `undefined` if you didn't specify any.
```js
const { meta } = useField('fieldName');
meta.dirty;
meta.pending;
meta.touched;
meta.valid;
meta.initialValue;
```
This is the typescript interface for a field's meta value
```ts
interface FieldMeta {
dirty: boolean;
pending: boolean;
touched: boolean;
valid: boolean;
initialValue: any;
}
```
Just like how the form's `meta` is read-only, this is also read-only and you cannot change it directly. Actually, only the `touched` meta value can be mutated using `handleBlur`, all other meta values are automatically updated for you as the field validates or when it changes its value.
```js
const { meta, handleBlur } = useField('fieldName');
// updates meta.touched = true
handleBlur();
```
Since the `meta.valid` flag is initially `true` (because it just means there are no errors yet), it would cause problems if you have a "success" UI state as an indicator.
To avoid this case you should combine the `valid` flag with either `meta.dirty` or `meta.touched` to get an accurate representation. You will see that in action in the next example.
In the following example, we the various meta information flags to style the input with some styling.
Notice in the previous example, we passed an `initialValue`, this is because the default field value is `undefined` which may cause unexpected `meta.dirty` results.
To get accurate results for the `meta.dirty` flag, you must provide an initial value to your field even if the values are empty.
To reduce the verbosity of adding an `initialValue` prop to each field, you could provide the `initialValues` prop to your `useForm` call instead.
## Building checkboxes
Checkboxes are a hard type of input to implement, mainly because of the expectations about how it should mutate the form's value. For example, a checkbox can be used to toggle between `true` or `false` values which is common with single checkboxes. But it can also be used in a group to act as a multi-select between multiple options. In that case, it adds or removes its own "checked" value to the group value.
This means checkboxes have three states to maintain:
- It's own checked value. In HTML this is done with the `value` attribute for native `input[type="checkbox"]` elements.
- The current form value and if it is a checkbox group or a single checkbox. This is usually the `modelValue` prop for components.
- Whether it's checked or not, if the checked value equals or is in the form value then it is checked. This should be computed based on the previous fact.
All of this can be hard to wrap your head around. However, `useField` makes this easy as it already handles the nuances of checkboxes.
The `useField` function accepts a `type` option that you can use to tell vee-validate that the input type is a checkbox and also accepts a `checkedValue` option.
```ts
const { handleChange, checked } = useField('myCheckbox', undefined, {
type: 'checkbox',
checkedValue: 'opt1',
});
```
A simple integration with an input element would look like this:
Note that we are not using `v-model` with the `value` returned from `useField` here. This is because `handleChange` is better suited for checkboxes as it handles toggling the value on or off and is also aware of the form has other checkboxes so it also handles whether the value should be an array or a single value.
You can find a more advanced example of checkboxes on [this page](/examples/custom-checkboxes/).
================================================
FILE: docs/src/pages/guide/composition-api/getting-started.mdx
================================================
---
layout: ../../../layouts/PageLayout.astro
title: Getting started
description: Field-level and form-level validation and validation behavior and error messages with composition API
order: 1
next:
path: guide/composition-api/handling-forms
title: Handling forms
description: Submissions, resets and form state
intro: |
Now that you've learned how to use forms to define fields, collect their values and validate them. Next, you will learn how to handle submissions and implement advanced patterns with forms.
---
import DocTip from '@/components/DocTip.vue';
import DocBadge from '@/components/DocBadge.vue';
import LiveExample from '@/components/LiveExample.vue';
import Repl from '@/components/MdxRepl.vue';
# Getting started
vee-validate is built from the ground up with the composition API through a collection of functions, mainly the `useField` and `useForm` functions. Internally the `` and `` components actually use the composition functions under the hood.
Meaning you can create your own custom input and form components and they will be treated the same as `` and `` components. You can mix them together and use a `Form` component with any other custom component that uses `useField` and vice versa.
vee-validate supports synchronous and asynchronous validation and allows defining rules on the field level or the form level using validation schemas. vee-validate has first-class support for:
- [Standard Schema](https://standardschema.dev/) libraries like zod, valibot, yup and more.
- [Global validators](/guide/global-validators) (Laravel-like syntax) through `@vee-validate/rules`.
vee-validate has historically been a declarative validation library, and while the composition API changes things a bit, it still follows the same mindset of declarative validation. vee-validate optimizes for building fields and forms, not values.
## When to use composition API
While vee-validate offers both declarative components and composition functions to supercharge your forms, it is always up to you to decide which one to use. However, the composition API is easier to integrate and more flexible. You can build custom components with it or integrate it with any UI library. It is generally recommended to use the composition API.
On this page, you will learn how to declare forms and how to hook your elements and components into vee-validate forms and achieve value tracking, validation, and more.
## Declaring Forms
### Form context
You can declare forms with the `useForm` function exported from the `vee-validate` core package. This is a composition API function that marks the current component as a form.
```vue
{{ values }}
```
Calling `useForm` creates a form context in the component and provides it for any child component that injects it. This means you should stick to calling `useForm` once in a component.
Creating a form context does a few things:
- Acts as a value collector for all the fields you will declare as child components.
- Validates the fields and aggregates the errors.
- Aggregates the validity, touched, and dirty states of all the fields.
### Field binds
With `useForm` declared, you are now ready to integrate the form with your elements and components. vee-validate is agnostic to the UI you are using.
You will learn how to associate your components and elements with the form and how to get value collection, validation, and error messages working.
### HTML Inputs
`useForm` provides a function called `defineField`. This function accepts a field path and returns a value model and an object containing the bindings for the input element. The field path is a string that represents the path to the field in the form context.
For example, if you have a field called `email` in the form context, the field path will be `email`.
```ts
const { defineField } = useForm();
const [email, emailAttrs] = defineField('email');
```
Note that `defineField` generates a pair of values, the first one is the value model and the second one is the attributes/props object. The props object contain attributes or event listeners that are useful to have on the input control or component which enables custom validation triggers and more.
Here is a basic example of how to use `defineField` with a simple input element:
Notice that as you type in the input, the `values` are automatically updated with the value changes.
Let's quickly add a validation schema on the form to see some errors on the form. We will be using `yup` throughout the examples, but you can use `zod` or any other supported validation library you want.
To add a `yup` schema or any kind of form schema, you pass it to the `validationSchema` option when calling `useForm`. Naturally, form schemas are almost always an `object` or a `shape` schema.
```ts{1,3-5,8}
import * as yup from 'yup';
const schema = yup.object({
email: yup.string().required().email(),
});
const { defineField } = useForm({
validationSchema: schema,
});
const [email, emailAttrs] = defineField('email');
```
Here is a full running example:
Notice as you type into the input, the validation is then triggered and the errors are populated. By default `defineField` optimizes for aggressive validation, meaning the validation will be triggered whenever the model changes.
You can change that behavior. For example, you can make it "lazy" by passing a configuration to `defineField` to disable validation on model updates with `validateOnModelUpdate` config.
Now as you type in the field, the input is not immediately validated. You can do more with dynamic configurations.
### Components
Similarly to HTML inputs, you can achieve the same results with the same `defineField` function.
Following the previous examples we can achieve value tracking like this:
As you type into the input, notice that the `values` are being updated.
Let's add validation to the previous example:
Notice that for components, validations are executed immediately. This is intended because component implementations are not standardized across the Vue ecosystem as there is no guarantee it will emit the same range of events as the native HTML elements. However, you can customize the validation trigger if you know the components you are using are emitting the right events to support the behavior.
### Mapping attributes and props
But aside from the attributes and listeners that vee-validate adds to those binding objects, you can also map the attributes and props of the in. This is useful when you want to:
- Map the attributes/props to a different name.
- Pass new attributes/props to the component/element based on the field state.
You can use `props` to include any additional props or attributes you need to add to the component/element.
```ts
const { defineField } = useForm({
// ...
});
const [email, emailProps] = defineField('email', { props: state => ({ error: state.errors[0] }) });
```
In the following example, we have a component that accepts an `error` string prop and shows that message if it is not empty. This is common in many UI libraries as they try not to lock you into a specific validation library.
The `state` object contains a lot of useful information about the field, it is fully typed so you can explore it with your IDE or visit the [source reference](https://github.com/logaretm/vee-validate/blob/main/packages/vee-validate/src/types/forms.ts#L255-L258) for more information.
Notice that `form` also gives you access to `errors` so you can reference them anywhere in the component.
### Dynamic configuration
Instead of passing a static configuration object `defineField`, you could pass a function that returns different configuration values. This is useful when you want the configuration to be dynamic based on the field state.
Here is an example that shows how to make the validation behavior "eager". Meaning if the field does not have any errors then it will only validate on `change`.
But once it is invalid, it validates on each input event, making it "eager" for success.
## Form Schema
As you have seen in the previous examples, the `useForm` function accepts a `validationSchema` that is used to validate the form. We've been using yup to define the schema however you can use `zod` or any 3rd-party validators.
### Validating with Yup
You can pass yup schemas directly as you've seen previously.
### Validating with Zod
You can use [Zod](https://github.com/colinhacks/zod) in a very similar manner to how we've been using yup in the past examples.
```ts
import { useForm } from 'vee-validate';
import { z } from 'zod';
const schema = z.object({
email: z.string().nonempty().email(),
});
const { errors, values } = useForm({
validationSchema: schema,
});
```
Here is a full example using zod with `useForm`:
There is a known issue with Zod's `refine` and `superRefine` not executing whenever some object keys are missing which is common with forms. This is not an issue with vee-validate as it is a design choice in Zod at the moment. Refer to [this issue](https://github.com/logaretm/vee-validate/issues/4338) for explanations and further reading.
### Validating with Valibot
You can also use [Valibot](https://valibot.dev/) which is is a schema library with bundle size, type safety and developer experience in mind. It is a great alternative to Yup and Zod if bundle size is a concern.
```ts
import { useForm } from 'vee-validate';
import * as v from 'valibot';
const schema = v.object({
email: v.pipe(v.string(), v.email('Invalid email'), v.nonEmpty('required')),
});
const { errors, values } = useForm({
validationSchema: schema,
});
```
Here is a full example using valibot with `useForm`:
### Other validation providers and options
#### Global Rules
Another option is using `@vee-validate/rules` which have been historically bundled with past versions of vee-validate. It includes rules that can be defined globally and then used anywhere using Laravel-like string expressions.
You can refer to the full guide on global rules [here](/guide/global-validators).
#### Validating with functions
Another option is to just use any 3rd party validation tool you prefer, something like [`validator.js`](https://github.com/validatorjs/validator.js/). Here is a quick example:
Or you could use any custom function.
Schema libraries like zod and yup are great at defining schemas especially with nested values so it is recommended that you use any [standard schema](https://standardschema.dev/) library to get full benefits. As an added bonus, you get full typescript support with any compatible library.
### Dynamic Form Schemas
There are a few ways you can create dynamic schemas (reactive) where it changes the validation rules based on some state. The first way to do that is with `computed`.
When the validation schema value changes, only the fields that were validated at least once will be re-validated, the other fields won't be validated to avoid aggressive validation behavior.
There are other ways depending on which validation library you are using. For example, with `yup` you can achieve the same with `yup.lazy` or `zod.lazy`:
================================================
FILE: docs/src/pages/guide/composition-api/handling-forms.mdx
================================================
---
layout: ../../../layouts/PageLayout.astro
title: Handling Forms
description: Handling form state and submissions
order: 2
next:
path: guide/composition-api/nested-objects-and-arrays
title: Nested Objects and Arrays
description: Structuring form values in nested paths in objects or arrays
intro: |
So far we've only dealt with flat form values, what about nested objects and arrays? In the next guide you will learn how to use path names to structure your values and nest them declaratively.
---
import DocTip from '@/components/DocTip.vue';
import Repl from '@/components/MdxRepl.vue';
# Handling Forms
vee-validate makes it easy to handle form submissions, resets, and DX to make your forms much easier to reason about and less of a burden to maintain. The `useForm` function allows you to easily handle:
- Form state (valid/dirty/touched/pending).
- Submitting forms and handling invalid submissions.
- Handling form resets.
## Form Metadata
Forms have a `meta` object value containing useful information about the form, it acts as an aggregation of the metadata for the fields inside that form.
```js
const { meta } = useForm();
meta.value.dirty;
meta.value.pending;
meta.value.touched;
meta.value.valid;
meta.value.initialValues;
```
- `valid`: The form's validity status, will be `true` if the errors array is empty initially, but will be updated once the form is mounted.
- `touched`: If at least one field was blurred (unfocused) inside the form.
- `dirty`: If at least one field's value was updated.
- `pending`: If at least one field's validation is still pending.
- `initialValues`: All fields' initial values, this is an object where the keys are the field names.
Here is a simple example where we disable the form's submit button unless a field was touched.
## Handling Submissions
vee-validate exposes useful defaults to help you handle form submissions whether you submit them using JavaScript or native HTML submissions.
### JavaScript Submissions (AJAX)
To handle submissions, you can use the `handleSubmit` function to create submission handlers for your forms, the `handleSubmit` function accepts a callback that receives the final form values.
```js
const { handleSubmit } = useForm({
validationSchema: yup.object({
email: yup.string().email().required(),
password: yup.string().min(6).required(),
}),
});
// Creates a submission handler
// It validates all fields and doesn't call your function unless all fields are valid
// You can bind `onSubmit` to a form element's submit event, or call it directly to submit the current data.
const onSubmit = handleSubmit(values => {
alert(JSON.stringify(values, null, 2));
});
```
Here is an example that makes use of `handleSubmit` to validate before submitting the form.
The `handleSubmit` function will only execute your callback once the returned function (`onSubmit` in the example) if all fields are valid, meaning you don't have to handle if the form is invalid in your logic.
You can call the returned function either manually or via an event like `@submit` and it will validate all the fields and execute the callback if everything passes validation.
As a bonus, when the returned function is used as an event handler (like in the previous example) it will automatically prevent the default submission of the form so you don't need to use the `prevent` modifier like you normally would.
### Full-Page Submissions (non-AJAX)
For non-ajax submissions that trigger a full page reload, you can use the `submitForm` function instead of `handleSubmit`. You normally would use this if you are not building a single-page application. In the following example, we submit the form to another tab using the `get` form method.
In that case **YOU MUST** use `submitForm` as an event handler for the `submit` event for a native `form` element, otherwise, it would have no effect.
### Handling Invalid Submissions
Sometimes you want to perform some logic after a form fails to submit due to validation errors (e.g. focusing the first invalid field), you can pass a callback as the second argument to the `handleSubmit` function.
```js
const { handleSubmit } = useForm();
function onSuccess(values) {
alert(JSON.stringify(values, null, 2));
}
function onInvalidSubmit({ values, errors, results }) {
console.log(values); // current form values
console.log(errors); // a map of field names and their first error message
console.log(results); // a detailed map of field names and their validation results
}
// This handles both valid and invalid submissions
const onSubmit = handleSubmit(onSuccess, onInvalidSubmit);
```
Here is a quick example of how to scroll to and focus the first invalid field after a failed submission attempt.
### Submission Progress
Quite often you need to show your users a submission indicator, or you might want to disable the submit button entirely until the submission attempt is done. The `useForm` function exposes an `isSubmitting` ref that you can use.
The `isSubmitting` state will be set to `true` once the validation of the form starts (as a result of a submit event) and will keep track of the submission handler you passed to either `onSubmit` or until it calls `submitForm`. If the submission handler throws any errors or completes successfully it will be set to `false` afterward.
```js
const { isSubmitting } = useForm();
```
### Submit Count
The `useForm` function also exposes a `submitCount` ref that you can use to track the number of submissions attempted by the user. The count is incremented regardless of the validation result.
```js
const { submitCount } = useForm();
```
Maybe you want to lock the form if too many attempts were made, or you want to show a message after the first submission attempt.
### Submission Behavior
vee-validate does the following when calling submission handlers created by `handleSubmit` or when calling `submitForm` as a result of the user submitting the form.
#### Before validation stage
- Sets all fields `touched` meta to `true`
- Sets `isSubmitting` form state to `true`
- Increments the `submitCount` form state by `1`
#### Validation stage
- Sets form and individual fields meta `pending` to `true` to indicate validation is in progress
- Runs the validation function/schema/rule against the current form values asynchronously
- Checks for any errors in the validation result
- If there are errors then it will skip the next stage and update the validation state (meta, errors) for the form and fields
- If there aren't any errors then it will set the `pending` meta flag to `false` and proceed to the next stage
#### After validation stage
- Calls the `handleSubmit` handler you passed
- After the callback finishes (it will wait if the result is asynchronous), then it will set `isSubmitting` to `false`
Note that there isn't a need to have `isSubmitting` set back to false if you've used `submitForm`, as this submission method will perform a full-page refresh (native forms behavior).
## Form Values
You may have noticed in the earlier examples that you can access all fields' values using the `values` reactive object returned by `useForm`.
```js
const { values } = useForm();
```
The `values` object is read-only and should not be mutated with a `v-model` or by assigning a value to it. This is because all mutations are done through the vee-validate API, this is because mutations to form state need to have a context.
For example:
```js
const { values } = useForm();
// ❌ Do not do that!
values.email = '';
```
In order for the form UX to be stable, we need to understand why the email value was set to `''`. Was it being reset? Should we run validation again? This is the type of small differences that are a result of vee-validate's design choice based on fields and forms, not values.
### Initial Values
Since you don't have to use `v-model` to track your values, the `useForm` function allows you to define the starting values for your fields, by default all fields start with `undefined` as a value.
Using the `initialValues` option you can send an object that contains the field names as keys and their values:
```js
const { defineInputBinds } = useForm({
initialValues: {
email: 'test@example.com',
password: 'p@$$w0rd',
},
});
```
It's generally recommended that you provide the `initialValues`, this is because vee-validate cannot assume a reasonable initial value for your fields other than `undefined` which may cause unexpected behavior when using a 3rd-party validator that does not deal with `undefined`.
You can reset initial values at [any time using the `resetForm`](#handling-resets) function returned by `useForm`.
### Manually Setting Form Values
You can set any field's value using either `setFieldValue` or `setValues` returned by `useForm`.
```js
const { setFieldValue, setValues } = useForm();
// Sets a value of a specific field in the form values
setFieldValue('fieldName', 'value');
// Merges the given object with the current form values
setValues({
fieldName: 'value',
});
```
### Controlled Values
The form values can be categorized into two categories:
- Controlled values: values that have a form input controlling them via `defineInputBinds` or `defineComponentBinds` or `useField` or ``.
- Uncontrolled values: values that are inserted dynamically with `setFieldValue` or inserted initially with initial values.
Sometimes you maybe only interested in controlled values. For example, your initial data contains noisy extra properties from your API and you wish to ignore them when submitting them back to your API.
When accessing `values` from `useForm` result or the submission handler you get all the values, both controlled and uncontrolled values. To get access to only the controlled values you can use `controlledValues` from the `useForm` result:
```js
const { handleSubmit, controlledValues } = useForm();
const onSubmit = handleSubmit(async () => {
// Send only controlled values to the API
const response = await client.post('/users/', controlledValues.value);
});
```
Alternatively, for less verbosity, you can create submission handlers with only the controlled values with `handleSubmit.withControlled` which has the same API as `handleSubmit`:
```js
const { handleSubmit } = useForm();
const onSubmit = handleSubmit.withControlled(async values => {
// Send only controlled values to the API
const response = await client.post('/users/', values);
});
```
Here is an example that filters out some noisy initial values when submitting the form using the `withControlled` modifier.
### Setting initial values asynchronously
Sometimes your data is fetched asynchronously from an API and you want to set the initial values or the current values after the data is fetched. You can do that by using `resetForm` to set both current and initial data.
You could alternatively use `setValues` but note that `setValues` can trigger validation and do not reset the meta state for the fields like `dirty` or `touched`.
## Handling Resets
vee-validate also handles form resets in a similar way to submissions. When resetting the form, all fields' errors will be cleared, meta info will be reset to defaults and the values will be reset to their original or initial values.
To reset forms you can use the `resetForm` function returned by `useForm`. You can also reset the form to a new state by passing a `FormState` object to the `resetForm` function. You can then set errors, `touched` meta, and the values.
```js
const { resetForm } = useForm();
// Resets the form
resetForm();
//
resetForm({
touched: {
email: false,
},
errors: {
email: 'custom error',
},
values: {
email: 'newvalue@email.com',
},
});
```
This is the shape of the `FormState` object:
```ts
interface FormState {
// any error messages
errors: Record;
// touched meta flags
touched: Record;
// Form Values
values: Record;
}
```
Here is an example where a full form is being reset:
### Resetting Forms After Submit
Usually, you will reset your forms after successful submission. For convenience, the `onSubmit` handler receives an additional `FormActions` object in the second argument that allows you to do some actions on the form after submissions, this is the shape of the `FormActions` object:
```ts
export interface FormActions {
setFieldValue: (field: T, value: any) => void;
setFieldError: (field: string, message: string | undefined) => void;
setErrors: (fields: Partial>) => void;
setValues: (fields: Partial>) => void;
setFieldTouched: (field: string, isTouched: boolean) => void;
setTouched: (fields: Partial>) => void;
resetForm: (state?: Partial) => void;
}
```
This is an example of using the form actions object to reset the form:
## Errors
As you have previously seen in some examples, you have access to `errors` with `useForm` that contains a mapping of each field's path and its error message.
```js
const { errors } = useForm();
```
However, if you want to display multiple errors for your fields then you can use `errorBag` which is a mapping of each field's path and an array of error messages for that field.
```js
const { errorBag } = useForm();
```
Here is an example that displays multiple errors for a field:
### Initial Errors
If you are building a non-SPA application it is very common to pre-fill form errors using server-side rendering, frameworks like Laravel and Rails make this very easy to do. vee-validate supports filling the errors initially before any validation is done using the `initialErrors` option.
The `initialErrors` option accepts an object containing the field names as keys with their corresponding error message string.
```js
useForm({
initialErrors: {
email: 'This email is already taken',
password: 'The password is too short',
},
});
```
`initialErrors` are applied once the component that called `useForm` is mounted and is ignored after, so any changes to the `initialErrors` props won't affect the messages.
### Setting Errors Manually
Quite often you will find yourself unable to replicate some validation rules on the client-side due to natural limitations. For example, `unique` email validation is complex to implement on the client side. So the ability to set errors manually can be useful.
You can set messages for fields by using either `setFieldError` which sets an error message for one field at a time, or by using the `setErrors` function which allows you to set error messages for multiple fields at once.
Both functions are available as a return value from `useForm`. In the following example, we check if the server response contains any validation errors and we set them on the fields:
```js
const { handleSubmit, setFieldError, setErrors } = useForm();
const onSubmit = handleSubmit(async values => {
// Send data to the API
const response = await client.post('/users/', values);
// all good
if (!response.errors) {
return;
}
// set single field error
if (response.errors.email) {
setFieldError('email', response.errors.email);
}
// set multiple errors, assuming the keys are the names of the fields
// and the key's value is the error message
setErrors(response.errors);
});
```
Alternatively, you can use the `FormActions` passed as the second argument to the `handleSubmit` callback which contains both functions for convenience:
```js
const onSubmit = handleSubmit(async (values, actions) => {
// Send data to the API
const response = await client.post('/users/', values);
// ...
// set single field error
if (response.errors.email) {
actions.setFieldError('email', response.errors.email);
}
// set multiple errors, assuming the keys are the names of the fields
// and the values is the error message
actions.setErrors(response.errors);
});
```
Here is an example that sets form errors after submission, usually you will have a backend API that returns the errors:
================================================
FILE: docs/src/pages/guide/composition-api/helpers.mdx
================================================
---
layout: ../../../layouts/PageLayout.astro
title: Composition Helpers
description: Composition API helpers
menuTitle: Helpers
order: 5
---
Aside from `useField` and `useForm` and `useFieldArray`, these are a collection of simple functions that you can use to opt-in specific parts of vee-validate features like form state and various actions you can perform on fields and forms.
Here are a few examples of what you can build with these functions:
- A custom submission progress component
- A custom error message component.
- A form validity indicators
- reset buttons or submit buttons
Here is a list of the functions available that you can use:
- `useFieldError` Gives access to a single field's first error message
- `useFormErrors` Gives access to the entire error bag of the form
- `useIsFieldDirty` If a field is dirty
- `useIsFormDirty` If the form is dirty (form contains at least one dirty field)
- `useIsFieldTouched` If a field is touched
- `useIsFormTouched` If the form is touched (form contains at least one touched field)
- `useIsFieldValid` If a field is valid
- `useIsFormValid` If all fields are **validated and valid**
- `useValidateField` Returns a function that validates a specific field
- `useValidateForm` Returns a function that validates the entire form
- `useResetForm` Resets the form to its initial state
- `useSubmitForm` Creates a submission function that validates and submits the form (even if no `form` element is involved)
- `useIsSubmitting` If the form is currently submitting
- `useIsValidating` If the form is currently validating by validate function
- `useSubmitCount` The number of times the user attempted to submit the form
- `useFieldValue` Returns a specific fields' current value
- `useFormValues` Returns the current form field values
For more information about the functions, you can head over to the [API reference and check them out](/api/composition-helpers).
================================================
FILE: docs/src/pages/guide/composition-api/nested-objects-and-arrays.mdx
================================================
---
layout: ../../../layouts/PageLayout.astro
title: Nested Objects and Arrays
description: Structuring form values in nested paths in objects or arrays
order: 3
next:
path: guide/composition-api/custom-inputs
title: Custom Inputs
description: Building input components with the composition API
intro: |
You've learned a lot about forms so far, but that's not all. Just like how vee-validate makes it easy to build forms, it also offers tools to help you build custom input components with the composition API. Enter `useField()`.
---
import DocTip from '@/components/DocTip.vue';
import DocBadge from '@/components/DocBadge.vue';
import Repl from '@/components/MdxRepl.vue';
# Nested Objects and Arrays
vee-validate supports nested objects and arrays by using field path syntax to indicate a field's path. This allows you to structure forms easily to make data mapping straightforward without having to deal with flat form values.
## Nested Objects
You can specify a field to be nested in an object using dot paths, like what you would normally do in JavaScript to access a nested property. The field's `name` acts as the path for that field in the form values:
```js
const { defineInputBinds } = useForm();
const twitterLink = defineInputBinds('links.twitter');
const githubLink = defineInputBinds('links.github');
```
Submitting the previous form would result in the following values being passed to your handler:
```js
{
"links": {
"twitter": "https://twitter.com/logaretm",
"github": "https://github.com/logaretm"
}
}
```
Here is a live example so you can see it in action.
You are not limited to a specific depth, you can nest as much as you like.
## Nested Arrays
Similar to objects, you can also nest your values in an array, using square brackets just like how you would do it in JavaScript.
```js
const { defineInputBinds } = useForm();
const twitterLink = defineInputBinds('links[0]');
const githubLink = defineInputBinds('links[1]');
```
Here is the same example as above but in array format:
Submitting the previous form would result in the following values being passed to your handler:
```js
{
"links": [
"https://twitter.com/logaretm",
"https://github.com/logaretm"
]
}
```
vee-validate will only create nested arrays if the path expression is a complete number, for example, paths like `some.nested[0path]` will not create any arrays because the `0path` key is not a number. However `some.nested[0].path` will create the array with an object as the first item.
## Avoiding Nesting
If your fields' names are using the dot notation and you want to avoid the nesting behavior which is enabled by default, all you need to do is wrap your field names in square brackets (`[]`) to disable nesting for those fields.
```js
const { defineInputBinds } = useForm();
const twitter = defineInputBinds('[links.twitter]');
const github = defineInputBinds('[links.github]');
```
Submitting the previous form would result in the following values being passed to your handler:
```js
{
"links.twitter": "https://twitter.com/logaretm",
"links.github": "https://github.com/logaretm"
}
```
Here is a live example on that:
## Field Arrays
Field arrays are a special type of nested array fields, they are often used to collect repeatable pieces of data or repeatable forms. They are often called "repeatable fields".
To set up a repeatable block of the form, you can use `useFieldArray` to help you manage the array values and operations. It requires a form context to be present so `useForm` must be called before you use `useFieldArray` either in parent component or in the same component.
```js
import { useForm, useFieldArray } from 'vee-validate';
useForm();
const { remove, push, fields } = useFieldArray('users');
```
The `useFieldArray` exposes a few properties and functions to help you manage the array fields, the most special one is the `fields` array which contains the array items and represents their current value in the form. You will use `fields` as an iteration source to render the array items.
Here is an example of a repeatable block of fields, we mutate the field value with `v-model` directly on the iteration item value.
Notice that we used `field.key` as the key of the iteration, this is because vee-validate generates a unique key for each array item so you can rely it on without having to generate them yourself.
The `key` property generated on array items is not an index. It is a unique identifier for the array item that is independent of the array index, so you should not be using it to reference field names.
### Field Array Paths
When calling `useFieldArray` you need to provide a `name` prop which is the path of the array starting from the root form value, you can use dot notation for object paths or indices for array paths.
Here are a few examples:
_*Iterate over the `users` array:*_
```js
const { remove, push, fields } = useFieldArray('users');
```
_*Iterate over the `domains` inside `settings.dns` object:*_
```js
const { remove, push, fields } = useFieldArray('settings.dns.domains');
```
### Array Helpers
The `` function provides the following properties and functions:
- `fields`: a **read-only** version of your array field items, it includes some useful properties like `key`, `isFirst` and `isLast`, the actual item value is inside `.value` property. You should use it to iterate with `v-for`.
- `push(item: any)`: adds an item to the end of the array.
- `prepend(item: any)`: adds an item to the start of the array.
- `insert(idx: number, item: any)`: Inserts an array item at the specified index.
- `remove(idx: number)`: removes the item with the given index from the array.
- `swap(idxA: number, idxB: number)`: Swaps two array elements by their indexes.
- `replace(items: any[])`: Replaces the entire array values with the given items.
- `update(idx: number, value: any)`: Updates an array item value at the specified index.
- `move(oldIdx: number, newIdx: number)`: Moves an array item to a different position within the array.
[Read the API reference](/api/use-field-array) for more information.
## Caveats
### Paths creation and destruction
vee-validate creates the paths inside the form data automatically but lazily, so initially, your form values won't contain the values of the fields unless you provide initial values for them. It might be worthwhile to provide initial data for your forms with nested paths.
When fields get unmounted like in the case of conditional rendered fields with `v-if` or `v-for`, their path will be destroyed just as it was created if they are the last field in that path. So you need to be careful while accessing the nested field in `values` inside your submission handler.
Path destruction can be annoying when dealing with multi-step forms or tabbed forms where you want all the values to be available even when the fields are unmounted. You can control this behavior by passing `keepValueOnUnmount` prop to the `useField` function or you can do it for all the fields by passing `keepValuesOnUnmount` to the `useForm` function.
Note that the priority of this configuration follows the field config first then it fallbacks to the form's config.
```js
import { useForm } from 'vee-validate';
// keep all values when their fields get unmounted
const { values } = useForm({
keepValuesOnUnmount: true,
});
```
```js
import { useField } from 'vee-validate';
// this field value will be removed
const field = useField('field', undefined, {
keepValueOnUnmount: false,
});
```
### Referencing Errors
When referencing errors using `errors` object returned from the `useForm` function. Make sure to reference the field name in the same way you set it on the `name` argument for that field. So even if you avoid nesting you should always include the square brackets. In other words `errors` do not get nested, they are always flat.
Since vee-validate supports `yup` and `zod` schemas, referencing the nested fields may vary depending on how you are specifying the schema.
If you are using yup, you can utilize the nested `yup.object` or `yup.array` schemas to provide validation for your nested fields, here is an example:
You can [visit this link](/examples/array-fields) for a practical example using nested arrays.
================================================
FILE: docs/src/pages/guide/devtools.mdx
================================================
---
layout: ../../layouts/PageLayout.astro
title: Devtools Plugin
description: Using the vee-validate Vue.js devtools plugin
order: 7
next:
path: guide/testing
title: Testing
description: Testing form validation in your apps
new: true
---
import DocTip from '@/components/DocTip.vue';
import DocBadge from '@/components/DocBadge.vue';
# Devtools Plugin
vee-validate ships with a Vue.js devtools plugin that allows you to inspect your forms. The terms "devtools plugin" or "plugin" in this page will refer to vee-validate's devtools plugin from now on.
The devtools plugin is useful for debugging and inspecting your forms. A common situation is not having any clues on why a form isn't submitting, the devtools plugin exposes to you all of the validation state giving you insight for your forms behavior.
Since vee-validate doesn't require any app configuration, the devtools plugin is auto installed when you use `useField` or `useForm` or their component counterpart `` and ``.
Note that the plugin won't be installed in the following cases:
- You are using the umd builds via CDN
- Your `process.env.NODE_ENV` is set to `production` or `test`
That means the plugin is only available to the workflows that employ either webpack or vite where `process.env.NODE_ENV` is available.
## The Inspector
The devtools plugin adds a new "vee-validate" inspector that allows you to view your form state, at the moment all the properties are read only.
To use the vee-validate inspector, switch from the `components` inspector to the `vee-validate` inspector:
When working with multiple forms, you can distinguish between them by their name. The name of the form can be set
using the `name` prop on the `` component or the `useForm` composable.
## Disabling the plugin
If the plugin is causing you issues, you can disable it explicitly from the vue-devtools plugin page.
Also please don't forget to report the issue [here](https://github.com/logaretm/vee-validate/issues/new?assignees=&labels=&template=bug_report.yaml).
This short video shows how to disable the vee-validate devtools plugin:
================================================
FILE: docs/src/pages/guide/global-validators.mdx
================================================
---
layout: ../../layouts/PageLayout.astro
title: Global Validators
description: Defining global rules to be used throughout your web app
order: 5
next:
path: guide/i18n
title: Localization (i18n)
description: Localization support with the first party module and other providers
---
import LiveExample from '@/components/LiveExample.vue';
import DocTip from '@/components/DocTip.vue';
# Global Validators
Sometimes you are building an application that is form-heavy and needs to validate forms frequently, like an admin dashboard or a form-based application. importing validation rules every time you need them can be quite tedious.
VeeValidate allows you to define validation rules globally on the app-level which in turn can allow you to express your rules in a minimal syntax that is inspired by the [Laravel framework's validation syntax](https://laravel.com/docs/validation).
## Defining Global Validators
You can define a global validator using the `defineRule` function exported by vee-validate:
```js
import { defineRule } from 'vee-validate';
```
The `defineRule` function accepts a rule name that acts as an identifier for that validation rule, the second argument is the validator function that will verify the field value. Here is an example of a simple `required` and an `email` rule:
```js
import { defineRule } from 'vee-validate';
defineRule('required', value => {
if (!value || !value.length) {
return 'This field is required';
}
return true;
});
defineRule('email', value => {
// Field is empty, should pass
if (!value || !value.length) {
return true;
}
// Check if email
if (!/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,4}/.test(value)) {
return 'This field must be a valid email';
}
return true;
});
```
The validator function is a simple function that receives the current field value as the first argument, and it should return:
- `true` if the validation passed
- `string` if the validation failed and there is an error message to display
- `false` if validation fails, in that case, vee-validate will try to generate an error message using `config.defaultMessage`
- `Promise` if you have an asynchronous rule, the promise must either resolve to `string` or `true`
You should make the `defineRule` calls in your application entry-point file to make sure your forms have access to them, otherwise, you may risk a form not being able to use some global rules because they weren't defined then. Here are some common entry points:
- In vue-cli applications that would be the `src/main.js` file
- In a Nuxt application, you need to create a `plugins/vee-validate.js` file and register it in `nuxt.config.js`
### Using Global Validators
Now that you've defined your validators, for example, the `email` and `required` rules. You can pass them directly to `` component's `rules` prop like this:
```vue-html
```
Notice that to define multiple rules you have to place a `|` (pipe) character between your rules as a separator.
## Configuring Global Validators
Sometimes your rules require more information to work properly, for example, if we want to define a `minLength` rule it won't be very useful to hard code the character limit, instead, it should receive it per field.
VeeValidate passes rules arguments or (configuration) as the second argument to the validator function which is often an array containing the arguments in the same order they were passed in. Here is an example defining a `minLength` rule:
```js
import { defineRule } from 'vee-validate';
defineRule('minLength', (value, [limit]) => {
// The field is empty so it should pass
if (!value || !value.length) {
return true;
}
if (value.length < limit) {
return `This field must be at least ${limit} characters`;
}
return true;
});
```
And then you can use it on the `Field` component like this:
```vue-html
```
Note that to pass arguments to rules, you need to place a colon `:` character to signify the beginning of rules. You can pass multiple arguments as a comma-separated list. Here is an example for a `minMax` rule:
```js
import { defineRule } from 'vee-validate';
defineRule('minMax', (value, [min, max]) => {
// The field is empty so it should pass
if (!value || !value.length) {
return true;
}
const numericValue = Number(value);
if (numericValue < min) {
return `This field must be greater than ${min}`;
}
if (numericValue > max) {
return `This field must be less than ${max}`;
}
return true;
});
```
Then you can use it like this:
```vue-html
```
## Schema Validation
The [Form-level validation](/guide/components/validation#form-level-validation) feature isn't limited to `yup` validators, you can define your global validators and define them in the same way as the previous examples in the `Form` component `validation-schema` prop.
Here is an example that uses all the rules we've defined prior in this page in a form validation schema:
```vue
```
This makes vee-validate extremely compatible with Laravel's Request validation and potentially opens the door to make your forms completely API-driven, eliminating the maintenance burden of syncing validation rules between frontend and backend.
## Cross-Field Validation
Assuming you want to create a rule that verifies that a field matches another, like a password confirmation scenario. Because globally defined rules do not have scope access to other values you may have in the component, vee-validate sends a third argument to your global validators which is a `ValidationContext` that carries useful information about the form and field being validated.
So assuming you want to build a `confirmed` rule, you would make it configurable by accepting the `target` field name and you can use the `ValidationContext.form` object to access its value:
```js
import { defineRule } from 'vee-validate';
defineRule('confirmed', (value, [target], ctx) => {
if (value === ctx.form[target]) {
return true;
}
return 'Passwords must match';
});
```
Here is an example of the two fields using that rule:
```vue-html
```
There is a shorthand for this using `@` prefix before specifying arguments, this tells vee-validate to automatically swap the specified field value in the arguments array:
```js
import { defineRule } from 'vee-validate';
defineRule('confirmed', (value, [target]) => {
if (value === target) {
return true;
}
return 'Passwords must match';
});
```
```vue-html
```
This allows you to create more concise rules, you can reference any number of fields using this way.
## Object Expressions
There is another way to use global validators which is more expressive by using JavaScript objects to describe the validation for your fields. For example this:
```js
'required|between:0,10';
```
Could be rewritten as an object like this
```js
{ required: true, between: [0, 10] }
```
This makes defining rules more expressive and less limited by the string format.
For dynamic expressions, you can use computed properties in the same way to define dynamic validation rules.
## @vee-validate/rules
VeeValidate offers a wide range of common validators that you can use as global validators, they are packed in a separate package under the `@vee-validate/rules` namespace
```sh
yarn add @vee-validate/rules
# or with npm
npm install @vee-validate/rules
```
You can then start importing and defining rules globally:
```js
import { defineRule } from 'vee-validate';
import { required, email, min } from '@vee-validate/rules';
defineRule('required', required);
defineRule('email', email);
defineRule('min', min);
```
Or you can globally define all the available rules in the `@vee-validate/rules` package:
```js
import { defineRule } from 'vee-validate';
import { all } from '@vee-validate/rules';
Object.entries(all).forEach(([name, rule]) => {
defineRule(name, rule);
});
```
## Caveats
- Be careful of having too many global rules as this can slow down your initial website load time due to the large initial bundle size
- It is recommended to treat your validation rules as pure functions, meaning they only operate with the information given to them
- Having small, pure global validations is preferable to allow reusing them across the app
- You could possibly trigger an infinite render-loop when using the [object expressions](/guide/global-validators#object-expressions) to define your validations for a field, read the [linked section](/guide/global-validators#object-expressions) for a workaround
## Available Rules
### Playground
Here is a live demo where you can view and test all the global validators live
#### alpha
The field under validation may only contain alphabetic characters.
```vue-html
```
#### alpha_dash
The field under validation may contain alphabetic characters, numbers, dashes, or underscores.
```vue-html
```
#### alpha_num
The field under validation may contain alphabetic characters or numbers.
```vue-html
```
#### alpha_spaces
The field under validation may contain alphabetic characters or spaces.
```vue-html
```
#### between
The field under validation must have a numeric value bounded by a minimum value and a maximum value.
```vue-html
```
| Param Name | Required? | Description |
| ---------- | --------- | ------------------ |
| `min` | **yes** | The minimum value. |
| `max` | **yes** | The maximum value. |
#### confirmed
The field under validation must have the same value as the confirmation field.
```vue-html
```
| Param Name | Required? | Description |
| ---------- | --------- | ---------------------------------------------------------------------------- |
| `target` | **yes** | The other field's `name` value, must use `@` to prefix the target field name |
Any fields defined to have this rule must have a `` parent in their hierarchy or `useForm()` called on their parent hierarchy.
#### digits
The field under validation must be numeric and have the specified number of digits.
```vue-html
```
| Param Name | Required? | Description |
| ---------- | --------- | ----------------------------- |
| `length` | **yes** | The number of digits allowed. |
#### dimensions
The file added to the field under validation must be an image (jpg,svg,jpeg,png,bmp,gif) having the exact specified dimension.
```vue-html
```
| Param Name | Required? | Description |
| ---------- | --------- | --------------------- |
| `width` | **yes** | The width in pixels. |
| `height` | **yes** | The height in pixels. |
#### email
The field under validation must be a valid email.
```vue-html
```
#### not_one_of
The field under validation must have a value that is not in the specified list. **Uses double equals** for checks.
```vue-html
```
`not_one_of` accepts an infinite number of params, each is a value that is disallowed.
#### ext
The file added to the field under validation must have one of the extensions specified.
```vue-html
```
`ext` accepts an infinite number of arguments representing extensions. ex: `ext:jpg,png,bmp,svg`.
#### image
The file added to the field under validation must have an image mime type (image/\*).
```vue-html
```
#### integer
The field under validation must be a valid integer value. Doesn't accept exponential notation.
```vue-html
```
#### is
The field under validation must match the given value, uses strict equality.
```vue-html
```
| Param Name | Required? | Description |
| ---------- | --------- | ----------------------------------------------------------- |
| `value` | **yes** | A value of any type to be compared against the field value. |
#### is_not
The field under validation must not match the given value, uses strict equality.
```vue-html
```
| Param Name | Required? | Description |
| ---------- | --------- | ----------------------------------------------------------- |
| `value` | **yes** | A value of any type to be compared against the field value. |
#### length
The field under validation must exactly have the specified number of items, only works for iterables.
Allowed Iterable values are `string`, `array`, and any object that can be used with `Array.from`.
```vue-html
```
| Param Name | Required? | Description |
| ---------- | --------- | ----------------------------------------------------------------------------- |
| `length` | **yes** | A numeric value representing the exact number of items the value can contain. |
#### max
The field under validation length may not exceed the specified length.
```vue-html
```
| Param Name | Required? | Description |
| ---------- | --------- | -------------------------------------------------------------- |
| `length` | **yes** | A numeric value representing the maximum number of characters. |
#### max_value
The field under validation must be a numeric value and must not be greater than the specified value.
```vue-html
```
| Param Name | Required? | Description |
| ---------- | --------- | -------------------------------------------------------- |
| `max` | **yes** | A numeric value representing the greatest value allowed. |
#### mimes
The file type added to the field under validation should have one of the specified mime types.
```vue-html
```
`mimes` accepts an infinite number of arguments that are formatted as file types. EG: `mimes:image/jpeg,image/png`.
You can use '\*' to specify a wild card, something like `mimes:image/*` will accept all image types.
#### min
The field under validation length should not be less than the specified length.
```vue-html
```
| Param Name | Required? | Description |
| ---------- | --------- | -------------------------------------------------------------- |
| `length` | **yes** | A numeric value representing the minimum number of characters. |
#### min_value
```vue-html
```
The field under validation must be a numeric value and must not be less than the specified value.
| Param Name | Required? | Description |
| ---------- | --------- | -------------------------------------------------------- |
| `min` | **yes** | A numeric value representing the smallest value allowed. |
#### numeric
The field under validation must only consist of numbers.
```vue-html
```
#### one_of
The field under validation must have a value that is in the specified list. **Uses double equals** for checks.
```vue-html
```
`one_of` takes an infinite number of params, each is a value that is allowed.
#### regex
The field under validation must match the specified regular expression.
```vue-html
```
| Param Name | Required? | Description |
| ---------- | --------- | --------------------------------------------------------- |
| `pattern` | **yes** | A regular expression instance or string representing one. |
You should not use the pipe '|' or commas ',' within your regular expression when using the string rules format as it will cause a conflict with how validators parsing works. You should use the object format of the rules instead as shown in the last snippet
When using the `regex` rule, using the `g` flag may result in unexpected falsy validations. This is because vee-validate uses the same instance across validation attempts.
#### required
The field under validation must have a non-empty value. By default, all validators pass the validation if they have "empty values" unless they are required. Those empty values are empty strings, `undefined`, `null`, `false`, and empty arrays.
```vue-html
```
#### size
The file size added to the field under validation must not exceed the specified size in kilobytes.
```vue-html
```
| Param Name | Required? | Description |
| ---------- | --------- | ----------------------------------- |
| `size` | **yes** | The maximum file size in kilobytes. |
#### url
The field under validation must be a valid url. You can pass a `pattern` if you need the url to be more restricted.
```vue-html
```
| Param Name | Required? | Description |
| ---------- | --------- | --------------------------------------------------------- |
| `pattern` | **no** | A regular expression instance or string representing one. |
================================================
FILE: docs/src/pages/guide/i18n.mdx
================================================
---
layout: ../../layouts/PageLayout.astro
title: Localization (i18n)
description: Localization support with the first party module and other providers
order: 6
next:
path: guide/devtools
title: Devtools Plugin
description: Using the vee-validate Vue.js devtools plugin
---
import LiveExample from '@/components/LiveExample.vue';
import DocTip from '@/components/DocTip.vue';
# Localization (i18n)
This guide only addresses generating error messages for [globally defined validators](/guide/global-validators) using vee-validate's own `@vee-validate/i18n` plugin.
If you are using vee-validate with yup, then you should check out [yup's localization guide](https://github.com/jquense/yup#localization-and-i18n). If you are using another library for data validation, check their i18n capabilities.
## Global Message Generator
vee-validate exposes a global config called `generateMessage` which is a function that should return a string. Whenever any globally defined rule returns a falsy value the `generateMessage` will be called and its result will be used as an error message for that rule.
The message generator function has the following type:
```ts
interface FieldContext {
field: string; // The field's name or label (see next section)
value: any; // the field's current value
form: Record; // other values in the form
rule: {
name: string; //the rule name
params?: any[]; // any params sent to it
};
}
type ValidationgenerateMessage = (ctx: FieldContext) => string;
```
With this information, you could create message handlers with any kind of 3rd party libraries. To register a message generator use the `configure` function exposed by vee-validate:
```js
import { configure } from 'vee-validate';
configure({
generateMessage: context => {
return `The field ${context.field} is invalid`;
},
});
```
### Custom Labels
If you want to display different field names in your error messages, the `` component accepts a `label` prop which allows you to display better names for your fields in their generated messages. Here is an example:
```vue-html
```
The generated message will use `nice name` instead of the badly formatted one.
## Using @vee-validate/i18n
### Overview
The `@vee-validate/i18n` contains a simple message generator function that you can use to generate localized messages from JSON objects:
First, you need to install the `@vee-validate/i18n` package:
```sh
yarn add @vee-validate/i18n
# or with npm
npm install @vee-validate/i18n
```
Import the `localize()` function from `@vee-validate/i18n` which returns a message generator function:
```js
import { defineRule, configure } from 'vee-validate';
import { required } from '@vee-validate/rules';
import { localize } from '@vee-validate/i18n';
// Define the rule globally
defineRule('required', required);
configure({
// Generates an English message locale generator
generateMessage: localize('en', {
messages: {
required: 'This field is required',
},
}),
});
```
If you have multiple locales in your application, you can add them like this:
```js
import { defineRule, configure } from 'vee-validate';
import { required } from '@vee-validate/rules';
import { localize } from '@vee-validate/i18n';
// Define the rule globally
defineRule('required', required);
configure({
generateMessage: localize({
en: {
messages: {
required: 'This field is required',
},
},
ar: {
messages: {
required: 'هذا الحقل مطلوب',
},
},
}),
});
```
You can change the locale using `setLocale` function exported by the `@vee-validate/i18n` anywhere in your application:
```js
import { setLocale } from '@vee-validate/i18n';
setLocale('ar');
```
To save you a lot of time translating `@vee-validate/rules` messages to your language, the awesome community around vee-validate already contributed over 40+ languages that you can use directly in your application and get started quickly. The localized files include localized messages for all the [global rules provided by @vee-validate/rules package](/guide/global-validators#available-rules).
You can import the needed locale from the `@vee-validate/i18n/dist/locale/{localeCode}.json` and they can be passed directly to the localize function. This snippet adds the English and Arabic localized messages for all the rules of `@vee-validate/rules` package into the message generator function:
```js
import { configure } from 'vee-validate';
import { localize } from '@vee-validate/i18n';
import en from '@vee-validate/i18n/dist/locale/en.json';
import ar from '@vee-validate/i18n/dist/locale/ar.json';
configure({
generateMessage: localize({
en,
ar,
}),
});
```
### Localizing Field Names
To localize the field name with the `@vee-validate/i18n` package, you can add a `names` property to your dictionaries containing the translated names of the fields.
```js
import { configure } from 'vee-validate';
import { localize } from '@vee-validate/i18n';
configure({
generateMessage: localize({
en: {
names: {
age: 'Age',
},
},
ar: {
age: 'السن',
},
}),
});
```
Then whenever a message is generated for a global rule, vee-validate will try to match the field name with the `names` property found in the active locale.
This is such an example:
## Custom messages for specific fields
You may want to override specific rule messages for specific fields, you can do this by calling `localize` with the specific messages object:
```js
import { localize } from '@vee-validate/i18n';
localize('en', {
fields: {
password: {
required: 'Hey! Password cannot be empty',
},
},
});
// Or update multiple languages
localize({
en: {
fields: {
password: {
required: 'Hey! Password cannot be empty',
},
},
},
});
```
You can call `localize` anywhere in your component initialization, ideally before any error is generated so either `mounted` or `setup` should be safe to call `localize`.
### Placeholder Interpolation
Your messages can be more complex than `required`, for example a `between` rule would need access to the params values to be able to produce a meaningful error message, the `@vee-validate/i18n` plugin comes with interpolation support for various placeholders, consider this example:
```js
import { defineRule, configure } from 'vee-validate';
import { between } from '@vee-validate/rules';
import { localize } from '@vee-validate/i18n';
// Define the rule globally
defineRule('between', between);
configure({
// Generates an English message locale generator
generateMessage: localize('en', {
messages: {
between: 'The {field} value must be between 0:{min} and 1:{max}',
},
}),
});
```
The `{field}` placeholder will be replaced with the field name, and `0:{min}` and `1:{max}` will be replaced with the rule arguments. Note that the indices that prefix each param name are recommended because the interpolation will need to know the order of the arguments because you may define your global rules in one of `object` or `array` or `string` formats, and thus the interpolation process needs to know both argument names and their order if array params or strings are used.
You can also interpolate the other fields in the form by using their names as placeholders.
Here is an example that show cases interpolation for different cases:
#### Custom Interpolation Prefix and Suffix
You also have the ability to customize the `prefix` and `suffix` of the interpolated values, by default they are `{` and `}` respectively.
Configure them by passing a third parameter of `InterpolateOptions` to the `localize` function:
```js
import { defineRule, configure } from 'vee-validate';
import { between } from '@vee-validate/rules';
import { localize } from '@vee-validate/i18n';
// Define the rule globally
defineRule('between', between);
configure({
// Generates an English message locale generator
generateMessage: localize(
'en',
{
messages: {
// use double `{{` and `}}` i18next-like curly braces for the interpolated values, instead of the default `{` and `}`
between: `The {{field}} field must be between 0:{{min}} and 1:{{max}}`,
},
},
{
prefix: '{{',
suffix: '}}',
},
),
});
```
### Loading Locale From CDN
If you are using Vue.js over CDN, you can still load the locale files without having to copy them to your code, the `@vee-validate/i18n` library exposes a `loadLocaleFromURL` function that accepts a URL to a locale file.
```html
```
Here is an example of the previous snippet:
================================================
FILE: docs/src/pages/guide/migration.mdx
================================================
---
layout: ../../layouts/PageLayout.astro
title: Migration Guide
description: How to migrate from vee-validate v4 to v5
order: 10
---
# Migrating from v4 to v5
vee-validate v5 is a major release that brings support to [standard schema](https://standardschema.dev/) libraries like zod, valibot, yup, and more.
This means most of the companion packages like `@vee-validate/zod`, `@vee-validate/yup`, `@vee-validate/valibot` are no longer needed and are now deprecated.
## Changes to Nuxt Module
The nuxt module won't suggest installing any packages anymore since most providers that were supported in v4 are now supported in v5 via standard schema API.
## Changes to schema behavior
Since vee-validate v5 is considered schema agnostic, you lose some features that were previously possible with each dedicated validation provider.
- Resolving `required` meta flag is no longer supported from schemas.
- Using defaults to initialize the form values is no longer supported from schemas.
While these features are critical to many apps, the standard schema spec does not provide a way to do that at the moment. Alternatives are being considered via external packages at the moment.
## Replace Typed Schema calls
Typed schemas were a way for vee-validate v4 to support a common interface for multiple validation providers. However, there is a community driven package called [standard schema](https://standardschema.dev/) that provides a common interface for multiple validation providers that is becoming very popular and is already supported by the most popular validation providers.
So in v5 we now introduced support for standard schema libraries, which means you can use any of the most popular validation providers with vee-validate v5 without installing any resolvers or adapter packages. This includes almost all the previous providers like zod, yup, and valibot.
The only needed step is to remove all calls to `toTypedSchema` and replace them with the standard schema library of your choice.
### Zod
vee-validate is compatible with zod 3.24.0 and above.
```ts
import { z } from 'zod';
// v4
const schema = toTypedSchema(z.object({ name: z.string().min(1) }));
// v5 - remove the call to `toTypedSchema`
const schema = z.object({ name: z.string().min(1) });
const { value, errorMessage } = useForm({ validationSchema: schema });
```
### Yup
You will need to upgrade `yup` to 1.7.0 or above since the standard schema support was added in that version.
#### If you are using `@vee-validate/yup`
```ts
import * as yup from 'yup';
// v4
const schema = toTypedSchema(yup.object({ name: yup.string().min(1) }));
// v5 - remove the call to `toTypedSchema`
const schema = yup.object({ name: yup.string().min(1) });
const { value, errorMessage } = useForm({ validationSchema: schema });
```
#### If you are using yup directly
Continue using your yup schema as you've been doing in the past. You will start getting type safety features out of the box, just make sure you are using yup 1.7.0 or above.
### Valibot
vee-validate is compatible with valibot 1.0 and above.
```ts
import * as v from 'valibot';
// v4
const schema = toTypedSchema(v.object({ email: v.pipe(v.string(), v.email()) }));
// v5 - remove the call to `toTypedSchema`
const schema = v.object({ email: v.pipe(v.string(), v.email()) });
const { value, errorMessage } = useForm({ validationSchema: schema });
```
### Joi
vee-validate is compatible with Joi v18.0.0 and above.
```ts
import * as Joi from 'joi';
// v4
const schema = toTypedSchema(Joi.object({ email: Joi.string().email() }));
// v5 - remove the call to `toTypedSchema`
const schema = Joi.object({ email: Joi.string().email() });
const { value, errorMessage } = useForm({ validationSchema: schema });
```
================================================
FILE: docs/src/pages/guide/overview.mdx
================================================
---
layout: ../../layouts/PageLayout.astro
title: Overview
description: Getting started with VeeValidate
order: 1
---
import DocTip from '@/components/DocTip.vue';
# Why vee-validate
"Forms" is a difficult subject in frontend development. Not only do you have to deal with ensuring that correct values are submitted, but you should also provide a pleasant UX for your users.
Building forms from scratch is a lot of work and you probably won't cover all your future needs as your requirements change over time, and as you add more features.
**The time you spend working on a custom form solution is better spent building your application logic**.
Most form libraries will save you a lot of time, but `vee-validate` tackles the major pain points of forms and then gets out of your way, some of those are:
- Form state and value tracking
- UX
- Synchronous and Asynchronous Validation
- Handling submissions
vee-validate tries to handle all of the above and more by providing abstractions to these problems without any UI. This could be viewed as a double-edged sword, however, overriding UI and styles was the downfall of many component libraries and design languages.
Because of that, vee-validate abstracts away the hard parts into pure logic compositions that you can add to your existing UI and component. There is nothing to override, there is no hidden cost. You can also use vee-validate to power your components internally, and as a result you can build up your form library without having to think about the hard parts.
A great showcase of this approach is how vee-validate seamlessly [integrate with almost every component UI library](/examples/ui-libraries/) for Vue.js out there without any special treatment or hacks.
## Getting Started
vee-validate makes use of two flavors to add validation to your forms.
- **Composition API**: This is the best way to use vee-validate as it allows seamless integrations with your existing UI, or any 3rd party component library.
- **Higher-order components (HOC)**: This approach is easy to use and is strictly used within the template, you can use it if you have simple forms and don't want to write a lot of JavaScript.
Whichever approach you prefer to use, both flavors can be used interchangeably. So you can mix and match between the two approaches as needed.
Most examples in the docs use the new [script setup](https://vuejs.org/api/sfc-script-setup.html#script-setup) SFC syntax for brevity. In case you're having difficulty following along, take some time to learn about it.
### Using a package manager
For a more modern workflow with a bundler, you can install vee-validate using a package manager like `yarn`, `npm` or `pnpm`:
```sh
yarn add vee-validate
# or
npm i vee-validate --save
# or
pnpm add vee-validate
```
### Using a script tag
You can use vee-validate with a script tag and a CDN, import the library like this:
```html
```
This will inject a `VeeValidate` global object, which you will use to access the various components and functions exposed by vee-validate.
================================================
FILE: docs/src/pages/guide/testing.mdx
================================================
---
layout: ../../layouts/PageLayout.astro
title: Testing
description: Testing form validation in your apps
order: 8
---
# Testing
vee-validate has many tests of its own that cover almost every functionality, but if you find yourself needing to test vee-validate integration with your forms and fields, this guide should offer some guidance into the best practices and the caveats of doing that.
## Waiting for async validation
vee-validate does all of the work asynchronously. This means whenever you trigger a validation using explicit `validate()` calls or form submissions or `change` events, you still need to "flush" the promises to assert the state you expect.
For example, the following test will fail
```js
import { useField } from 'useField';
const SomeComponent = {
template: `
{{ errorMessage }}
`,
setup() {
const { value, errorMessage } = useField('name', value => {
return value ? true : 'field is required';
});
return {
value,
errorMessage,
};
},
};
test('it validates', async () => {
// assuming you have a mounting helper
mount(SomeComponent);
const input = document.querySelector('input');
input.value = '';
input.dispatchEvent(new Event('change'));
// ❌ Fails
expect(document.querySelector('span').textContent).toBe('Field is required');
});
```
To wait for the validation to execute and render the error message, you can use the `flush-promises` npm package to wait for all promises to fulfill and also coupled with `wait-for-expect`.
```js
import flushPromises from 'flush-promises';
import waitForExpect from 'wait-for-expect';
test('it validates', async () => {
// assuming you have a mounting helper
mount(SomeComponent);
const input = document.querySelector('input');
input.value = '';
input.dispatchEvent(new Event('change'));
// wait for the promises to fulfill
await flushPromises();
await waitForExpect(() => {
// ✅ Now passes
expect(document.querySelector('span').textContent).toBe('Field is required');
});
});
```
vee-validate may run validation in batches to improve performance which isn't always detected by `flush-promises`, so using both is recommended here.
## Testing error messages
Messages can change for the simplest of reasons, for example, grammar or punctuation changes could break your tests if you test against the literal contents of the message.
Ideally, you shouldn't rely on validation messages staying the same for your tests to pass, in any of the iterations when you work on your product you don't want your tests to fail just because of that.
So instead of testing the literal messages, you want to test if they get any kind of validation message regardless of their content. There are a few suggestions to remedy that:
### Testing message existence
You can test if the error field contains any message at all, this is useful if you rely on error messages from 3rd party, like the `@vee-validate/i18n` package which changes its messages frequently due to constant updates and fixes by the awesome contributors from all over the world.
```js
// ❌ Breaks easily
expect(errorElement.textContent).toBe('Field is required');
// ✅
expect(errorElement.textContent).toBeTruthy();
```
### Testing partial contents
Another approach is to test that the messages contain the critical information needed for the user to understand how to fix their input. This assumes you have some idea of the contents of the message:
```js
// ❌ Breaks easily
expect(errorElement.textContent).toBe('Field is required');
// ✅ use `toContain` or similar matching assertions
expect(errorElement.textContent).toContain('required');
```
Of course, this can break easily but still is more flexible than the full literal check.
### Testing actual contents
This approach relies on the fact that you organize your app user-facing strings in dictionary files, meaning messages are deterministic and not sprinkled across your component's code.
```js
import messages from 'strings/validation.js';
// ✅
expect(errorElement.textContent).toBe(messages.required);
```
## Mocking Form and Field Contexts
While this is extremely rare you may need to mock the `FormContext` object or the `FieldContext` object, one of the reasons is to unit test some component that relies on those objects being provided with the `provide/inject` API.
You can import the injection keys for those objects from vee-validate and manually inject your fields/forms.
```js
import { provide } from 'vue';
import { FormContextKey, FieldContextKey } from 'vee-validate';
provide(FormContextKey, MockedForm);
provide(FieldContextKey, MockedField);
```
To learn more about the mock details you should check the source code and see the typescript interfaces for [`FormContext`](https://github.com/logaretm/vee-validate/blob/main/packages/vee-validate/src/types.ts#L145) and [`FieldContext`](https://github.com/logaretm/vee-validate/blob/main/packages/vee-validate/src/types.ts#L66) objects and implement them as mocks.
================================================
FILE: docs/src/pages/index.astro
================================================
---
import HomeLayout from '@/layouts/HomeLayout.astro';
import SponsorButton from '@/components/SponsorButton.vue';
import Icon from '@/components/Icon.vue';
import MainPageExample from '@/components/MainPageExample.vue';
import StarCount from '@/components/StarCount.vue';
import FeatureCard from '@/components/FeatureCard.vue';
import { features } from '@/constants';
import UiLibraries from '@/components/UiLibraries.vue';
const highlights = [
{
title: 'Flexible',
details:
'Offers both declarative components or composable functions API.
vee-validate sets up the foundation for you to form in whatever style you prefer.',
},
{
title: 'Incremental',
details:
'vee-validate can do a lot if you let it. Like tracking values, validation, handling submissions and more.
You may opt-in or out to all of these aspects. You are in control of how much form code you write.',
},
{
title: 'Great DX',
details:
'Vue.js devtools support.
vee-validate makes debugging forms much easier and less of a wild goose chase every time that form does not submit.',
},
];
---
VeeValidate
Painless Vue
forms
VeeValidate is the most popular Vue.js form library. It takes care of value tracking, validation, errors,
submissions and more.
Official vee-validate's Nuxt module
## Features
- Auto import of vee-validate components
- Auto import of vee-validate composables
No types are exposed by default to avoid having conflicts with other libraries, aside from vee-validate's main API components/composables. You can still import them via `vee-validate`.
## Getting Started
In your nuxt project install the vee-validate nuxt module:
```sh
# npm
npm i @vee-validate/nuxt
# pnpm
pnpm add @vee-validate/nuxt
# yarn
yarn add @vee-validate/nuxt
```
Then add the module to your `modules` config in `nuxt.config.ts`:
```ts
export default defineNuxtConfig({
// ...
modules: [
//...
'@vee-validate/nuxt',
],
});
```
## Configuration
You can configure a few aspects of the `@vee-validate/nuxt` module. Here is the config interface:
```ts{3-19}
export default defineNuxtConfig({
// ...
modules: [
//...
[
'@vee-validate/nuxt',
{
// disable or enable auto imports
autoImports: true,
// Use different names for components
componentNames: {
Form: 'VeeForm',
Field: 'VeeField',
FieldArray: 'VeeFieldArray',
ErrorMessage: 'VeeErrorMessage',
},
},
],
],
});
```
You can also use the `veeValidate` config key instead of the array syntax:
```ts{7-16}
export default defineNuxtConfig({
// ...
modules: [
//...
'@vee-validate/nuxt',
],
veeValidate: {
// disable or enable auto imports
autoImports: true,
// Use different names for components
componentNames: {
Form: 'VeeForm',
Field: 'VeeField',
FieldArray: 'VeeFieldArray',
ErrorMessage: 'VeeErrorMessage',
},
},
});
```
================================================
FILE: docs/src/pages/resources.mdx
================================================
---
layout: ../layouts/PageLayout.astro
title: Resources
description: Articles, Tutorials, and Products on VeeValidate
order: 1
---
# Resources
## Talks
- [What's new in vee-validate v4](https://youtu.be/_r6PjzFLbqw) by [Abdelrahman Awad](https://twitter.com/logaretm) - Jul 18, 2020
- [Vue Form Validation w/ VeeValidate](https://www.youtube.com/watch?v=KN1ij6hWVDs) by [Aaron Saunders](https://twitter.com/aaronksaunders) - Apr 30, 2021
## Community Videos
- [Managing Form Validation with Custom Form Components And Vee-Validate Composition API](https://www.youtube.com/watch?v=2ET7IH57XwQ) by [Aaron Saunders](https://twitter.com/aaronksaunders)
## Products
Creative-Tim are using vee-validate in their Vue dashboards, head over to [creative-tim](https://www.creative-tim.com/templates/vuejs?ref=vee-validate) and check their offerings.
================================================
FILE: docs/src/pages/submit-target.astro
================================================
---
import LogQueryStr from '@/components/LogQueryStr.vue';
---
Submit target
================================================
FILE: docs/src/pages/tutorials/basics.mdx
================================================
---
layout: ../../layouts/PageLayout.astro
title: Validation Basics
description: Build a newsletter form with vee-validate
order: 1
---
import LiveExample from '@/components/LiveExample.vue';
# Validation Basics
VeeValidate offers many ways to do form validation, this tutorial will teach you how to do basic form validation using the simplest approach.
## What are we building
In this tutorial, we will be building a "sign up newsletter" form where the user would have to fill a field to complete their sign-up.
## Prerequisites
This tutorial assumes you know:
- Modern JavaScript features like arrow functions and ES modules.
- Vue's [SFC file syntax](https://v3.vuejs.org/guide/single-file-component.html#introduction).
## Setup
It is preferable to use a local development environment to follow along, make sure to have the following:
1. Prepare a Vue 3.x project using the [`vue-cli`](https://cli.vuejs.org/)
Detailed Steps
If not already prepared, install the New Vue CLI
```sh
npm install -g @vue/cli@next
```
Using the `vue-cli`, create a new project and choose Vue 3 template:
```sh
vue create vee-validate-tutorial
```
2. Add `vee-validate` to your project
```sh
yarn add vee-validate
# or
npm install vee-validate --save
```
3. Cleanup the contents of `App.vue`, it should look like the following:
```vue
```
And that's it, now you have an empty Vue project and vee-validate installed.
## Building the Form
First, start by adding some markup, you can start by having a `form` wrapping a few `input` elements.
```vue
```
So far so good, try filling the `email` field with a dummy value like `hello`. Then click the submit button once and see what happens.
You will notice that the form submits and you should see `?email=` added in your URL in the address bar, it should have the same value that you entered in the `email` field.
This is the native HTML form submission behavior. Usually, in modern applications, you don't want that and you prefer to handle submission with JavaScript.
The `novalidate` attribute on the `
