summary	The String data type is used to validate string values including their formatting

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.

{
  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 {{ originalField }} 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',
  vat: 'The {{ field }} field must be a valid VAT number',
}

vine.messagesProvider = new SimpleMessagesProvider(messages)

Validations

Following is the list of validation rules you can apply on a string.

email

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.

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({
      as: '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.

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 (1 through 8).

vine.object({
  id: vine
    .string()
    .uuid({ version: [4] })
})

// Enforce multiple version.
vine.object({
  id: vine
    .string()
    .uuid({ version: [2, 4, 5, 7] })
})

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,
      }
    })
})

To validate international phone numbers, including landlines and mobiles, simply install the @julienbenac/vine-plugin-phone plugin. This rule is provided as a separate plugin to keep the VineJS core lightweight and fast.

See the example below, and refer to the plugin documentation for more details.

vine.object({
  contact_number: vine
    .string()
    .phone({ countryCode: 'IN' })
})

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]
      }
    })
})

vat

Ensure the field's value is formatted as a valid VAT number for a given or multiple country codes.

vine.object({
  vat_number: vine
    .string()
    .vat({ countryCode: ['IN'] })
})

You may define a callback function to compute the options at runtime.

vine.object({
  vat_number: vine
    .string()
    .vat((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()
})

Uh oh!

FilesExpand file tree

string.md

Latest commit

History

string.md

File metadata and controls

String type

Defining error messages

Validations

email

regex

url

activeUrl

alpha

alphaNumeric

minLength

maxLength

fixedLength

confirmed

endsWith

startsWith

sameAs

notSameAs

in

notIn

ipAddress

uuid

ulid

ascii

creditCard

hexCode

iban

jwt

coordinates

mobile

passport

postalCode

vat

Mutations

trim

normalizeEmail

normalizeUrl

escape

toUpperCase

toCamelCase

toLowerCase