logaretm/vee-validate

vee-validate

API Changes

• BREAKING:

  v-model

  support disabled by default in v4.10.0 for performance; enable via

  configure({ validateOnModelUpdate: true })

  or per-field

  syncVModel

  source
• NEW:

  defineField

  introduced in v4.9.0 — replaces

  defineComponentBinds

  and

  defineInputBinds

  for cleaner Composition API integration source
• DEPRECATED: Reactive initial values deprecated in v4.12.0; use non-reactive objects or getters to prevent unintended sync source
• NEW:

  useFormContext

  exposed in v4.14.0 for accessing form state in deeply nested components without manual injection source
• NEW:

  setValue

  exposed on

  Field

  instances and slot props in v4.13.0 for manual value updates source
• NEW: Composition setter hooks (

  useSetFieldValue

  ,

  useSetFormValues

  ,

  useSetFormErrors

  ) added in v4.11.0 for external state management source
• NEW:

  handleBlur

  accepts

  shouldValidate

  parameter since v4.10.0 to control validation triggers on blur events source
• NEW:

  syncVModel

  accepts target model prop name as a string in v4.10.0 for custom model support source
• NEW:

  isValidating

  state added to

  useForm

  and form slot props in v4.9.3 to track async validation status source
• NEW:

  move(oldIdx, newIdx)

  added to

  FieldArray

  in v4.6.0 for reordering items within array fields source
• NEW: Specialized state hooks (

  useIsFieldDirty

  ,

  useIsFormValid

  ,

  useFieldValue

  ) added in v4.1.0 for granular state access source
• DEPRECATED:

  handleInput

  deprecated in v4.4.0; use

  handleChange

  for both input and change events source
• NEW:

  label

  support in

  defineField

  added in v4.12.0 for consistent error message generation source
• NEW:

  ResetFormOpts

  with

  force

  flag added to

  useResetForm

  in v4.13.0 to clear values without merging source

defineComponentBinds

defineInputBinds

useFieldModel

unsetValueOnUnmount

keepValuesOnUnmount

useForm

useResetForm

nested field meta querying

Best Practices

• Prefer

  defineField()

  for binding components and inputs — returns a

  v-model

  ref and a props object for clean, non-deprecated binding source

const [email, emailProps] = defineField('email', {
  validateOnBlur: true,
  props: state => ({ 'aria-invalid': !!state.errors.length })
});

• Display errors conditionally using

  meta.touched

  — prevents "aggressive" validation where error messages appear before the user interacts with the field source
• Use

  toTypedSchema()

  for comprehensive TypeScript safety — wraps Yup, Zod, or Valibot schemas to differentiate between input (UI) and output (submitted) types source

import { toTypedSchema } from '@vee-validate/zod';
import * as z from 'zod';

const { values } = useForm({
  validationSchema: toTypedSchema(z.object({ email: z.string().email() }))
});

• Mark validation schemas as non-reactive — wrap schemas in

  markRaw

  or declare them outside of

  ref

  /

  reactive

  to avoid unnecessary deep reactivity overhead source
• Tree-shake schema validator imports — only import the specific functions you need (e.g.,

  import { string } from 'yup'

  ) to keep bundle sizes to a minimum source
• Pass reactive field names as getters in

  useField

  — use a function (e.g.,

  () => props.name

  ) to ensure vee-validate tracks name changes in dynamic forms source
• Enable

  keepValuesOnUnmount

  for multi-step forms — preserves field state when components are hidden via

  v-if

  or tab switching source

const { values } = useForm({
  keepValuesOnUnmount: true
});

• Use

  field.key

  for stable iteration in

  v-for

  —

  useFieldArray

  provides unique identifiers that persist through array operations, unlike indices source
• Escape field names with

  []

  to disable automatic nesting — wrap names (e.g.,

  [user.name]

  ) to treat dots as literal characters rather than object paths source
• Filter submission values with

  handleSubmit.withControlled()

  — ensures only fields explicitly registered via

  useField

  or

  defineField

  are included in the payload source