💣 Breaking Changes

• Removed default export from the @vee-validate/rules package which caused issues for ESM importing #4470

This only affects you if you are importing all the rules.

Migration:

- import AllRules from '@vee-validate/rules';
+ import * as AllRules from '@vee-validate/rules';

👕 Types

• useSetFormValues now accepts values generic type parameters (#4475) thanks to @ivan-angjelkoski
• Exported missing internal types causing a build error #4478 (a1414f6)

🆕 New Features

• Added Joi schema support thanks to @lallenfrancisl (#4463), it was sneaked in a previous release tag but it is being announced here to acknowledge that addition.
• Valibot and Yup schemas now merge their default values with the initial form values, allowing you to use each lib's schema defaults more freely (c372718)

👕 TypeScript

This release is aimed at resolving #4421

• useForm#defineComponentBinds is now more strict and provides accurate typings for both modelValue and update:modeValue properties. Previously they were not exposed.

Try the following example.

const { defineComponentBinds } = useForm({
  validationSchema: toTypedSchema(yup.object({
    date: yup.date().required(),
    number: yup.number().required(),
    string: yup.string().required(),
    valueModel: yup.string().required(),
  })),
});

const date = defineComponentBinds('date');
const number = defineComponentBinds('number');
const string = defineComponentBinds('string');
const valueModel = defineComponentBinds('valueModel');

🐛 Bug Fixes

The latest release introduced a bug with detecting external changes to models when the default updateOnValueUpdate is set to true. This release fixes that #4404 (804ec6f)

🐛 Bug fixes

• Silent validation should not mark a field as validated ( b53400e)
• Clone the schema object before validating typed schemas to avoid outputting proxies #4459 (8f680bf)
• Respect validateOnModelUpdate configuration #4451 #4467 (5231f43)

🆕 New features

• feat: added reset options to force values changing to the given values without merging the old ones #4440 (4d8ed7e)

This release updates valibot support to v0.13.0 and replaces the usage of deprecated API methods. #4414 (#4415)

🆕 New features

You can now query fields meta state using isFieldTouched, isFieldDirty, and isFieldValid helpers on useForm.

const { isFieldDirty } = useForm();

isFieldDirty('myField') // true or false

// or compose it to be reactive:
const isFieldDirty  = computed(() => isFieldDirty('myField'));

🐛 Bug Fixes

• Do not warn if a form or a field was resolved closes #4399 (2ff045c)

👕 Types

• Expose all internal types #4409 (73219b4) (4947e88)

🐛 Bug fixes

• handleChange should now infer value as a number from Input type range (5e23dcb)

This release contains a couple of new features

🆕 Composition API setters

Added composition functions to set field and form values, meta, and errors from their child components. The functions are:

• useSetFieldValue: sets a field's value.
• useSetFieldTouched: sets a field's touched state.
• useSetFieldError: sets a field's error message.
• useSetFormValues: sets form values.
• useSetFormTouched: sets multiple or all fields touched state.
• useSetFormErrors: sets form error messages.

🆕 Initial support for Valibot

Valibot is an impressive new schema validation library, mainly it offers Zod-like features at a much less bundle size due to its non-chainable API while still being easy to use and fully typed.

Because of this, vee-validate now supports it as a schema provider using the @vee-validate/valibot package that exposes the same API function toTypedSchema that you can use to get TypeScript support into your forms input and output values.

Quick example:

import { useForm } from 'vee-validate';
import { toTypedSchema } from '@vee-validate/valibot';
import { email, string, minLength, object } from 'valibot';

const { errors, values } = useForm({
  validationSchema: toTypedSchema(
    object({
      email: string([minLength(1, 'Email is required'), email()]),
      password: string([minLength(6, 'password too short')]),
    }),
  ),
});

Refer to the docs for live examples and more information on typed schemas.

👕 Types

• Fixed a type issue where setErrors did not accept an array of strings #4396 (c02337f)

💨 Performance improvement

• Improve setFieldError and setFieldValue performance #4382 (c511385) (a9a473b)

🐛 Bug fixes

• Clone values inserted into field arrays #4372 (9290f5a)
• Do not warn if the validation is for auto-removed paths #4368 (93f8001)

✨ Behavior Changes

• use silent validation when field is initialized closes #4312 (68080d2)

This is because it was causing modal forms to have errors on mounted which confused users. This does not effectively change anything other than you will no longer need to reset the form whenever the modal is shown or when the fields are mounted. If you relied on this behavior then it could be a breaking change for you and you can get it back by enabling validateOnMount or calling validate whenever.

This does not affect initial errors or validateOnMount option.

🐛 Bug Fixes

• resetForm should cast typed schema values closes #4347 (e9b215a)
• validate form values on setValues by default closes #4359 (4e11ff9)
• normalize error paths to use brackets for indices closes #4211 (e354a13)

⚙️ Misc

• feat: expose normalizeRules #4348 (40ce7a9)

🐛 Bug fixes

• Fixed an issue with defineComponentBinds not adding onBlur binding correctly (6a1dc9b)
• Fixed an issue with defineComponentBinds not respecting validateOnModelUpdate config #4346 (6a1dc9b)

👕 TypeScript

• Avoid using DeepReadOnly type for now with useForm#values since it is too aggressive 2f9ca91

🐛 Bug Fixes

• SSR: Avoid referencing window with setTimeout for validation batching #4339 (#4340) thanks to @userquin 🙌
• Respect model modifiers when emitting the value with useField v-model integration #4333 (c3698f0)

✨ Enhancements

Made object dirty meta checks less strict by treating undefined and missing keys as the same value #4338 (32537e1)

This may cause some differences with the value of dirty meta for forms and object value fields but it shouldn't affect most cases.

🐛 Bug Fixes

• defineXXXBinds not respecting validation config events (1660048)

🐛 Bug Fixes

• handle NaN when parsing number inputs #4328 (fc41691)
• reset present values after all path mutation (435e785)
• resetField() should not validate #4323 (273cca7)

💣 Breaking Change

Disabled syncVModel by default #4283 (7ce9d67)

A lot of issues created because of this and valid issues and concerns by the community caused by useField auto model tracking causing unexpected behavior for a lot of people. The feature has been disabled by default starting from v4.10.0.

If you relied on useField doing auto modelValue and update:modelValue emitting then you need to turn it on by passing true to syncVModel.

const { ... } = useField('name', undefined, {
 syncVModel: true,
});

Check the discussion in #4283

This makes sense, because it being opt-in makes it less dangerous to cause unexpected behavior.

useForm#values is now readonly #4282 (05d957e)

the values object returned from useForm should have never been treated as mutable and the docs mentioned that a few times and didn't encourage it.

In this release, we mark it as readonly to make it clear to everyone that it should not be mutated directly. The main reason for this design choice is we need to be able to infer the user intent with those mutations. For example, if you clear an array, did you mean to reset the field or did you mean to change its value and trigger a validation?

Being able to infer the user intent is paramount for vee-validate to be able to handle such behaviors correctly, it has always been the case here, and marking it as readonly is just a hint that should've been there from the start.

This should not affect a lot of users.

💅 DX enhancements

• Allow custom models for defineComponentBinds (bfd6b00)
• handleBlur can be configured to run validations (d4fafc9)
• useField#syncVModel also accepts the model prop name (3e4a7c1)
• Allow multiple messages to be returned in a validator function #4322 #4318 (2cf0eec)

🐛 Bug Fixes

• resetForm should merge values #4320 (77345c4)
• Use event value if no checked value for checkbox/radio #4308 (f1dc135)
• Trigger validation with setFieldValue by default #4314 (ed20891)
• Parse native number fields #4313 (6a3f9f1)

👕 TypeScript

vee-validate v4.10.0 requires vue@3.3 as it uses many of the newly introduced types to replace its own version of them, this should not affect your experience however it may produce type errors if you relied on some of these internal types. Like MaybeRefOrLazy replaced with MaybeRefOrGetter.

🐛 Bug Fixes

• Field's handleBlur should respect validateOnBlur config #4285 (6e074f7)
• Correctly merge non-plain objects in form's setValues #4287 (#4289) thanks to @VladStepanov

👕 TypeScript

• Improve Field binding types (#4291) thanks to @FedorSherbakov
• export SetFieldValueOptions interface #4290 (b138282)

🐛 Bug Fixes

• Allow labels to be localized with dictionary names prop #4268 (16580b4)
• setFieldError sets meta.valid correctly #4274 (7356c10)

🆕 New features

• Exposed componentField on Field slot props to make it easier to integrate with components (#4270) thanks to @FedorSherbakov

🐛 Bug Fixes

• Types: Exclude undefined and null from initial values resolution #4139 (f4ea2c0)
• Bundle: Components were not being tree-shaken correctly (#4266) thanks to @ydcjeff
• devtool: add compatibility for UTF character (#4265) thanks to @linghaoSu

🐛 Bug Fixes

• Run validation on value change #4251 (09d5596)
• Hoist nested errors to the nearest parent state #4063 (#4259)

🆕 New features

• Added isValidating on the form context (#4244) thanks to @jusheng27

🐛 Bug fixes

• Hiding array fields with v-if did not remove the last item correctly #4115 (fe322a0)
• Removing some items caused other items to lose value in a field array loop #4239 (31090e0)
• Validations run for unmounted fields when keep-values is enabled #4247 (9046308)

🐛 Bug fixes

• Added type-fest to dependencies on the core package #4242 (681bbab)
• Hide nested value write warning if the value isn't an object (18f3c1c)
• Fix Type errors when using v-bind="field" on a textarea element #4031 (ce2f539)

This release required a lot of internal changes to how vee-validate tracks fields to have better DX down the line. There shouldn't be any breaking changes to your apps, as all the tests are passing with these changes. But some behaviors may differ if you were using some unintentional bugs as features.

The main change is vee-validate shifting from thinking about fields as unique field instances to treating them as outlets for path values. The outcome is the same in most cases but allows for more ways for vee-validate to define fields.

💣 Possible breaking changes

• setValues was deleting the other values not specified, now it only sets the fields partially as provided without deleting any values. #4231 (298577b)
• If you were using a field's meta with group fields (checkboxes/radio), each field had its own meta, with this release all those fields will have the exact same meta values.
• Validations are now run only when a value setter has been triggered, this should not break anything but if you were using nested values as field values you will get a warning and which alternative to use.

🆕 New Features

Component Binds

useForm now exposes a new helper defineComponentBinds which allows you to create bindable objects for your components.

This is meant as replacement for useFieldModel and should replace using useField as a model. useField is still the best way to build input fields components, but if you don't want to wrap your fields with useField especially with 3rd party UI component libraries then defineComponentBinds is the way to go.

This is an example with Vuetify:

<script>
const schema = toTypedSchema(yup.object({
  email: yup.string().email().required().label('E-mail'),
  password: yup.string().min(6).required(),
}));

const { defineComponentBinds } = useForm({
  validationSchema: schema
});

const email = defineComponentBinds('email', {
 // maps error messages to Vuetify
  mapProps: (state) => ({ 'error-messages': state.errors  })
});
const password = defineComponentBinds('password');
</script>

<template>
  <v-text-field
    v-bind="email"
    label="email"
    type="email"
  />

  <v-text-field
    v-bind="password"
    label="password"
    type="password"
   />
</template>

Input Binds

Another helper exposed by useForm is defineInputBinds which allows you to create bindable objects for your HTML elements.

<script>
const schema = toTypedSchema(yup.object({
  email: yup.string().email().required().label('E-mail'),
  password: yup.string().min(6).required(),
}));

const { defineInputBinds } = useForm({
  validationSchema: schema
});

const email = defineInputBinds('email', {
 // Adds attributes to the element, like classes, aria-attrs, etc...
  mapAttrs: (state) => ({ 'aria-invalid': state.valid ? 'false' : 'true'  })
});
const password = defineInputBinds('password');
</script>

<template>
  <input
    v-bind="email"
    label="email"
    type="email"
  />

  <input
    v-bind="password"
    label="password"
    type="password"
   />
</template>

📚 Docs update WIP

The docs will be updated throughout the week to include a new guide for the composition API and the recommended ways to set up fields depending on the different requirements.

Some of the recently added features will be missing until the re-write is complete.

🐛 Bug Fixes

• Removing a field from useFieldArray should not trigger validation for unchanged fields #4017 (7554d4a)
• fix: handle mimes with plus symbol #4230 (f5b3482)
• fix: support surrogate pairs (#4229) thanks to @NaokiHaba
• fix: Zod transforms not reflecting in output types correctly #4227 (93228b7)
• fix: corrected slot prop types for field component #4223 (b2c4967)

🆕 Nuxt Module

Published the offical vee-validate nuxt module, to install the module:

npm i @vee-validate/nuxt

then you can add it to nuxt.config.ts:

export default defineNuxtConfig({
  // ...
  modules: [
    //...
    '@vee-validate/nuxt',
  ],
});

check the documentation for more information and how to configure it.

🐛 Bug Fixes

• Fixed zod unions errors not mapping to field errors #4204 (9048a23)
• Fixed falsy model initial value not overriding form value #4200 (07418b9)

🐛 Bug Fixes

• properly unref the schema before checking for default values closes #4196 (8e3663d)

👕 TypeScript

• make initial values partial closes #4195 (eeccd0c)

🏗️ DX Improvements

• allow name ref to be a lazy function (8fb543a)

// no need to wrap this anymore with `computed` or with `toRef`.
const { value } = useField(() => props.name);

🐛 Bug Fixes

• Fixed a bug with Zod's typed schema defaults logic that caused a crash sometimes #4186 (comment)

🐛 Bug Fixes

Fix a bug introduced in 4.7.4 where useField error messages ignored the names configuration in global i18n dictionaries #4164 (d5acff7)

🐛 Bug Fixes

• Fixed an issue where a zod schema may produce undefined as a cast value #4186 (9f1c63b)
• Exposed errorBag on the <Form /> component (371744e)

🆕 New features

Yup and Zod typed schemas

You can now infer the input/output types from yup and zod validation schemas by using toTypedSchema helper from @vee-validate/yup and @vee-validate/zod packages.

import { useForm } from 'vee-validate';
import { object, string } from 'yup';
import { toTypedSchema } from '@vee-validate/yup';

const { values, handleSubmit } = useForm({
  validationSchema: toTypedSchema(
    object({
      email: string().required(),
      name: string(),
    })
  ),
});
// ❌ Type error, which means `values` is type-safe
values.email.endsWith('@gmail.com');
handleSubmit(submitted => {
  // No errors, because email is required!
  submitted.email.endsWith('@gmail.com');
  // ❌ Type error, because `name` is not required so it could be undefined
  // Means that your fields are now type safe!
  submitted.name.length;
});

Same thing for zod with the exception that zod requires all fields by default and you will need to mark them as optional for it to reflect in the output type. Check the docs for more examples.

Aside from type inference, you can also assign default values to form schemas using either schema libraries and you can also use yup's transform and zod's preprocess to cast values.

Form's Error bag

The errorBag is now exposed from useForm which returns a record of the fields with their errors as an array, previously you could only grab one error per field but with this, you can render all errors for all fields.

const { errorBag } = useForm();

errorBag.email; // string[] or undefined

🐛 Bug fixes

• Return all errors from yup and zod schema validations #3680 #4078 (c2e02b7) (f74fb69)
• Sync initial model with useField's value #4163 (1040643)
• Field arrays not changing when replaced by setValues or setFieldValue from the form's context #4153 (6e784cc)
• Field array not updating the form's valid state when pushing/removing/replacing/etc... #4096 (044b4b4)

👕 TypeScript

• Exposed FieldState type #4159 (69c0d12)

🐛 Bug Fixes

• Fixed an issue where unique field/rule special messages didn't work when a label was provided #4097 (89f8689)
• ext rule using incorrect wildcard symbol (#4045) (5265af5)

👕 TypeScript

Exposed various types from the @vee-validate/i18n module #4106 (c65ead8)

🆕 Minor Features

• Added new resetField on useForm and <Form /> component slot props #4117 (87c4278)
• Exposed getValues and getErrors and getMeta on <Form /> component instance (#4121) (7f1c39c)

🐛 Bug Fixes

• Updated excluded references in translation files with not_one_of #3993 (7fc5077)
• Use cloned value when setting field value via form #3991 (90b61fc)

🐛 Bug Fixes

• Don't mutate validated meta when non-forced validation is run #3981 #3982 (6652a22)

🐛 Bug Fixes

• clean up single group value after unmount #3963 (#3972) (8ccfd2b)
• correctly mutate deep field array item and trigger validation (#3974) (267736f)
• mark slot prop field value as any #3969 (#3973) (70ddc5b)

🌍 i18n

• Fixed wrong placeholder in CS localization (#3959) (a4603fa) thanks to @Liwoj

🆕 New Features

Controlled values filtering #3924

A good use-case is where you assign a bunch of values as initial values to your form but your inputs only control a few of them but it wasn't possible to extract these controlled values from all the values.

v4.7 Lets you do that using a few ways:

You can grab controlledValues from useForm result

const { handleSubmit, controlledValues } = useForm();

const onSubmit = handleSubmit(async () => {
  // Send only controlled values to the API
  // Only fields declared with `useField` or `useFieldModel` will be sent
  const response = await client.post('/users/', controlledValues.value);
});

Or use withControlled composed function:

const { handleSubmit } = useForm();

const onSubmit = handleSubmit.withControlled(async values => {
  // Send only controlled values to the API
  // Only fields declared with `useField` or `useFieldModel` will be sent
  const response = await client.post('/users/', values);
});

vee-validate marks fields which were created using useFieldModel or useField (and <Field />) as "controlled" and these would be the only values included in the previous samples.

Explict form context option #3204

Previously useField and <Field /> components used implicit injections to resolve the form context they are part of. This prevented having multiple form contexts within the same component with useForm since each call will take over the fields declared after.

Now when declaring fields with useField you can pass form option explicitly to assign that field to that form:

const form1 = useForm();
const form2 = useForm();
        
const field1 = useField('field', undefined, {
  form: form1,
});

const ield2 = useField('field', undefined, {
  form: form2,
});

🐛 Bug Fixes

• Fixed using File constructor while in SSR (56663aa)

i18n 🌍

• Updated SK and CS language files to include missing rules thanks to @Liwoj #3936 #3937

🐛 Bug Fix

• Fixed an issue where resetForm would leave behind null or undefined in array fields after reset #3934 (1c016d9)

🐛 Bug Fixes

• Run validation if we skip checkbox value setting if event trigger should validate #3927 (#3930)
• Fix File value instance equality checks #3911 (#3932)
• Fix nested value change not triggering validation when validateOnValueUpdate is enabled #3926 (#3929)

👕 TypeScript

• Exposed RuleExpression type #3913 (cdaf22d)

👕 TypeScript

Allow generics types to be passed to GenericValidatorFunction which previously caused errors with simple snippets like this:

function validator(value: string) {
  // ...
}

const { value } = useField('field', validator);

🐛 Bug Fixes

• Fixed an issue with async function validators not respecting the last run error messages #3906 (#3908)

🐛 Bug Fixes

• Fixed emitted value when there are no model modifiers defined #3895 (#3896)

🐛 Bug Fixes

• Fixed an issue where checkboxes bound to an object could fail unchecking #3883 (#3885)
• Fixed an issue with field's meta.dirty not being set correctly after calling resetField with a new value #3891 (#3892)

🐛 Bug Fixes

• Fixed an issue where useFieldModel did not trigger validation for nested paths (fbe273c)

🐛 Bug Fixes

• fix form's meta.dirty not calculated correctly when using FieldArray API #3874 (#3875)

👕 TypeScript

• Expose FieldOptions and FormOptions interfaces #3843 (7437612)

🐛 Bug Fixes

• Avoid toggling field array checkboxes values when an item is removed #3844 (fffad4b)

🐛 Bug Fixes

• Pass onInvalidSubmit prop to submitForm #3841 (b6cf543)

This release has been in the making for a while and I'm really glad it is finally released with a lot of requested improvements and new features.

🆕 New Features

v-model with FieldArray API

You can now use v-model directive with any kind of input to mutate the field array value directly without having to use <Field /> or useField.

<Form>
  <FieldArray name="users" v-slot="{ fields }">
    <div v-for="(field, idx) in fields" :key="field.key">
      <input v-model="fields[idx].value" />
    </div>
  </FieldArray>
  
  <button>Submit</button>
</Form>

Keep values after fields are unmounted

By default, vee-validate destroys the form values automatically whenever a field is unmounted. This made creating tabbed forms or multi-step forms a little bit harder to achieve since you needed to implement a mechanism to track the values independently from vee-validate.

Now there is a new (config available) (e6e1c1d) that allows you to control this behavior on the form and field levels.

In the component API, you can pass keepValue or keepValues to <Field /> and <Form /> components respectively.

<!-- Now all field will keep their values when unmounted unless specified otherwise -->
<Form keep-values>
  <template v-if="showFields">
    <Field name="field" as="input" rules="required" />
    <!-- This field opts out and its value will be destroyed -->
    <Field name="[non-nested.field]" :keep-value="false" />
    <Field name="drink" as="input" type="checkbox" value="Tea" rules="required" /> Tea
  </template>

  <button>Submit</button>
</Form>

You can also pass keepValueOnUnmount and keepValuesOnUnmount to useField() and useForm() respectively:

useForm({
 // default is false
  keepValuesOnUnmount: true
});

useField('field', undefined, {
  // default is whatever the form is configured to, if no form then `false`
  keepValueOnUnmount: true
});

Note Keep in mind that the field config takes priority over the form config if specified. Otherwise, all fields will follow the form's config.

useFieldModel API

A new useFieldModel function was added] to useForm which introduces a new way to use useForm without having to call useField.

The reason for this is useField is meant to create input components, not model bindings. The useFieldModel allows you to create bindable refs that you can use directly with v-model on your components or any 3rd party components. This makes it significantly easier to integrate with 3rd party libraries.

<template>
  <input name="email" v-model="email" />
  <span>{{ errors.email }}</span>

  <input name="password" v-model="password" type="password" />
  <span>{{ errors.password }}</span>
</template>

<script setup>
import { useForm } from 'vee-validate';
import MyTextInput from '@/components/MyTextInput.vue';

// Define a validation schema
const simpleSchema = {
  email(value) {
    // validate email value and return messages...
  },
  name(value) {
    // validate name value and return messages...
  },
};

// Create a form context with the validation schema
const { errors, useFieldModel } = useForm({
  validationSchema: simpleSchema,
});

const email = useFieldModel('email');
const password = useFieldModel('password');

// or multiple models at once
const [email, password] = useFieldModel(['email', 'password']);
</script>

This is much less verbose than useField and is optimized to be just a validatable model. However you will no longer have access to the advanced state and capabilities of useField like meta and validation triggers. So you will need to implement your own logic for when to show errors as they will be generated immediately whenever the value changes.

Automatic v-model events with useField

Quite often you will setup your component to support v-model directive by adding a modelValue prop and emitting a update:modelValue event whenever the value changes.

If you use useField in your input component you don't have to manage that yourself, it is automatically done for you. Whenever the useField value changes it will emit the update:modelValue event and whenever the modelValue prop changes the useField value will be synced and validated automatically.

The only requirement is you need to define your model prop on your component explicitly.

<script setup>
import { useField } from 'vee-validate';

defineProps({
  // Must be defined
  modelValue: {
    type: String,
    default: '',
  },
});

const { value } = useField('field', undefined);
</script>

You can change the default model prop name by passing modelPropName option to useField:

<script setup>
import { useField } from 'vee-validate';

defineProps({
  // Must be defined
  custom: {
    type: String,
    default: '',
  },
});

// component will now emit `update:custom` and sync `custom` prop value with the `value` returned from `useField`.
const { value } = useField('field', undefined, {
  modelPropName: 'custom',
});
</script>

You can also disable this behavior completely and manage those events yourself by passing syncVModel option to useField:

<script setup>
import { useField } from 'vee-validate';

// Now it won't emit anything and won't sync anything
const { value } = useField('field', undefined, {
  syncVModel: false,
});
</script>

Other minor new features

• Added move() to FieldArray (a52f133)
• If you are using a native <input type="file"> element its value will now respect the multiple attribute, if it is present and set to true then it will be an array of files. Otherwise, it will be a single file. This could be a breaking change for some.

👕 TypeScript Changes

• Expose ValidationOptions type #3825 (9854865)
• Exposed component APIs to their TS defs with refs #3292 (ae59d0f)
• Remove yup type dependency (#3704) (e772f9a). This sadly loses the ability to infer the types from a yup schema, however it caused more errors than it is worth and introduced an installation dependency on yup even if it is not used.

🐛 Bug Fixes

• Use multiple batch queues for both validation modes #3783 (6156603)
• Compare form's meta.dirty based on original values than staged initials #3782 (f3ffd3c)
• Avoid value binding for file type inputs #3760 (3c76bb2)
• Added existing undefined path fallback for optional arrays #3801 (fd0500c)
• Added argument order for digits rule inja.json#3780 (9385457)

🐛 Bug Fixes

• Ignored validation of fields during unmounting #3748 (3d49faa)

🆕 New Features

useField now allows the usage of array of functions instead of a single function to perform validation (#3725) #3726 thanks to @gbaquedano

const {
  value: value,
  errors: errors,
} = useField(
  'field',
  [
    val => (val ? true : REQUIRED_MESSAGE),
    val => ((val as string)?.length >= 3 ? true : MIN_MESSAGE)
  ],
  { bails: false }
);

🐛 Bug Fixes

• Fixed an issue with da.json locale which caused the JSON file to not parse correctly (9485310)

🐛 Bug Fixes

• Set meta.validated for fields validated by the form API's validate (ad9fa9d)

🌏 i18n

• Updated locale for ko, ja, zh-CN, zh-TW (d5fc732)

🐛 Bug Fixes

• Fixed a general issue when a field changes its name and has errors at the old name path #3664 (f736e62)
• Fixed an issue where FieldArray.swap function wasn't working when either indices had falsy values (40afbd9)

🐛 Bug Fixes

• Always ensure update:modelValue listener existing on field binding object #3583 (6a53e80)

🌏 i18n

• Added Uzbek locale thanks to @akahon (#3601)

🐛 Bug Fixes

• Use watchEffect to calculate FormContext.meta instead of computed #3580 (e8729dc)

As a result of this, there should be a performance improvement depending on the size of your forms

👕 TypeScript

• Corrected the typings for resetField #3568 (4e9460e)

🌏 i18n

• Added missing Estonian locale messages and fixes by (#3584) @Tarinu

🐛 Bug Fixes

• Fixed an issue where singular checkboxes would be toggled when the form is reset #3551 (cad12ba)

👕 TypeScript

• Published various internal types that are considered stable #3548 (88ed4e7)

👕 TypeScript

• Added scoped slot types for Field, Form, FieldArray and ErrorMessage components #3534 (#3537)

✨ Enhancements

• Use the full mode of lukeed/klona which is used to clone values internally to support Luxon data structures #3508 (048c9c0)

🐛 Bug Fixes

• Fixed field name not rendering in messages correctly in default error messages (#3506) thanks to @cexbrayat

🆕 New Features

Field Arrays

A long-requested feature is a proper way to handle field arrays. With this release you get two ways you can manage your array fields:

• useFieldArray a composition API version. Read more in docs
• <FieldArray /> a component API version. Read more in docs.

Both have the same API, and they make managing those fields much easier.

Invalid Submission Handler

Another common request is the ability to handle invalid submissions, for example, you may want to scroll to the first invalid element.

This is now possible with both <Form /> component and useForm composition function. Check the links for their documentation:

• Handle invalid submissions with <Form /> component
• Handle invalid submissions with useForm composition function

Devtools Plugin

vee-validate now ships with its VueDevtools plugin, this will be an invaluable tool to help you debug your forms and their validation state.

This is the initial release for the plugin, so please report any bugs and suggest any improvements you can think of. 🙏

Check the guide page.

💨 Performance Enhancements

A partial re-write of vee-validate v4 fixed a long-standing performance issue that was reported here #3399

💀 Breaking Changes

handleInput is removed from useField after being deprecated since 4.3, you can use handleChange instead of handleInput as follows:

const { handleChange } = useField('email', {
  validateOnValueUpdate: false
});

handleChange('value'); // updates the value and validates
handleChange('value', false); // updates the value without validation

// replace deprecated handleInput with custom one
const handleInput = (val) => handleChange(val, false);

Note that handleInput prop still exists in <Field /> scope slot. This is only for useField.

Note: This release was a 2-month work in progress, so there aren't any bug fixes as 4.4.x was already being worked on in parallel to this release, so both 4.4.x and 4.5.0 contain the same bug fixes which won't be mentioned here in the release notes. Check the previous releases for more information.

🐛 Bug Fixes

• Fixed an issue where computed rules triggered validation before the field was explicitly validated (via event trigger or calling validate).

🐛 Bug Fixes

• Fixed resetField and resetForm setting the valid flag to true, it should reflect the current validity state of the form as it always should regardless of errors being displayed or not, this can be breaking for some but it was a bug. #3463 (a61f7ab)
• Fixed a Vue crash when the provided v-model value is undefined #3467 #3468 (2c4a7ff)
• Fixed native Select input not setting the bound value of options #3440 (b144615)

👕 TypeScript

Corrected the type for handleReset function (#3451) thanks to @iamandrewluca

🐛 Bug Fixes

• Fixes an issue where initial values were using the same reference as the current values #3428 #3434 (6470a1f)

🐛 Bug Fixes

• Fixed checkboxes emitting the absent value symbol to bound models when using v-model and not specifying an uncheckedValue #3422 #3422 (3824103)

🐛 Bug Fixes

• Fixed extra validation being triggered with Vue 3.2.0-beta.x at the end of a resetField call #3407 (86f594f)

👕 TypeScript

• Exported the FieldContext type #3398 (a6e4c0a)

⚙️ Misc

• Exported FormContextKey and FormFieldKey injection keys to make mocking in unit tests easier (6034e66)

🐛 Bug Fixes

• fix: clean error message for singular fields after unmounting #3384 formvuelate/formvuelate#210 (#3385)
• fix: quit unsetting path if its already unset, you may have encountered this if you use vue-router (64ba5f9)

🐛 Bug Fixes

• Fixed null initial values not being respected #3352 (1e9cfd1)

🐛 Bug Fixes

• field with pre-register schema errors should be validated on register #3342 (61c7359)

🐛 Bug Fixes

• Fixed bails option being ignored in <Field /> component when using form schema with global rules #3332 (6679387)

🐛 Bug Fixes

• Clean up form values fields that exchange their name with another field #3325 (fe51c12)

🐛 Bug Fixes

• Bring back errors object on the form validation result that was removed by mistake #3317

This release commits the changes from 4.4.0-alpha releases

🐛 Bug Fixes

• Fixed the URL rule not exported #3310 (abeccfb)
• Fixed an issue with Field component not emitting onUpdate:modelValue when bound to undefined #3312 (5e72852)

🐛 Bug Fixes

Fixed errors being cleared whenever any input was being validated

🐛 Bug Fixes

Fixed an issue where the dist files code didn't preserve the result of a conditional promise

⚠️ Important Changes

Schema Behavior Change

Previously vee-validate treated schemas loosly, meaning if there are validations for fields that were not rendered with Field or useField it will ignore the errors for those fields. This was found unexpected from the few reports I got.

In 4.4.x and onwards, vee-validate will treat schemas as the source of truth and will no longer ignore any errors generated by the validation schema.

There are a few side effects to this change:

• You can now set custom form errors with setErrors or setFieldError for non-existing fields and it will affect the form's validity.
• You can set custom values with setValues or setFieldValue for non-existing fields.
• Defining a schema for multi-step forms will require partitioning them into separate ones per step

The first two side effects should not be breaking in your apps unless you have typos when setting fields values/errors

The official examples for multi-step forms will be updated in the docs to reflect these changes

Depreactions

• handleInput is now marked for deprecation, you may still use it but it will be removed in the next minor release, instead use handleChange(event, shouldValidate = false) as an alternative.
• valueProp was renamed to checkedValue to better reflect its usage, you may still use the old prop name but it will be removed in the next minor release.

Compatibility: This patch is to adjust to some changes introduced in Vue 3.1

• Added a new way to detect if modelValue was passed as a prop or not #3294 (#3295)

🐛 Bug Fixes

• prioritize self injections over parent injections #3270 (07c1234)

🌍 i18n

• Added Welsh language translations thanks to @al3d

🐛 Bug Fixes

• Ensure the valid flag is updated correctly regardless of the validation intent #3284 (6594ad1)

🆕 New behavior

• submitting forms rendered by <Form /> or handleSubmit or submitForm functions, all fields will be automatically "touched" (#3278)

You can find documentation for the submission full behavior here

🐛 Bug Fixes

• Fixed an issue with the initial value being wrapped in a ref which caused some issues for individual resetField calls and dirty field-level flags #3272 (#3274)

✨ Enhancements

• Added name to the ErrorMessage component ctor options which should make it identifiable in Vue dev tools
• Tweaked slots rendering for custom components with Field, Form, ErrorMessage component which avoids Vue warning in some situations

🆕 New Features

• Computed Validation Schema Support: Previously when working with yup schemas, in particular, it was hard to create a dynamic schema using just the Yup.mixed and Yup.when API, now you can create computed schema to make it easier to do so. Check the docs for more information
• v-model.number modifier support: TheField component v-model now supports the .number modifier, thanks to @davidguilherme who worked on this
• New global rule: The url rule is added back to the global validators, thanks to @davidguilherme who worked on this. You can find more information in the documentation

📢 The language files need your help, if you find the url locale message missing for your language, please contribute it 🙏

👕 TypeScript

Removed the SubmitEvent type which caused some tools like volar to display errors for form @submit handlers created by handleSubmit function in the composition API

🌏 I18n

Several enhancements to the ja locale, thanks to @kuanyui

🐛 Bug Fixes

• Fixed an issue where validation would trigger on value change with useField even if validateOnValueChange is set to false (10549b7)

🐛 Bug Fixes

• fix: prevent yup schema validation from accidentally setting non-interacted fields errors #3228 (534f8b2)

👕 TypeScript

• Exposed PublicFormContext interface (#3222) thanks to @notiv-nt

🌍 i18n

• Fixed mistype in digits rule message for LT locale #3209 (#3215) thanks to @vaidotas

🐛 Bug Fixes

• Fixed an issue for pending validation with fields/forms being unmounted with vue-router (ef5a7cc)

🌏 i18n

• Added Uyghur locale thanks to @uqkun09 (#3201 )

This release fixes some issues introduced in 4.2.1 due to the limitations mentioned in #3189

Enahanced valid flag behavior

Instead of having the valid flag starts with either true or false, it will have its own validation ecosystem where silent validations would be run when:

• The field is mounted
• The field value changed

This means you can now always rely on the valid flag to present the accurate form state, note that the valid flag is now completely independent from the errors array as it can be false while there are no errors. But the opposite is not true, the valid flag cannot be true while there are some errors.

Until that silent validation is run, the valid flag will be true, so it is still good idea to combine it with dirty or touched as to avoid this issue.

This change makes easier to disable various UI elements based on the validity and interactivity with the form, here are some common ones:

This PR introduces several updates to the meta objects in both field and form APIs, these changes are considered breaking for non-intended use-cases, so it doesn't warrant a major release.

🆕 New Changes

dirty flag changes

The flag now acts as a changed flag, it will be read-only and will be set to true if the field current value is not deeply equal to its initial value.

The reason for this change is the dirty and touched flags are not that different from one another, so users end up using one or the other. Having the dirty flag reflects whether the form values have changed or not gives it more utility and is more valuable to several common tasks done by FE developers.

valid flag changes

Changes in this release has been overwritten by 4.2.1 due to bad DX

Rules and Empty Values

The global validators published under @vee-validate/rules didn't handle the empty values before, meaning they gave an incorrect behavior when used without required. The changes in this PR introduce a consistent behavior across all these rules:

• If the value is empty, the value is valid
• Empty values are: empty strings, empty arrays, null or undefined

That closely mirrors the behavior in v3 where validation is skipped for empty non-required fields, except now the validation passes rather than skipped. #3170

🐛 Bug Fixes

• Fixed the checkboxes setting their initial value twice causing malformed form values #3183

🐛 Bug Fixes

• Fixed nested errors for @vee-validate/zod not being picked up correctly (01b89e4) #3184
• Fixed an issue where initial values for checkboxes would cause malformed output (ab5f821) #3183

🌎 i18n

• Add missing Turkish locale translations by @yoktav in #3573

✨ Enhancements

The double rule now accepts integers (#3481) thanks to @MauriceChocoSwiss

🐛 Bug Fixes

• Fixed an issue where Hebrew characters were not recognized by the alpha_xx rules (#3397) thanks to @MHGuitarte

🐛 Bug Fixes

• Fixed Japanese locale validation in alpha validators #3357 (#3356) thanks to @nachogarcia

🐛 Bug Fixes

• Fixed required flag not re-evaulating its value #2843 (#3318) thanks to @Andrevwv

🔧 Compatability

• fixed IE 9 compatibility issue introduced in fd5bacb #3326 (4545fb9)

🐛 Bug Fixes

• fixed recursive objects comparison for the changed flag triggering maximum callstack errors #3320 (fd5bacb)

🐛 Bug Fixes

• Implemented recursive checking for changed flag for nested arrays and objects #3300 (#3313) thanks to @AdelineCaro