Documentation

Installation

            
npm install valform
            
        

Alternatively, you can download a file here and include it into your page:

            
<script src="valform.min.js"></script>
            
        

Usage

            
import valForm from "valform";
valForm.init()

// then place "data-val-rules" attribute to your inputs with at least one rule defined, see bellow
            
        

You would want to initialize valForm on the page where you have your form element. Form needs to be in the DOM so if you are using frameworks like react or vue etc. you need to place valForm.init method to respective lifecyle methods (e.g. in react to "componentDidMount()" or in vue to "mounted()").

Configuration

HTML "data" attributes

data-val-rules

valForm will work out of the box. The only requirement is to place "data-val-rules" attribute to your inputs with at least one rule defined, e.g.:

          
<input type="text" name="address" data-val-rules="required" />
          
        

If you need to apply more than one rule separate the rules with a pipe: |

          
<input type="text" name="address" data-val-rules="required|max_length[32]" />
          
        

data-val-display

If not specified otherwise then "name" attribute will be used for validation message. Normally though you would want to specify this in most cases:

            
<input
  type="text"
  name="dob"
  data-val-rules="required"
  data-val-dispaly="Date of birth"
/>
            
        

In case of error this would produce error message: The Date of birth field is required.

data-val-allow-empty

Sometimes the field is optional (it's not required) but if it contains value you might want to validate it:

          
<input
  type="tel"
  name="phone"
  id="phone"
  data-val-rules="numeric|uk_phonenumber"
  data-val-allow-empty="true"
/>
          
        

In this case the field can be empty and would validate as valid but as soon as there's a value it will be validated against the specified rules.

data-val-with

There might be cases when you need to validate two fields against each other, e.g. date of birth field against insurance policy inception date. Then you just need to provide "name" attribute of that field:

          
<input
  type="text"
  name="dob"
  data-val-rules="required|years_between[17]"
  data-val-with="inception"
/>

<input
  type="text"
  name="inception"
  data-val-rules="required|years_between[17]"
  data-val-with="dob"
/>
          
        

Config object

You can configure valForm with a simple object:

          
const valConfig = {
    formId: "my-form",
    validationErrorClass: "not-valid",
    validationValidClass: "valid",
    errorElement: "div",
    appendAfter: "input-form",
    dateFormat: "YYYY-mm-dd"
};

valForm.init(valConfig);
          
        

formId: this might be useful if you need to handle more than one form on a page, e.g. you have main form with several fields and then small one for newsletter subscription. In that case you can specify which form shall be handled when submit button is pressed. NB: In this case uyou might want to handle validation submission programmatically...

validationErrorClass: by default it's "val--error",

validationValidClass: by default it's "val--valid",

errorElement: by default it's "small",

appendAfter: class of an element after which should be errorElement appended. By default error element will come staright after input field,

dateFormat: specify which date format you are using, by default it's 'mm/dd/YYYY', available ones are:

          
"dd/mm/YYYY", "YYYY-mm-dd", "mm/dd/YYYY", "isoDateTime";
          
        

Custom validation methods

Adding custom methods is straightforward:

          
valForm.addValMethod("greater_than_6", field => {
  return field.value > 6;
});
          
        

You just need to return true or false at the end. Also, "field" object will be automatically passed to the method, might look like this:

          
{
    allowEmpty: false,
    display: "Date of birth",
    error: null,
    name: "dob",
    rules: ["required"],
    type: "text",
    valid: false,
    value: '05/05/1980',
    visited: false,
    with: null
}
          
        

Most of the time you will only need to work with "value" property.

NB: You can add these methods even inside your (react/vue...) components and use for validation data properties defined in there.

Naturally, you will need to add then your custom validation message:

          
valForm.addValMessage("greater_than_6", "The number must be greater than 6.");
          
        

Use "%s" placeholder to specify field name: 'The %s field must be greater than 6.'

This will transform to (let's assume "Number of months" field): 'The Number of months field must be greater than 6.'

NB: If used to add new methods and messages then "addValMethod" and "addValMessage" must be used together for the validation to work properly. Alternatively, you can use it to overwrite any method or to adjust validation message to your liking.

Messages with dynamic additions

Because some methods can have optional parameters there are some messages that may or may not have additions to them, e.g.:

Method "greater_than" can accept number parameter which can start (but doesn't have to) with equals sign: greater_that[20] or greater_than[=20]. The latter will include parameter to comparison and add to error message this addition: 'It can be equal to it.'

So the whole message in case or error would be: The %s field must contain a number greater than %s. It can be equal to it.

There are two possible additions:

• - equals_addition: 'It can be equal to it.' => when dealing with numbers
• - date_addition: 'It can be today.' => when dealing with dates

If you need to change this messages you can also use addValMessage method provided to you:

          
valForm.addValMessage("equals_addition", "Can be the same"); // changing
valForm.addValMessage("equals_addition", ""); // removing
          
        

Validation methods with optional dynamic additions:

• - greater_than (equals_addition)
• - less_than (equals_addition)
• - date_greater_than (equals_addition)
• - date_less_than (equals_addition)
• - date_in_past (date_addition)
• - date_in_future (date_addition)

Asynchronous validation

In this case the only thing you need to do is to provide an asynchronous validation method that will return a promise, it can look something like this:

          
valForm.addValMethod("async_validation", async (field) => {
  return new Promise((resolve, reject) => {
    try {
      const data = await fetch(`http://example.com/validate?value=${field.value}`);
      const result = await data.json();
      resolve(result.validity);
    } catch (error) {
      console.error(error);
      reject(false);
    }
  });
});
          
        

Programmatic validation

Validating the whole form

If you want to be in a control of the whole validation process you can use "validateForm" method. Note that this is asynchronous process so it needs to be handled asynchronously, e.g.:

          
async function handleFormSubmission(event) {
    // prevent form from submitting
    event.preventDefault();
    const formEl = document.getElementById('my_form');

    const check = await valForm.validateForm();

    if(check) {
        formEl.submit();
    } else {
        console.log('Form is not valid');
        // your own logic
    }
}
          
        

It will return true if the whole form is valid or false if not.

If you pass optional boolean parameter (true) it will return an object containing every field with all the attributes as shown above. So you can process it any way you like.

Validating form partially

There's also a method to partially validate only few fields:

          
const check = await valForm.partialValidation(["name", "dob"], true);
          
        

First parameter is required and can be either string (if it's one field) or array (more fields). This expects name attributes of the fields. Again, optional second parameter controls if the return value is boolean or the object with passed fields' information.

Handling validation of hidden inputs

There might be cases when you build your own custom inputs using hidden inputs which should be validated. As the input and change events do not apply to hidden input types you can control this with a helper method:

          
const check = await valForm.validateHidden(name, value);
          
        

This method accepts two parameters - name attribute and the value of an input. For now this method does not accept third parameter to return the the object with field information. (in progress)

NB: Using "data-val-rules" on hidden inputs and not handling validation with this method will cause form validation to fail.

Hooks

Validation of any field will dispatch custom "validated" event which you can use to hook up to. It can look like this:

          
let elem = document.getElementsByName("email")[0];
elem.addEventListener("validated", event => {
  console.log("Email has been validated");
  console.log(event.detail);
  // any callback you need
});
          
        

Supported inputs

1. text
2. number
3. tel
4. textarea
5. select
6. radio
7. checkbox