0
# VeeValidate
1
2
VeeValidate is a powerful Vue.js form validation library that provides comprehensive validation capabilities through both Composition API and component-based approaches. It offers field-level and form-level validation, dynamic field arrays, extensive state management, and seamless integration with popular validation schema libraries like Yup, Zod, and Joi.
3
4
## Package Information
5
6
- **Package Name**: vee-validate
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install vee-validate`
10
- **Peer Dependencies**: Vue.js ^3.4.26
11
12
## Core Imports
13
14
```typescript
15
import {
16
useForm,
17
useField,
18
validate,
19
defineRule,
20
Field,
21
Form,
22
ErrorMessage
23
} from "vee-validate";
24
```
25
26
For CommonJS:
27
28
```javascript
29
const {
30
useForm,
31
useField,
32
validate,
33
defineRule,
34
Field,
35
Form,
36
ErrorMessage
37
} = require("vee-validate");
38
```
39
40
## Basic Usage
41
42
```typescript
43
import { useForm, useField } from "vee-validate";
44
45
// Basic form with validation
46
const { handleSubmit, errors } = useForm();
47
48
const { value: email, errorMessage: emailError } = useField('email', (value) => {
49
if (!value) return 'Email is required';
50
if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) return 'Email is invalid';
51
return true;
52
});
53
54
const { value: password, errorMessage: passwordError } = useField('password', (value) => {
55
if (!value) return 'Password is required';
56
if (value.length < 6) return 'Password must be at least 6 characters';
57
return true;
58
});
59
60
const onSubmit = handleSubmit((values) => {
61
console.log('Form submitted:', values);
62
});
63
```
64
65
## Architecture
66
67
VeeValidate is built around several key architectural components:
68
69
- **Composition API**: Core composables (`useForm`, `useField`, `useFieldArray`) for reactive form state management
70
- **Vue Components**: Renderless components (`Field`, `Form`, `FieldArray`, `ErrorMessage`) for template-based forms
71
- **Validation Engine**: Flexible validation system supporting functions, rules, and schemas
72
- **State Management**: Comprehensive tracking of form state (touched, dirty, valid, errors, etc.)
73
- **Field Arrays**: Dynamic array field management for complex forms
74
- **Schema Integration**: Built-in support for Yup, Zod, Joi, and custom TypedSchema implementations
75
76
## Capabilities
77
78
### Core Validation
79
80
Core validation functions for standalone field and object validation without Vue context.
81
82
```typescript { .api }
83
function validate<TInput, TOutput>(
84
value: TInput,
85
rules: string | Record<string, unknown> | GenericValidateFunction | GenericValidateFunction[] | TypedSchema,
86
options?: ValidationOptions
87
): Promise<ValidationResult<TOutput>>;
88
89
function validateObject<TValues extends GenericObject, TOutput extends GenericObject = TValues>(
90
schema: RawFormSchema<TValues>,
91
values: TValues,
92
options?: { names?: Record<string, string>; bailsMap?: Record<string, boolean> }
93
): Promise<FormValidationResult<TValues, TOutput>>;
94
```
95
96
[Core Validation](./core-validation.md)
97
98
### Form Management
99
100
Form-level composables for managing complete form state, validation, and submission handling.
101
102
```typescript { .api }
103
function useForm<TValues extends GenericObject = GenericObject, TOutput extends GenericObject = TValues>(
104
options?: FormOptions<TValues>
105
): FormContext<TValues, TOutput>;
106
107
function useFormContext<TValues extends GenericObject = GenericObject, TOutput extends GenericObject = TValues>(): FormContext<TValues, TOutput>;
108
```
109
110
[Form Management](./form-management.md)
111
112
### Field Management
113
114
Field-level composables for individual field validation, state management, and value binding.
115
116
```typescript { .api }
117
function useField<TValue = unknown>(
118
path: MaybeRefOrGetter<string>,
119
rules?: MaybeRef<RuleExpression<TValue>>,
120
options?: Partial<FieldOptions<TValue>>
121
): FieldContext<TValue>;
122
123
function useFieldArray<TValue = unknown>(
124
arrayPath: MaybeRefOrGetter<string>
125
): FieldArrayContext<TValue>;
126
```
127
128
[Field Management](./field-management.md)
129
130
### State Access
131
132
Composables for accessing reactive form and field state information.
133
134
```typescript { .api }
135
function useFieldValue<TValue = unknown>(path?: MaybeRefOrGetter<string>): ComputedRef<TValue | undefined>;
136
function useFieldError(path?: MaybeRefOrGetter<string>): ComputedRef<string | undefined>;
137
function useFormValues<TValues extends GenericObject = GenericObject>(): ComputedRef<Partial<TValues>>;
138
function useFormErrors<TValues extends GenericObject = GenericObject>(): ComputedRef<FormErrors<TValues>>;
139
```
140
141
[State Access](./state-access.md)
142
143
### Form Actions
144
145
Composables for programmatically controlling form behavior, validation, and state mutations.
146
147
```typescript { .api }
148
function useValidateForm(): (opts?: Partial<ValidationOptions>) => Promise<FormValidationResult>;
149
function useValidateField(): <TPath extends Path<any>>(path: TPath, opts?: Partial<ValidationOptions>) => Promise<ValidationResult>;
150
function useSubmitForm(): <TReturn = unknown>(
151
onSubmit?: SubmissionHandler<any, any, TReturn>,
152
onInvalidSubmit?: InvalidSubmissionHandler
153
) => (e?: Event) => Promise<TReturn | undefined>;
154
function useResetForm(): (state?: Partial<FormState>, opts?: Partial<ResetFormOpts>) => void;
155
```
156
157
[Form Actions](./form-actions.md)
158
159
### Vue Components
160
161
Renderless Vue components for template-based form development with validation.
162
163
```typescript { .api }
164
// Field component for individual form fields
165
interface FieldProps {
166
name: string;
167
rules?: RuleExpression;
168
as?: string | Component;
169
validateOnMount?: boolean;
170
validateOnBlur?: boolean;
171
validateOnChange?: boolean;
172
validateOnInput?: boolean;
173
validateOnModelUpdate?: boolean;
174
bails?: boolean;
175
label?: string;
176
uncheckedValue?: any;
177
modelValue?: any;
178
keepValue?: boolean;
179
}
180
181
// Form component for form context
182
interface FormProps {
183
as?: string | Component;
184
validationSchema?: object;
185
initialValues?: object;
186
initialErrors?: object;
187
initialTouched?: object;
188
validateOnMount?: boolean;
189
onSubmit?: SubmissionHandler;
190
onInvalidSubmit?: InvalidSubmissionHandler;
191
keepValues?: boolean;
192
name?: string;
193
}
194
```
195
196
[Vue Components](./vue-components.md)
197
198
### Configuration and Rules
199
200
Global configuration and custom validation rule definition.
201
202
```typescript { .api }
203
function defineRule<TValue = unknown, TParams extends any[] = any[]>(
204
id: string,
205
validator: ValidationRuleFunction<TValue, TParams> | SimpleValidationRuleFunction<TValue, TParams>
206
): void;
207
208
function configure(config: Partial<VeeValidateConfig>): void;
209
210
interface VeeValidateConfig {
211
bails?: boolean;
212
generateMessage?: ValidationMessageGenerator;
213
validateOnInput?: boolean;
214
validateOnChange?: boolean;
215
validateOnBlur?: boolean;
216
validateOnModelUpdate?: boolean;
217
}
218
```
219
220
[Configuration and Rules](./configuration-rules.md)
221
222
## Core Types
223
224
```typescript { .api }
225
interface ValidationResult<TValue = unknown> {
226
errors: string[];
227
valid: boolean;
228
value?: TValue;
229
}
230
231
interface FormValidationResult<TInput extends GenericObject, TOutput extends GenericObject = TInput> {
232
valid: boolean;
233
results: Partial<FlattenAndMapPathsValidationResult<TInput, TOutput>>;
234
errors: Partial<Record<Path<TInput>, string>>;
235
values?: Partial<TOutput>;
236
source: 'schema' | 'fields' | 'none';
237
}
238
239
interface FieldMeta<TValue> {
240
touched: boolean;
241
dirty: boolean;
242
valid: boolean;
243
validated: boolean;
244
required: boolean;
245
pending: boolean;
246
initialValue?: TValue;
247
}
248
249
interface FormMeta<TValues extends GenericObject> {
250
touched: boolean;
251
dirty: boolean;
252
valid: boolean;
253
pending: boolean;
254
initialValues?: Partial<TValues>;
255
}
256
257
interface FieldState<TValue = unknown> {
258
value: TValue;
259
touched: boolean;
260
errors: string[];
261
}
262
263
interface FormState<TValues> {
264
values: PartialDeep<TValues>;
265
errors: Partial<Record<Path<TValues>, string | undefined>>;
266
touched: Partial<Record<Path<TValues>, boolean>>;
267
submitCount: number;
268
}
269
270
interface TypedSchema<TInput = any, TOutput = TInput> {
271
__type: 'VVTypedSchema';
272
parse(values: TInput, context?: TypedSchemaContext): Promise<{ value?: TOutput; errors: TypedSchemaError[] }>;
273
cast?(values: Partial<TInput>): TInput;
274
describe?(path?: Path<TInput>): Partial<TypedSchemaPathDescription>;
275
}
276
277
type GenericValidateFunction<TValue = unknown> = (
278
value: TValue,
279
ctx: FieldValidationMetaInfo
280
) => MaybePromise<boolean | MaybeArray<string>>;
281
282
type Path<T> = T extends any ? PathInternal<T, T, true> & string : never;
283
type PathValue<T, P extends Path<T> | ArrayPath<T>> = T extends any
284
? P extends `${infer K}.${infer R}`
285
? K extends keyof T
286
? R extends Path<T[K]>
287
? PathValue<T[K], R>
288
: never
289
: K extends `${ArrayKey}`
290
? T extends ReadonlyArray<infer V>
291
? PathValue<V, R & Path<V>>
292
: never
293
: never
294
: P extends keyof T
295
? T[P]
296
: P extends `${ArrayKey}`
297
? T extends ReadonlyArray<infer V>
298
? V
299
: never
300
: never
301
: never;
302
303
type GenericObject = Record<string, any>;
304
type MaybeRef<T> = T | Ref<T>;
305
type MaybeRefOrGetter<T> = T | Ref<T> | (() => T);
306
type MaybePromise<T> = T | Promise<T>;
307
type MaybeArray<T> = T | T[];
308
```