Implementing Type-Safe Form Validation with VeeValidate and Zod

The Problem: Fragmented Validation Logic

In complex Vue.js applications, validation logic often becomes scattered across template props, separate JavaScript functions, and manual state checks. This fragmentation makes it difficult to maintain a single source of truth for data requirements and often leads to a mismatch between the validated form state and the TypeScript types used in the backend API.

The solution is to decouple the validation rules from the UI components using a schema-based approach. By integrating VeeValidate with Zod, you can define a centralized schema that handles both runtime validation and TypeScript type inference, ensuring that your form state is guaranteed to match your data model before submission.

Prerequisites

• Vue 3 (Composition API)
• VeeValidate v4.x
• Zod v3.x
• TypeScript enabled in the project

Defining the Validation Schema

To avoid performance hits during component re-renders, define your Zod schema outside the Vue component. This ensures the schema is instantiated only once.

import { z } from 'zod';

// Define the schema as a constant
export const registrationSchema = z.object({
  username: z.string().min(3, 'Username must be at least 3 characters'),
  email: z.string().email('Invalid email format'),
  password: z.string().min(8, 'Password must be at least 8 characters'),
  confirmPassword: z.string()
}).refine((data) => data.password === data.confirmPassword, {
  message: 'Passwords do not match',
  path: ['confirmPassword'],
});

// Extract the TypeScript type from the schema
export type RegistrationFormValues = z.infer<typeof registrationSchema>;

Integrating Schema with useForm

VeeValidate's useForm hook accepts a validationSchema property. When using Zod, you must pass the schema directly. This tells VeeValidate to delegate all validation checks to Zod's engine.

<script setup lang="ts">
import { useForm } from 'veevalidate';
import { toTypedSchema } from '@veevalidate/zod';
import { registrationSchema, type RegistrationFormValues } from './schemas/registration';

// toTypedSchema converts the Zod schema into a format VeeValidate understands
const { handleSubmit, errors, defineField } = useForm<RegistrationFormValues>({
  validationSchema: toTypedSchema(registrationSchema),
});

// defineField creates a binding for the input and its error state
const [username, usernameProps] = defineField('username');
const [email, emailProps] = defineField('email');
const [password, passwordProps] = defineField('password');
const [confirmPassword, confirmPasswordProps] = defineField('confirmPassword');

const onSubmit = handleSubmit((values) => {
  console.log('Form submitted successfully:', values);
  // 'values' is now typed as RegistrationFormValues
});
</script>

<template>
  <form @submit="onSubmit">
    <input v-model="username" v-bind="usernameProps" placeholder="Username" />
    <span>{{ errors.username }}</span>

    <input v-model="email" v-bind="emailProps" placeholder="Email" />
    <span>{{ errors.email }}</span>

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

    <input v-model="confirmPassword" v-bind="confirmPasswordProps" type="password" />
    <span>{{ errors.confirmPassword }}</span>

    <button type="submit">Register</button>
  </form>
</template>

Diagnostic Checks and Verification

To ensure the integration is functioning correctly, perform the following checks:

• Immediate Feedback: Enter a value that violates a constraint (e.g., a 2-character username). The errors.username object should populate immediately upon the blur event or according to the configured validation trigger.
• Cross-Field Validation: Enter different values in the password and confirmPassword fields. The refine block in the Zod schema should trigger an error specifically on the confirmPassword field.
• Submission Block: Attempt to submit the form with empty fields. The onSubmit callback should not execute, and all required fields should display their respective Zod error messages.

Engineering Trade-offs and Limitations

Critical Limitation: Do not mix rules props on individual components with a global validationSchema. Doing so can cause race conditions where the template rule overrides the schema result, leading to inconsistent UI states where an input appears valid but the form fails to submit.

Rollback Procedure

If the schema-based approach causes performance degradation or integration conflicts, revert to standard VeeValidate field validation by:

1. Removing the validationSchema property from useForm.
2. Removing the toTypedSchema wrapper.
3. Moving validation logic back into the rules prop of the Field component or using the setFieldError method for manual control.