Validation Rules

Note

We recommend using FormCreate's built-in validation engine for form validation. See Form Validation (v2)

Form props

How to Use Validation Rules in Forms

Validation Rule Description

Key Name	Description	Type
required	Marks the field as required. Validation fails when the value is empty (empty string, empty array, false, undefined, or null)	boolean
message	Error message to display. Can be a function that returns dynamic message content	string | (value, rule) => string
validator	Custom validation function. Can return a Promise for async validation	(value, rule) => boolean | string | Promise
pattern	Regular expression for validation. Validation fails if the value doesn't match	RegExp
trigger	When to trigger validation. Takes precedence over the Form component's validate-trigger attribute. Options: onChange, onBlur, onSubmit	string | string[]
formatter	Function to format the field value before validation	(value, rule) => any
validateEmpty	Whether validator and pattern should validate empty values. Defaults to true. Set to false to skip validation for empty values	boolean

Note

• Vant's validator returns boolean, string, or Promise (no callback needed)
• Vant's message can be a function that returns dynamic error messages
• Vant's trigger options: onChange, onBlur, onSubmit
• Access component and form information via this.rule and this.api in custom validation

Common Validation Examples

1. Required Field Validation

const rule = {
    type: 'input',
    field: 'username',
    title: 'Username',
    validate: [
        { required: true, message: 'Username is required', trigger: 'onBlur' }
    ]
}

2. Length Validation

Minimum Length Validation

const rule = {
    type: 'input',
    field: 'password',
    title: 'Password',
    validate: [
        { 
            required: true, 
            validator: (value) => {
                if (!value || value.length < 6) {
                    return 'Password must be at least 6 characters';
                }
                return true;
            },
            trigger: 'onBlur' 
        }
    ]
}

Maximum Length Validation

const rule = {
    type: 'input',
    field: 'description',
    title: 'Product Description',
    props: {
        type: 'textarea',
        maxlength: 200,
    },
    validate: [
        { 
            validator: (value) => {
                if (value && value.length > 200) {
                    return 'Description cannot exceed 200 characters';
                }
                return true;
            },
            trigger: 'onBlur' 
        }
    ]
}

3. Regular Expression Validation

const rule = {
    type: 'input',
    field: 'phone',
    title: 'Phone Number',
    validate: [
        { required: true, message: 'Phone number is required', trigger: 'onBlur' },
        { pattern: /^1[3-9]\d{9}$/, message: 'Please enter a valid phone number', trigger: 'onBlur' }
    ]
}

Email Validation

const rule = {
    type: 'input',
    field: 'email',
    title: 'Email',
    validate: [
        { required: true, message: 'Email is required', trigger: 'onBlur' },
        { 
            pattern: /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/, 
            message: 'Please enter a valid email address', 
            trigger: 'onBlur' 
        }
    ]
}

4. Number Range Validation

const rule = {
    type: 'stepper',
    field: 'age',
    title: 'Age',
    props: {
        min: 0,
        max: 120,
    },
    validate: [
        { required: true, message: 'Age is required', trigger: 'onChange' },
        { 
            validator: (value) => {
                if (value < 18 || value > 65) {
                    return 'Age must be between 18 and 65';
                }
                return true;
            },
            trigger: 'onChange' 
        }
    ]
}

5. Custom Validation

const rule = {
    type: 'input',
    field: 'age',
    title: 'Age',
    validate: [
        {
            validator: (value) => {
                if (value < 18) {
                    return 'Age must be at least 18';
                } else if (value > 65) {
                    return 'Age cannot exceed 65';
                }
                return true;
            },
            trigger: 'onBlur'
        }
    ]
}

Custom Validation (Access Other Fields)

const rule = [
    {
        type: 'input',
        field: 'password',
        title: 'Password',
        validate: [
            { 
                required: true, 
                validator: (value) => {
                    if (!value || value.length < 6) {
                        return 'Password must be at least 6 characters';
                    }
                    return true;
                },
                trigger: 'onBlur' 
            }
        ]
    },
    {
        type: 'input',
        field: 'confirmPassword',
        title: 'Confirm Password',
        validate: [
            { required: true, message: 'Please confirm your password', trigger: 'onBlur' },
            {
                validator: (value) => {
                    // Access other field values via this.api
                    const password = this.api.getValue('password');
                    if (value !== password) {
                        return 'Passwords do not match';
                    }
                    return true;
                },
                trigger: 'onBlur'
            }
        ]
    }
]

6. Asynchronous Validation

const rule = {
    type: 'input',
    field: 'username',
    title: 'Username',
    validate: [
        { required: true, message: 'Username is required', trigger: 'onBlur' },
        {
            validator: (value) => {
                // Return Promise for asynchronous validation
                return new Promise((resolve) => {
                    checkUsernameExists(value).then(exists => {
                        if (exists) {
                            resolve('Username already exists');
                        } else {
                            resolve(true);
                        }
                    });
                });
            },
            trigger: 'onBlur'
        }
    ]
}

7. Array/Multiple Selection Validation

Minimum Selection Validation

const rule = {
    type: 'checkbox',
    field: 'tags',
    title: 'Product Tags',
    value: [],
    options: [
        { value: '1', label: 'Hot Sale' },
        { value: '2', label: 'New Product' },
        { value: '3', label: 'Recommended' },
        { value: '4', label: 'Limited Time' },
    ],
    validate: [
        { 
            required: true, 
            validator: (value) => {
                if (!value || value.length < 2) {
                    return 'Please select at least 2 tags';
                }
                return true;
            },
            trigger: 'onChange' 
        }
    ]
}

Maximum Selection Validation

const rule = {
    type: 'checkbox',
    field: 'categories',
    title: 'Product Categories',
    value: [],
    options: [
        { value: '1', label: 'Electronics' },
        { value: '2', label: 'Clothing & Accessories' },
        { value: '3', label: 'Home Goods' },
    ],
    validate: [
        { 
            validator: (value) => {
                if (value && value.length > 2) {
                    return 'Select up to 2 categories';
                }
                return true;
            },
            trigger: 'onChange' 
        }
    ]
}

8. Dynamic Error Messages

const rule = {
    type: 'input',
    field: 'password',
    title: 'Password',
    validate: [
        { 
            required: true, 
            message: (value, rule) => {
                if (!value) {
                    return 'Password is required';
                }
                if (value.length < 6) {
                    return `Password must be at least 6 characters (currently ${value.length})`;
                }
                return '';
            },
            trigger: 'onBlur' 
        }
    ]
}

9. Combined Validation

const rule = {
    type: 'input',
    field: 'username',
    title: 'Username',
    validate: [
        { required: true, message: 'Username is required', trigger: 'onBlur' },
        { 
            validator: (value) => {
                if (value.length < 3 || value.length > 20) {
                    return 'Username must be between 3 and 20 characters';
                }
                if (!/^[a-zA-Z0-9_]+$/.test(value)) {
                    return 'Username can only contain letters, numbers, and underscores';
                }
                return true;
            },
            trigger: 'onBlur' 
        }
    ]
}

10. Conditional Validation

const rule = [
    {
        type: 'switch',
        field: 'enableDiscount',
        title: 'Enable Discount',
        value: false,
    },
    {
        type: 'stepper',
        field: 'discount',
        title: 'Discount Rate',
        props: {
            min: 0,
            max: 1,
            step: 0.1,
            decimalLength: 2,
        },
        validate: [
            {
                validator: (value) => {
                    const enableDiscount = this.api.getValue('enableDiscount');
                    if (enableDiscount && (!value || value <= 0)) {
                        return 'Discount rate must be greater than 0 when discount is enabled';
                    }
                    return true;
                },
                trigger: 'onChange'
            }
        ]
    }
]

11. Validation After Formatting

const rule = {
    type: 'input',
    field: 'phone',
    title: 'Phone Number',
    validate: [
        { 
            required: true, 
            formatter: (value) => {
                // Remove all non-numeric characters
                return value.replace(/\D/g, '');
            },
            validator: (value) => {
                if (value.length !== 11) {
                    return 'Phone number must be 11 digits';
                }
                if (!/^1[3-9]\d{9}$/.test(value)) {
                    return 'Please enter a valid phone number';
                }
                return true;
            },
            trigger: 'onBlur' 
        }
    ]
}