Painless forms for Vue.js
This section documents version-specific API changes for vee-validate v4.x — prioritize these over legacy patterns.
-
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
-
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 or declare them outside of / to avoid unnecessary deep reactivity overhead
