0
# @vuelidate/validators
1

2
@vuelidate/validators is a comprehensive collection of validation functions designed for Vue.js applications using the Vuelidate validation library. It provides common validators like required, email, minLength, maxLength, numeric, and more with built-in error messages and customization options. The library supports both Vue 2.x and Vue 3.x through vue-demi, making it highly reusable across different Vue.js project versions.
3

4
## Package Information
5

6
- **Package Name**: @vuelidate/validators
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install @vuelidate/validators`
10

11
## Core Imports
12

13
```javascript
14
import { required, email, minLength, helpers } from "@vuelidate/validators";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { required, email, minLength, helpers } = require("@vuelidate/validators");
21
```
22

23
Raw validators without built-in messages:
24

25
```javascript
26
import { required, email, minLength } from "@vuelidate/validators/raw";
27
```
28

29
## Basic Usage
30

31
```javascript
32
import { required, email, minLength, maxLength, sameAs } from "@vuelidate/validators";
33
import { computed } from "vue";
34

35
// Define validation rules for a form
36
const formData = { password: "" };
37

38
const validationRules = {
39
  username: { required, minLength: minLength(3) },
40
  email: { required, email },
41
  password: { required, minLength: minLength(8) },
42
  confirmPassword: { 
43
    required, 
44
    sameAsPassword: sameAs(computed(() => formData.password))
45
  }
46
};
47

48
// The validators are validation objects with $validator, $message, and $params
49
const emailValidator = email;
50
const lengthValidator = minLength(5);
51
```
52

53
## Architecture
54

55
@vuelidate/validators is built around several key components:
56

57
- **Core Validators**: Fundamental validation functions (required, email, length constraints, etc.)
58
- **Format Validators**: Specialized validators for specific formats (email, URL, IP address, MAC address)
59
- **Logical Operators**: Combinators for complex validation logic (and, or, not)
60
- **Helper Functions**: Utilities for customizing validators (withMessage, withParams, withAsync)
61
- **Internationalization**: Support for translatable error messages via createI18nMessage
62
- **Vue Integration**: Reactive parameter support using Vue refs for dynamic validation
63

64
## Capabilities
65

66
### Core Validators
67

68
Essential validation functions for common form validation scenarios including required fields, string/numeric format validation, and length constraints.
69

70
```javascript { .api }
71
// Required field validation
72
const required: ValidationRuleWithoutParams;
73

74
// String format validators
75
const alpha: ValidationRuleWithoutParams;
76
const alphaNum: ValidationRuleWithoutParams;
77
const numeric: ValidationRuleWithoutParams;
78
const decimal: ValidationRuleWithoutParams;
79
const integer: ValidationRuleWithoutParams;
80

81
// Length and value constraints
82
function minLength(min: number | Ref<number>): ValidationRuleWithParams<{ min: number }>;
83
function maxLength(max: number | Ref<number>): ValidationRuleWithParams<{ max: number }>;
84
function minValue(min: number | Ref<number> | string | Ref<string>): ValidationRuleWithParams<{ min: number }>;
85
function maxValue(max: number | Ref<number> | string | Ref<string>): ValidationRuleWithParams<{ max: number }>;
86
function between(min: number | Ref<number>, max: number | Ref<number>): ValidationRuleWithParams<{ min: number, max: number }>;
87
```
88

89
[Core Validators](./core-validators.md)
90

91
### Format Validators
92

93
Specialized validators for validating specific data formats such as email addresses, URLs, and network addresses.
94

95
```javascript { .api }
96
// Network and format validators
97
const email: ValidationRuleWithoutParams;
98
const url: ValidationRuleWithoutParams;
99
const ipAddress: ValidationRuleWithoutParams;
100
function macAddress(separator: string | Ref<string>): ValidationRuleWithoutParams;
101
```
102

103
[Format Validators](./format-validators.md)
104

105
### Conditional and Comparison Validators
106

107
Validators for conditional validation logic and value comparison operations.
108

109
```javascript { .api }
110
// Conditional validators
111
function requiredIf(prop: boolean | Ref<boolean> | string | (() => boolean | Promise<boolean>)): ValidationRuleWithoutParams;
112
function requiredUnless(prop: boolean | Ref<boolean> | string | (() => boolean | Promise<boolean>)): ValidationRuleWithoutParams;
113

114
// Comparison validator
115
function sameAs<E = unknown>(equalTo: E | Ref<E>, otherName?: string): ValidationRuleWithParams<{ equalTo: E, otherName: string }>;
116
```
117

118
[Conditional and Comparison Validators](./conditional-validators.md)
119

120
### Logical Operators
121

122
Combinators for creating complex validation logic by combining multiple validators with logical operations.
123

124
```javascript { .api }
125
// Logical combinators
126
function and<T = unknown>(...validators: ValidationRule<T>[]): ValidationRuleWithoutParams;
127
function or<T = unknown>(...validators: ValidationRule<T>[]): ValidationRuleWithoutParams;
128
function not<T = unknown>(validator: ValidationRule<T>): ValidationRuleWithoutParams;
129
```
130

131
[Logical Operators](./logical-operators.md)
132

133
### Helper Functions and Utilities
134

135
Utility functions for customizing validators with parameters, messages, async behavior, and array validation.
136

137
```javascript { .api }
138
const helpers: {
139
  withParams: <T = unknown>(params: object, validator: ValidationRule<T>) => ValidationRuleWithParams;
140
  withMessage: <T = unknown>(message: string | ((params: MessageProps) => string), validator: ValidationRule<T>) => ValidationRuleWithParams;
141
  withAsync: Function;
142
  forEach: (validators: ValidationArgs) => { $validator: ValidationRule, $message: () => string };
143
  req: (value: any) => boolean;
144
  len: (value: any) => number;
145
  regex: (...expr: RegExp[]) => (value: any) => boolean;
146
  unwrap: (value: any) => any;
147
  unwrapNormalizedValidator: Function;
148
  unwrapValidatorResponse: Function;
149
  normalizeValidatorObject: Function;
150
};
151
```
152

153
[Helper Functions and Utilities](./helpers-utilities.md)
154

155
### Internationalization
156

157
Internationalization support for creating translatable validation error messages.
158

159
```javascript { .api }
160
// I18n message creation
161
function createI18nMessage({ 
162
  t, 
163
  messagePath?, 
164
  messageParams? 
165
}: {
166
  t: typeof TranslationFunction;
167
  messagePath?: typeof messagePathFactory;
168
  messageParams?: typeof messageParamsFactory;
169
}): typeof withI18nMessage;
170

171
// Translation function type
172
export function TranslationFunction(
173
  path: string, 
174
  params: { model: string, property: string, [key: string]: any }
175
): string;
176

177
// Helper factory functions  
178
export function messagePathFactory(params: MessageProps): string;
179
export function messageParamsFactory(params: MessageParams): MessageParams;
180
```
181

182
[Internationalization](./internationalization.md)
183

184
## Types
185

186
```javascript { .api }
187
// Core validation types (imported from @vuelidate/core)
188
type ValidationRuleWithoutParams = () => boolean;
189
type ValidationRuleWithParams<T = object> = { 
190
  $validator: Function, 
191
  $params: T, 
192
  $message?: string | Function 
193
};
194
type ValidationRule<T = unknown> = ValidationRuleWithoutParams | ValidationRuleWithParams | Function;
195
type ValidatorWrapper = (...args: any[]) => ValidationRule;
196

197
// Message-related types
198
interface MessageProps {
199
  $model: string;
200
  $property: string;
201
  $params: { [attr: string]: any };
202
  $validator: string;
203
  $pending: boolean;
204
  $invalid: boolean;
205
  $response: unknown;
206
  $propertyPath: string;
207
}
208

209
interface MessageParams {
210
  model: unknown;
211
  property: string;
212
  invalid: boolean;
213
  pending: boolean;
214
  propertyPath: string;
215
  response: unknown;
216
  validator: string;
217
  [key: string]: any;
218
}
219
```