logaretm/vee-validate v4.6.0

on GitHub

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)