String type
Ensure the field's value is a valid string. Empty strings are allowed, and you must handle them using the convertEmptyStringsToNull configuration option.
import vine from '@vinejs/vine'
const schema = vine.object({
username: vine.string()
})
Using the following modifiers, you may mark the field as optional or nullable.
See also: Working with undefined and null values
{
username: vine.string().nullable()
}
{
username: vine.string().optional()
}
Defining error messages
You may define custom error messages for the following string-based rules.
const messages = {
string: 'The {{ field }} field must be a string',
email: 'The {{ field }} field must be a valid email address',
regex: 'The {{ field }} field format is invalid',
url: 'The {{ field }} field must be a valid URL',
activeUrl: 'The {{ field }} field must be a valid URL',
alpha: 'The {{ field }} field must contain only letters',
alphaNumeric: 'The {{ field }} field must contain only letters and numbers',
minLength: 'The {{ field }} field must have at least {{ min }} characters',
maxLength: 'The {{ field }} field must not be greater than {{ max }} characters',
fixedLength: 'The {{ field }} field must be {{ size }} characters long',
confirmed: 'The {{ field }} field and {{ otherField }} field must be the same',
endsWith: 'The {{ field }} field must end with {{ substring }}',
startsWith: 'The {{ field }} field must start with {{ substring }}',
sameAs: 'The {{ field }} field and {{ otherField }} field must be the same',
notSameAs: 'The {{ field }} field and {{ otherField }} field must be different',
in: 'The selected {{ field }} is invalid',
notIn: 'The selected {{ field }} is invalid',
ipAddress: 'The {{ field }} field must be a valid IP address',
uuid: 'The {{ field }} field must be a valid UUID',
ulid: 'The {{ field }} field must be a valid ULID',
ascii: 'The {{ field }} field must only contain ASCII characters',
creditCard: 'The {{ field }} field must be a valid {{ providersList }} card number',
hexCode: 'The {{ field }} field must be a valid hex color code',
iban: 'The {{ field }} field must be a valid IBAN number',
jwt: 'The {{ field }} field must be a valid JWT token',
coordinates: 'The {{ field }} field must contain latitude and longitude coordinates',
mobile: 'The {{ field }} field must be a valid mobile phone number',
passport: 'The {{ field }} field must be a valid passport number',
postalCode: 'The {{ field }} field must be a valid postal code',
}
vine.messagesProvider = new SimpleMessagesProvider(messages)
Validations
Following is the list of validation rules you can apply on a string.
Validate the field's value to be a valid email address. The validation is performed using the validator.js library, and you may pass all the options accepted by the validator.isEmail method.
See also: normalizeEmail
vine.object({
email: vine
.string()
.email(optionsGoesHere)
})
regex
Validate the field's value against a pre-defined regular expression.
vine.object({
username: vine
.string()
.regex(/^[a-zA-Z0-9]+$/)
})
vine.object({
username: vine
.string()
.regex(new RegExp('^[a-zA-Z0-9]+$'))
})
url
Validate the field's value to be a valid URL. The validation is performed using the validator.js library, and you may pass all the options accepted by the validator.isURL method.
vine.object({
health_checks_url: vine
.string()
.url({
require_protocol: true,
protocols: ['http','https','ftp']
})
})
activeUrl
Ensure the URL value of a field has valid A or AAAA DNS records. The DNS lookup is performed using the dnsPromises.resolve method.
vine.object({
health_checks_url: vine
.string()
.activeUrl()
})
alpha
Validate the field's value only to contain letters, i.e.: [a-z] and [A-Z]. Optionally allow spaces, underscore, and dashes as well.
vine.object({
username: vine
.string()
.alpha({
allowSpaces: false,
allowUnderscores: true,
allowDashes: true,
})
})
alphaNumeric
Validate the field's value only to contain letters and numbers, i.e.: [a-z], [A-Z], and [0-9]. Optionally allow spaces, underscore, and dashes as well.
vine.object({
username: vine
.string()
.alphaNumeric({
allowSpaces: false,
allowUnderscores: true,
allowDashes: true,
})
})
minLength
Enforce the string to have the minimum pre-defined length.
vine.object({
password: vine
.string()
.minLength(8)
})
maxLength
Enforce the string to have the maximum pre-defined length.
vine.object({
password: vine
.string()
.maxLength(32)
})
fixedLength
Enforce the string to have a fixed length.
vine.object({
pan_number: vine
.string()
.fixedLength(10)
})
confirmed
Ensure the field under validation is confirmed by having another field with the same name and _confirmation suffix.
For example, You may use this rule to ensure the user confirms their password by typing it twice. If the field name is password, the confirmation field name must be password_confirmation.
const schema = vine.object({
password: vine
.string()
.confirmed()
})
const data = {
password: 'secret',
password_confirmation: 'secret'
}
const validator = vine.compile(schema)
await validator.validate(data)
You may modify the confirmation field name as follows.
const schema = vine.object({
password: vine
.string()
.confirmed({
confirmationField: 'passwordConfirmation'
})
})
endsWith
Ensure the field's value ends with the pre-defined substring.
vine.object({
email: vine
.string()
.endsWith('client_app.com')
})
startsWith
Ensure the field's value starts with the pre-defined substring.
vine.object({
email: vine
.string()
.startsWith('+91')
})
sameAs
Ensure the field's value under validation is the same as the other field's value.
vine.object({
password: vine.string(),
password_confirmation: vine
.string()
.sameAs('password'),
})
notSameAs
Ensure the field's value under validation is different from another field's value.
vine.object({
old_email: vine.string().email(),
email: vine
.string()
.email()
.notSameAs('old_email')
})
in
Ensure the field's value under validation is a subset of the pre-defined list.
See also: Enum data type for better type inference
vine.object({
role: vine
.string()
.in(['admin', 'moderator', 'writer'])
})
You may defer computing the list values by registering a callback. The callback must return an array of values.
vine.object({
state: vine.string().in(statesList()),
city: vine
.string()
.in((field) => {
return citiesList(field.parent.state)
})
})
notIn
Ensure the field's value under validation is not inside the pre-defined list.
vine.object({
username: vine
.string()
.notIn(['admin', 'root', 'superuser'])
})
Like the in validation, you may defer computing the list values by registering a callback.
vine.object({
username: vine
.string()
.notIn(() => {
return ['admin', 'root', 'superuser']
})
})
ipAddress
Validate the field's value to be a valid IP Address. Optionally, you may enforce the IP version as 4 or 6. Both ipv4 and ipv6 values are allowed by default.
vine.object({
ip: vine
.string()
.ipAddress({ version: 4 })
})
uuid
Ensure the field's value to be a valid uuid. You may optionally enforce a specific uuid version (version 1, 2, 3, 4 or 5).
vine.object({
id: vine
.string()
.uuid({ version: [4] })
})
// Enforce multiple version.
vine.object({
id: vine
.string()
.uuid({ version: [2, 4, 5] })
})
ulid
Ensure the field's value to be a valid ulid according to the canonical specs.
vine.object({
id: vine
.string()
.ulid()
})
ascii
Ensure the value contains ASCII characters only.
vine.object({
greeting: vine
.string()
.ascii()
})
creditCard
Ensure the field's value is a valid credit card number. Optionally, you can define an array of providers from the following list.
- amex
- dinersclub
- discover
- jcb
- mastercard
- unionpay
- visa
vine.object({
credit_card: vine
.string()
.creditCard()
})
// Only allow mastercard credit cards
vine.object({
credit_card: vine
.string()
.creditCard({ provider: ['mastercard'] })
})
You may define a callback function to compute the credit card options at runtime.
vine.object({
credit_card: vine
.string()
.creditCard((field) => {
return {
provider: ['mastercard', 'amex', 'visa']
}
})
})
hexCode
Ensure the value is a valid hex code for a color.
vine.object({
primary_color: vine.string().hexCode()
})
iban
Ensure the value is a valid IBAN (International Bank Account Number).
vine.object({
iban: vine.string().iban()
})
jwt
Ensure the value is formatted as a valid JWT (JSON Web Token).
vine.object({
authorization: vine.string().jwt()
})
coordinates
Ensure the value is a string with latitude and longitude coordinates.
vine.object({
delivery_location: vine
.string()
.coordinates()
})
mobile
Ensure the field's value is a valid mobile number. The validation is performed using the validator.js library, and you may pass all the options accepted by the validator.isMobilePhone method.
vine.object({
contact_number: vine
.string()
.mobile()
})
You may define a callback function to compute the options at runtime.
vine.object({
contact_number: vine
.string()
.mobile((field) => {
return {
locale: ['en-IN'],
strictMode: true,
}
})
})
passport
Ensure the field's value is formatted as a valid passport number for a given or multiple country codes.
vine.object({
passport: vine
.string()
.passport({
countryCode: ['IN', 'US', 'GB']
})
})
You may define a callback function to compute the options at runtime.
vine.object({
passport: vine
.string()
.passport((field) => {
return {
countryCode: [field.parent.country_code]
}
})
})
postalCode
Ensure the field's value is formatted as a valid postal code. Optionally, you can define an array of country codes as well.
vine.object({
postal_code: vine
.string()
.postalCode({ countryCode: ['IN'] })
})
You may define a callback function to compute the options at runtime.
vine.object({
postal_code: vine
.string()
.postalCode((field) => {
return {
countryCode: [field.parent.country_code]
}
})
})
Mutations
Following is the list of mutations you can apply to a string value. As the name suggests, mutations normalize or change the input value and do not perform any validations.
trim
Trim whitespaces from the value.
vine.object({
email: vine.string().trim().email()
})
normalizeEmail
The normalizeEmail method normalizes the email address. The normalization is performed using the validator.js library, and you may pass all the options accepted by the validator.normalizeEmail method.
vine.object({
email: vine
.string()
.normalizeEmail({
all_lowercase: true,
gmail_remove_dots: true,
})
})
normalizeUrl
The normalizeUrl method normalizes a URL value. The normalization is performed using the normalize-url package, and you may pass all the options accepted by the package.
vine.object({
health_checks_url: vine
.string()
.normalizeUrl({
normalizeProtocol: true,
forceHttps: true,
stripHash: true,
})
})
escape
The escape method escapes HTML entities inside the string value.
vine.object({
about: vine.string().escape()
})
toUpperCase
Convert the field value to all uppercase.
vine.object({
role: vine
.string()
.toUpperCase()
})
toCamelCase
Convert the field value to camel case.
vine.object({
role: vine
.string()
.toCamelCase()
})
toLowerCase
Convert the field value to lowercase.
vine.object({
username: vine
.string()
.toLowerCase()
})