README.md

    Facile Validator

    npm version npm downloads Github Actions CI License

    Laravel-inspired validation for HTML forms, built for simplicity of use: 😋

    Facile (French word for "easy", pronounced fa·sil) is an HTML form validator that is inspired by Laravel's validation style and is designed for simplicity of use.

    DEMO

    Table of Contents

    Note: This package does not include any polyfills. If you want to use in old environments, add this package to your project's config transpiling list.


    Installation

    npm i @upjs/facile-validator
    
    # or
    yarn add @upjs/facile-validator

    Usage

    HTML:

    <form>
      <input data-rules="bail|required|number|between:1,10" />
    </form>

    The rules for each field are separated with a pipe character (vertical line) |. In this example, we've assigned 4 rules for that input:

    • bail
    • required
    • number
    • between (with two arguments: 1 and 10)

    JavaScript:

    import { Validator, enLang as en } from '@upjs/facile-validator';
    
    // Select the container element that contains the fields
    const form = document.querySelector('form');
    
    // Create an instance of Validator for the container element
    const v = new Validator(form, {
      lang: en,
    });
    
    form.addEventListener('submit', (e) => {
      e.preventDefault();
      
      // Call validate method to start validation
      v.validate();
    });
    
    
    // Handle error-free validation
    v.on('validation:success', () => {
      alert('Nice! The form was validated without any errors');
    });
    
    // Handle failed validation
    v.on('validation:failed', () => {
      alert('Oops! There are some errors in the form.');
    });

    Now every input with data-rules attribute in the form will be validated.


    Handling Events

    When the validation starts, ends, succeeds or fails, there are easy ways to handle these events. We do this with the help of the Hooks. A hook is simply a function that you define to be executed when a particular event occurs.

    There are five type of events that can be handled with the hooks:

    To attach a hook to these events, use on method:

    v.on(event_name, () => {
      // This function will be executed when the respective event occurs.
    });

    You can also attach those hooks in the config object:

    const v = new Validator(form, {
      // ...
      on: {
        'validation:success': () => {
          alert('Success! Form validated with no errors');
        },
      },
    });

    validation:start

    As you might have guessed, this event will occur when the validation starts:

    v.on('validation:start', (form) => {
      // This function will be executed when the validation starts
    });

    validation:end

    This event will occur when the validation ends, no matter if it was successful or not:

    v.on('validation:end', (form, isSuccessful) => {
      // This function will be executed when the validation ends
    });

    validation:success

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

    v.on('validation:success', (form) => {
      // Do something after successful validation e.g. send the form-data to the server
    });

    validation:failed

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

    v.on('validation:failed', (form) => {
      // Notify the user to fix the form
    });

    field:error

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

    v.on('field:error', (form, field, errors) => {
      errors.forEach(error => {
        console.log(error.args);
        console.log(error.message);
        console.log(error.rule);
        console.log(error.element);
      });
    });

    This is a good place to display errors in your own format. By default, the validator automatically shows error messages below each input. However, you can disable this feature by setting renderErrors option to false in the config object:

    const v = new Validator(form, {
      renderErrors: false,
    });

    Available Validation Rules:


    accepted

    The field under validation (checkbox, radio) must be checked:

    <input data-rules="accepted" />

    alpha

    The field under validation must contain only alphabetic characters:

    <input data-rules="alpha" />

    Some valid inputs:

    • Hello
    • français
    • سلام

    alpha-num

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

    <input data-rules="alpha-num" />

    Some valid inputs:

    • abc123
    • abc
    • 123

    alpha-num-dash

    The field under validation must contain only alpha-numeric characters, dashes, and underscores:

    <input data-rules="alpha-num-dash" />

    Some valid inputs

    • abc-123
    • abc_123
    • abc123
    • abc
    • 123

    bail

    Stops running validation rules for the field after the first validation failure:

    <input data-rules="bail|required|number|between:1,10" />

    required rule will be processed and if it fails, other rules will not be processed.


    between

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

    <input data-rules="between:1,10" />

    The numbers lower than 1 and higher than 10 are not accepted.


    digits

    The field under validation must be a number with the given length:

    <input data-rules="digits:10" />

    Only a number with the length of 10 is accepted (e.g. 1234567890)


    email

    The field under validation must be an email:

    <input data-rules="email" />

    ends-with

    The field under validation must end with the given substring:

    <input data-rules="ends-with:ies" />

    Only the words that end with ies (technologies, parties, allies, ...) are accepted.


    int

    The field under validation must be an integer (positive or negative):

    <input data-rules="int" />

    You can also use integer rule.


    max

    This rule is used for multiple purposes.

    In the combination with the number rule, the field under validation must be a number less than or equal to the given number:

    <input data-rules="number|max:50" />

    Only a number less than or equal to 50 are accepted.

    If max is used without number rule, the field under validation is considered as a string and then the field under validation must be a string with a maximum length of the given number:

    <input data-rules="max:5" />

    Only strings with the length of 5 or less are accepted.


    min

    This rule is used for multiple purposes.

    In the combination with the number rule, the field under validation must be a number greater than or equal to the given number:

    <input data-rules="number|min:50" />

    Only a number greater than or equal to 50 will be accepted.

    If min rule is used without number rule, the field under validation is considered as a string and then The field under validation must be a string with a minimum length of the given number.

    <input data-rules="min:5" />

    Only strings with the length of 5 or higher will be accepted.


    nullable

    The field under validation can be empty:

    <input data-rules="nullable|min:5" />

    min rule will not be processed unless the field is filled. Note that the rules order is important. In this example, if nullable rule comes after min rule, the validator first processes min rule and then nullable rule.


    num-dash

    The field under validation must contain only numeric characters, dashes, and underscores:

    <input data-rules="num-dash" />

    1000, 123-456, 123_456 are some valid inputs for this rule.


    number

    The field under validation must be a number:

    <input data-rules="number" />

    required

    The field under validation must not be empty:

    <input data-rules="required" />

    size

    This rule is used for multiple purposes.

    In the combination with the number rule, the field under validation must be a number equal to the given number:

    <input data-rules="number|size:1000" />

    Only 1000 is accepted.

    If used without number rule, the field under validation is considered as a string and then the field under validation must be a string with the exact length of the given argument:

    <input data-rules="size:5" />

    Only the strings with the length of 5 are accepted.


    starts-with

    The field under validation must start with the given substring:

    <input data-rules="starts-with:app" />

    Only the words that start with app (apple, application, append, ...) are accepted.


    in

    The field under validation must be in the list of the given arguments:

    <input data-rules="in:red,green,blue" />

    Only red or green or blue are valid inputs.

    in rule can also be used with a <select multiple> element. In this case, in rule should be used with array rule:

    <select data-rules="array|in:1,3" name="names[]" multiple>
      <option value="1">1</option>
      <option value="2">2</option>
      <option value="3">3</option>
    </select>

    Only 1, 3 or both are accepted.



    Localization

    When instantiating the Validator class, importing a language is mandatory. This allows you to keep the bundle size as minimal as possible by including only the desired language:

    import { Validator, enLang as en } from '@upjs/facile-validator';
    
    const form = document.querySelector('form');
    const v = new Validator(form, {
      lang: en,
    });

    Facile Validator currently supports these languages by default:

    • English (import with enLang)
    • Persian (import with faLang)

    We welcome any contributions for other languages. The languages are located in this path. Just copy any file, translate it into your own language and then make a PR.


    Using your own language

    Use createLang function to define your own error messages:

    import { Validator, enLang as en, createLang } from '@upjs/facile-validator';
    
    const myLang = createLang({
      required: 'Please fill out this field',
      accepted: 'Please accept this field',
    });
    
    const v = new Validator(form, {
      lang: myLang,
    });

    Note that in this case you should define a message for each existing rule. Although, to override only certain messages, pass the original language object:

    import { Validator, enLang as en, createLang } from '@upjs/facile-validator';
    
    const myLang = createLang({
      ...en,
      required: 'Please fill out this field',
      accepted: 'Please accept this field',
    });

    License

    MIT

    项目简介

    Laravel-inspired validation for HTML forms, built for simplicity of use 🍬

    🚀 Github 镜像仓库 🚀

    源项目地址

    https://github.com/upjs/facile-validator

    发行版本 3

    v1.0.0

    全部发行版

    贡献者 6

    R Renovate Bot @Renovate Bot
    A Ali Nazari @Ali Nazari
    M Mohammad Saleh Fadaei @Mohammad Saleh Fadaei
    M Mohammad Saleh Fadaei @Mohammad Saleh Fadaei

    开发语言

    • TypeScript 92.1 %
    • HTML 7.8 %
    • Shell 0.1 %