use-validation

Light validation function.

• vanilla js, framework independent
• 5 modes of validation
• includes common validators with validation messages
• customizable validators and validation messages

Usage:

useValidation function takes two arguments:

• object that should contain rules array and number of optional properties to customize validation for specific input,
• callback that is called after each validation. The results of the validation are in the callback argument.

useValidation function returns object that contains functions (touch, formValidate, reset) to perform validation related actions on the input.

let validation = useValidation(options, callback)

Arguments:

{
    name: String,
    rules: Array,
    mode: String,
    messages: Object,
},
callback: Function

• rules - an array of validation rules where each item is a name of validator (string or object) or an object with function and tested value as argument. Functions should return true for valid values or a string message if the result is invalid. For list of available validators check validators.js
• name - name of the input.
• mode - is a mode that defines when to validate input and how to update state depending on the validation results:
  • "blur-silent" - validate after input loses focus. If the input is valid then do not set state to valid.
  • "blur-eager" - validate after input loses focus. Always set state for valid and invalid inputs.
  • "form-silent" - validated manually after calling formValidate function. If the input is valid then do not set state to valid.
  • "form-eager" - validated manually after calling formValidate function. Always set state for valid and invalid inputs.
  • "immediate-eager" - validate on each input update. Always set state for valid and invalid inputs.
• messages - Each rule has default generic validation message for the invalid value. You can customize these messages for the input by adding them to the messages property. The key is a rule name and the value is the new message.
• callback - function that is called after each validation. The results of the valiation are in the callback argument. See below for the description of the validation results object.

Validation results

The validation result is an object with following propreties:

• status - object containg the results of validation and the current state of the input (for example touched, dirty etc). It is updated once initially and then after each value change.
• state - final validation state of input. This state is based on the current status and is updated only when conditions for the mode are fulfilled (for example input lost focus etc). By default it is empty string for initial state of input, "valid" for valid input and "invalid" for invalid input.
• messages - object containing validation messages.

Returns:

useValidation function returns single object:

{
    name: String,
    touch: Function,
    formValidate: Function,
    updateValue: Function,
    reset: Function,
}

Functions:

• updateValue - function that should be called when the value of the input changes
• touch - function that should be set as handler for inputs blur event.
• formValidate - function to manually validate and update validation state of the input.
• resetValidation - function that resets validation to default state.

Examples

Vue

Here is example of useValidation in the Vue. Check it online in Vue SFC Playground

<script setup>
import { ref, watch } from 'vue'
import useValidation from "./use-validation"

const msg = ref("")

let status = ref({})
let messages = ref({})
let state = ref("")

let rules = ["required", { minLength: 3 }, { maxLength: 5}]

let validation = useValidation(
  {
    rules,
    mode: "blur-silent",
  },
  (res) => {
    status.value = res.status
    messages.value = res.messages
    state.value = res.state
  }
)

watch(msg, (value) => {
  validation.updateValue(value)
}, { immediate: true })
</script>

<template>
  <h1>{{ msg }}</h1>
  <input 
    v-model="msg" 
    :class="{ valid: state === 'valid', invalid: state === 'invalid' }" 
    @blur="validation.touch()"
  />
  <div>
    <pre>Status: {{ status }}</pre>
  </div>
  <div>
    <pre>Messages: {{ messages }}</pre>
  </div>
  <div>
    <pre>State: {{ state }}</pre>
  </div>
</template>

<style>
input {
  outline: none;
}
.valid {
  border-color: green;
}
.invalid {
  border-color: red;
}
</style>

For more examples of components using this function check Litewind-vue or Litewind-alpine validation documentation.

Default messages

To change or add default messages for the validators import validationMessages object from validators.js file. A message can contain %d characters that are replaced with a rule value.

Default validators

To add new validators import globalValidators object from validators.js file.

---

Todo

• async validators