Alpine plugin to easily validate forms
- Installation
- Usage
- Setup ( Rules - Messages )
- Reserved Keyword
- Show Error Messages
- Methods
- Events
- Available Validation Rules
<!-- 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>
npm i @fernandcf/x-validator
#or
yarn add@fernandcf/x-validator
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>
There are the following options:
- Rules - To add new validation rules. Supports
Promise. - Messages - To add and/or update error messages.
<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>
<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>
By default, some keyword are reserved for Validator internal use
- validator
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.
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>
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>
- init(fields:Array[HTMLElement]|null)
- validate(fields:Array[HTMLElement]|null)
- setLanguage(Locale:String)
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.
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.
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>
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.
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>
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>
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']" />
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']" />
For example:
<input x-rules="['string','between:5,9']" />
The field under validation can be empty:
The field under validation must not be empty.
The field under validation must not be empty.
The field under validation must contain only alpha-numeric characters.
The field under validation must contain only alphabetic characters.
Useful for validating single/multiple selectors, group of checkbox/radio inputs (with the same name).
The field under validation must be a number between the given range.
The field under validation must be a credit card number.
The field under validation must be a valid date.
The field under validation must be a valid date.
The field under validation must be an email.
The field under validation must end with one of the given values.
The field under validation must be equal to another field.
The field under validation must be a file.
The field under validation must be a is a hexadecimal color.
The field under validation must be included in the given list of values.
The field under validation must be an integer.
The field under validation must be less than or equal to a maximum value.
The field under validation must have a minimum value.
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']
The field under validation must be numeric.
The field under validation must match the given regular expression.
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.
The field under validation must be of type slug.
The field under validation must end with one of the given values.
The field under validation must be a string
The field under validation must be considered a strong password or not. Conditions that apply are: minLength: 8, minLowercase: 1, minUppercase: 1, minNumbers: 1, minSymbols: 1.
The field under validation must be a is a valid time.
The field under validation must be a valid URL.