Documentation

Getting Started

Install vue3-form-validation with your favorite package manager:

yarn add vue3-form-validation
# or with npm
npm install vue3-form-validation

Configure the validation through createValidation and pass it to the app:

import { createValidation } from 'vue3-form-validation'

const validation = createValidation({
  defaultValidationBehavior: 'lazier',
  validationBehavior: {}
})

app.use(validation)

Start using useValidation in your components.

API

import { useValidation } from 'vue3-form-validation'

const {
  form,
  submitting,
  validating,
  errors,
  hasError,
  validateFields,
  resetFields,
  add,
  remove
} = useValidation({})

useValidation takes the following parameters:

• formData {object} The structure of your form data.

The form data object has a structure that is similar to any other object you would write for v-model data binding. The only difference being that together with every value you can provide rules to display validation errors. Let's look at an example how the structure of some form data can be converted to an object with the addition of rules:

const formData = {
  email: '',
  password: ''
}

The above can be converted to the following:

const formData = {
  email: {
    $value: '',
    $rules: [email => !email && 'Please enter your email address']
  },
  password: {
    $value: '',
    $rules: [
      password =>
        password.length > 7 || 'Password has to be longer than 7 characters'
    ]
  }
}

FormData can contain arrays and can be deeply nested. At the leaf level, the object should contain fields whose simplified type definition looks like the following:

type Field<T> = {
  $value: T
  $rules?: Rule<T>[] // the list of rules is optional
}

useValidation exposes the following state

• form {object} A transformed form data object.
• submitting {Ref<boolean>} True during validation after calling validateFields when there were any rules that returned a Promise.
• validating {ComputedRef<boolean>} True while there are any asynchronous rules that are executing.
• errors {ComputedRef<string[]>} All current validation error messages.
• hasError {ComputedRef<boolean>} True while there are any validation errors on the form.

Form is a reactive object with identical structure as the form data input but with added metadata to every field. All objects with a $value are converted to an object of the following type:

type TransformedField<T> = {
  $uid: number
  $value: T
  $errors: string[]
  $rawErrors: (string | null)[]
  $hasError: boolean
  $validating: boolean
  $touched: boolean
  $dirty: boolean
  $validate(options?: ValidateOptions): void
}

Given the data of the previous example this would result in the structure below:

type Form = {
  email: TransformedField<string>
  password: TransformedField<string>
}

As you may have noticed, all of the properties are prefixed with the $ symbol, which is to distinguish them from other properties but also to avoid naming conflicts.

• $uid {number} The unique id of this field. Can be used as the key attribute in v-for.
• $value {any} The current field's value. Intended to be used together with v-model.
• $errors {string[]} List of validation error messages local to this field without null values.
• $rawErrors {(string | null)[]} The field's raw error messages one for each rule and null if there is no error.
• $hasError {boolean} True while there are any errors on this field.
• $validating {boolean} True while there are any async rules validating.
• $touched {boolean} True if this field has been touched. In most cases, this value should be set together with the blur event. Either through $validate or manually.
• $dirty {boolean} True when the $value of this field has been changed at least once.
• $validate {function} Validate this field.