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

At its core, this package exports one function useValidation, plus some type definitions for when using TypeScript.

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 formData

FormData has a structure similar to any other object you would write for v-model data binding, the only difference being that together with every property, you can provide rules to display validation errors. Let's look at an example, how rules can be added to some formData:

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 | Ref<T>
  $rules?: Rule<T>[]
}

useValidation exposes the following state

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

Form is a reactive object with identical structure as the formData 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>
}

Below is a description of all the properties and their use case:

• $uid { number } The unique id of this field. For dynamic forms, this 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[] } A 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 the field has any pending rules.
• $touched { boolean } True if the field is touched. In most cases, this value should be set together with the blur event. Either through $validate or manually.
• $dirty { boolean } True if the $value of this field has changed at least once.
• $validate { function } Validate this field.

$validate([options])

• options { object } Validation options to use.
  • setTouched { boolean }
  • force { boolean }