x-validator plugin alpine

Alpine plugin to easily validate forms

Installation

Via CDN

<!-- Alpine Plugin x-validator -->
<script  defer src="https://unpkg.com/@fernandcf/x-validator"></script>
<!-- Alpine Core -->
<script  defer  src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>

Via NPM

npm i @fernandcf/x-validator
#or
yarn add@fernandcf/x-validator

Usage

HTML:

<form x-validator>
    <input x-rules="['required','numeric','between:1,10']" />
</form>
<!-- OR -->
<form x-data="{
    rules:{
	  name: ['required','numeric','between:1,10']
	}
}" x-validator>
    <input x-rules="rules.name" />
</form>
<!-- OR -->
<form x-data="{
    rules:{
	  name: 'required|numeric|between:1,10'
	}
}" x-validator>
    <input x-rules="rules.name" />
</form>

Setup

There are the following options:

Rules - To add new validation rules. Supports Promise.
Messages - To add and/or update error messages.

Adding new rule

<form x-validator="{
    rules:{
	    exists({value:Array|String,args:Array,input:HTMLElement}){
			if(value){
				return true;	
			}
			return false;
	    }
    },
    messages: {
	    exists:'Error message from my new rule.'
	}
}">
    <input type="text" x-rules="['exists']" />
</form>

Adding new rule (Promise)

<form x-validator="{
    rules:{
	    exists({value:Array|String,args:Array,input:HTMLElement}){
			return new Promise((resolve) => {
				setTimeout(() => {
					resolve(value ? true : false)
				}, 2000);
			});
	    }
    },
    messages: {
	    exists:'Error message from my new rule.'
	}
}">
    <input type="text" x-rules="['exists']" />
</form>

Reserved Keyword

By default, some keyword are reserved for Validator internal use

validator

Show Error Messages

Error messages from the start/server.

To show start/server errors. You must do the following:

<form x-data="{
	 validator:{
		error:{
			description: 'The username has already been taken.'
		}
	 }   
 }" x-validator>
	<input type="text" name="description" x-rules="['required']"/>
	<!-- error message for field 'description' -->
	<div x-text="validator.error.description"></div>
</form>

This is useful if you are using a backend like Laravel and need to display error messages.

Get the error message

To get the error message for a specific field, you must use the validator keyword inside error and lastly the field name. validator.error.{field_name}. It will return an empty string if validation has passed, otherwise it will return an error message.

For example

<form x-validator>
	<input type="text" name="description" x-rules="['required']"/>
	<!-- error message for field 'description' -->
	<div x-text="validator.error.description"></div>
</form>

Get all error messages

To get all error messages for a specific field, you must use the validator keyword inside errors and lastly the field name. validator.errors.{field_name}. It will return an object of error messages.

For example

<form x-validator>
	<input type="text" name="description" x-rules="['required']"/>
	<!-- error messages for field 'description' --> 
	<template  x-for="(item, index) in  validator.errors.description" :key="index">
		<div>
			<p>Rule name: <span x-text="index"></span></p>
			<p>Message:<span x-text="item"></span></p>
		</div>
	</template>
</form>

Methods

init(fields:Array[HTMLElement]|null)
validate(fields:Array[HTMLElement]|null)
setLanguage(Locale:String)

`validator.init(fields:Array[HTMLElement]|null)`

Initializes the validator on the field or fields. Receives an optional parameter fields that is an array of HTMLElements to initialize. It is recommended that you call it inside magic $nextTick.

`validator.validate(fields:Array[HTMLElement]|null)`

It will validate the field or fields. Receives an optional parameter fields that is an array of HTMLElements to validate. Returns a true value to indicate that the validation was successful and a false value otherwise.

`validator.setLanguage(Locale:String)`

Set the language of the error messages. Default 'en'. Available languages:

English (en)
Spanish (es)

For example:

<form x-validator x-init="validator.setLanguage('es')">
	...	
</form>

Handling Events

There are four types of events that can be handled with hooks:

validator.success
validator.failed
field.invalid
field.valid

For example in Alpinejs:

<input x-on:field-invalid.dot="console.log($event.detail.errors)" x-rules="['required','min:5']" />

Since dots within the event name are reserved by Alpine you need to write them with dashes and add the .dot modifier.

`validator.success`

This event will occur when the validation ends with no errors:

<form x-validator x-on:validator-success.dot="alert('success')">
    <input x-rules="['required','min:5']" />
</form>

`validator.failed`

This event will occur when the validation ends while there are some errors in the form:

<form x-validator x-on:validator-failed.dot="alert('failed')">
    <input x-rules="['required','min:5']" />
</form>

`field.valid`

This event is fired when a particular field has no validation errors:

<input x-on:field-valid.dot="alert('valid')" x-rules="['required','min:5']" />

`field.invalid`

When a particular field has errors, you can handle the errors with this event:

<input x-on:field-invalid.dot="alert('invalid')" x-rules="['required','min:5']" />

Available Validation Rules:

For example:

<input x-rules="['string','between:5,9']" />

optional

The field under validation can be empty:

required

The field under validation must not be empty.

accepted

The field under validation must not be empty.

alphaNum

The field under validation must contain only alpha-numeric characters.

alpha

The field under validation must contain only alphabetic characters.

array

Useful for validating single/multiple selectors, group of checkbox/radio inputs (with the same name).

between:min,max

The field under validation must be a number between the given range.

creditCard

The field under validation must be a credit card number.

date

The field under validation must be a valid date.

digits:value

The field under validation must be a valid date.

email

The field under validation must be an email.

endsWith:foo,bar...

The field under validation must end with one of the given values.

equalTo:fieldName

The field under validation must be equal to another field.

file

The field under validation must be a file.

hexColor

The field under validation must be a is a hexadecimal color.

in:foo,bar...

The field under validation must be included in the given list of values.

integer

The field under validation must be an integer.

max:value

The field under validation must be less than or equal to a maximum value.

min:value

The field under validation must have a minimum value.

mobilePhone:locale1,locale2...

The field under validation must have a a mobile phone number. Available locales: ['am-Am', 'ar-AE', 'ar-BH', 'ar-DZ', 'ar-EG', 'ar-EH', 'ar-IQ', 'ar-JO', 'ar-KW', 'ar-PS', 'ar-SA', 'ar-SD', 'ar-SY', 'ar-TN', 'ar-YE', 'az-AZ', 'az-LB', 'az-LY', 'be-BY', 'bg-BG', 'bn-BD', 'bs-BA', 'ca-AD', 'cs-CZ', 'da-DK', 'de-AT', 'de-CH', 'de-DE', 'de-LU', 'dv-MV', 'dz-BT', 'el-CY', 'el-GR', 'en-AG', 'en-AI', 'en-AU', 'en-BM', 'en-BS', 'en-BW', 'en-CA', 'en-GB', 'en-GG', 'en-GH', 'en-GY', 'en-HK', 'en-IE', 'en-IN', 'en-JM', 'en-KE', 'en-KI', 'en-KN', 'en-LS', 'en-MO', 'en-MT', 'en-MU', 'en-NG', 'en-NZ', 'en-PG', 'en-PH', 'en-PK', 'en-RW', 'en-SG', 'en-SL', 'en-SS', 'en-TZ', 'en-UG', 'en-US', 'en-ZA', 'en-ZM', 'en-ZW', 'es-AR', 'es-BO', 'es-CL', 'es-CO', 'es-CR', 'es-CU', 'es-DO', 'es-EC', 'es-ES', 'es-HN', 'es-MX', 'es-NI', 'es-PA', 'es-PE', 'es-PY', 'es-SV', 'es-UY', 'es-VE', 'et-EE', 'fa-AF', 'fa-IR', 'fi-FI', 'fj-FJ', 'fo-FO', 'fr-BE', 'fr-BF', 'fr-BJ', 'fr-CD', 'fr-CF', 'fr-FR', 'fr-GF', 'fr-GP', 'fr-MQ', 'fr-PF', 'fr-RE', 'fr-WF', 'ga-IE', 'he-IL', 'hu-HU', 'id-ID', 'ir-IR', 'it-IT', 'it-SM', 'ja-JP', 'ka-GE', 'kk-KZ', 'kl-GL', 'ko-KR', 'ky-KG', 'lt-LT', 'mg-MG', 'mn-MN', 'ms-MY', 'my-MM', 'mz-MZ', 'nb-NO', 'ne-NP', 'nl-AW', 'nl-BE', 'nl-NL', 'nn-NO', 'pl-PL', 'pt-AO', 'pt-BR', 'pt-PT', 'ro-Md', 'ro-RO', 'ru-RU', 'si-LK', 'sk-SK', 'sl-SI', 'so-SO', 'sq-AL', 'sr-RS', 'sv-SE', 'tg-TJ', 'th-TH', 'tk-TM', 'tr-TR', 'uk-UA', 'uz-UZ', 'vi-VN', 'zh-CN', 'zh-HK', 'zh-MO', 'zh-TW']

numeric

The field under validation must be numeric.

regex:pattern

The field under validation must match the given regular expression.

size:value

The field under validation must have a size matching the given value. For string data, value corresponds to the number of characters. For numeric data, value corresponds to a given integer value.

slug

The field under validation must be of type slug.

startsWith:foo,bar...