formurai v0.3.7

Formurai

Validating forms has never been so easy. A few lines of code and your form is validated

import Formurai from 'formurai';

const rules = {'login-email': ['email']};

const errors = {
  'login-email': {WRONG_EMAIL: 'Email must be valid'}
};

const form = document.querySelector('#login');

const validator = new Formurai(form);
validator.init(rules, errors);

Table of Contents

• Features
• Setup
• Usage
• Options
• Methods
• Rules
• Examples
• Roadmap

Features

• 📦 Just 4.4 KB gzipped
• 👩🏻‍💻 Rules are declarative
• ✨ Any number of rules for each field
• ❌ Flexible error handling and their display
• 🗜 Has possibility to validate multi-step forms
• ⚙️ Configurable check queue
• 📜 Easy to create and reuse your own rules
• ⚡️ Based on LIVR(Language Independent Validation Rules)
• 👍 Don't need Jquery.

Setup

Install the package

npm install formurai

yarn add formurai

JS

import Formurai from 'formurai';

// define rules
const rules = {
  'login-email': ['required', 'email'],
};

// define errors for user, its optional
const errors = {
  'login-email': {
    REQUIRED: 'Email required',
    WRONG_EMAIL: 'Email must be valid',
  }
};

const form = document.querySelector('#login');
const validator = new Formurai(form);
validator.init(rules, errors);

ALL RULES AND ERROR CODES

As a key for the rules, you need to pass the name of the field to be validated. The field name must be unique within this form

HTML

<form id="login">
  
  <section class="formurai-container">
    <input name="login-email" type="email">
    <span class="formurai-message"></span>
  </section>

  <button type="submit">Submit</button>
  
</form>

If you need to show errors in the interface, add the formurai-container class to the element to which you want to assign the error or success class (optional step).

To display an error, inside the container, define an element with the class formurai-message, errors that you pass during initialization will be displayed here (optional step).

CSS

.formurai-message {
  display: none;
}

.formurai-error .formurai-message {
  display: none;
}

.formurai-error input {
  border: 1px solid red;
}

.formurai-success input {
  border: 1px solid green;
}

When the form is submitted, or the checkForm method is called, the wrapper(.formurai-container) is assigned an error or success class.

Usage

Basic usage, you need to pass the form and rules.

/**
 * @param {HTMLFormElement} form 
 * @param {Object} options 
 * @type {Formurai}
 */
const validator = new Formurai(form, options);
validator.init(rules);

Options

Methods

const validator = new Formurai(form);

init(rules, messages?, initialState?)

Initializes validator, error object and initialState, optional parameters, initialState work only in multi-step forms.

validator.init(rules)

destroy()

Destroys the validator and all associated event listeners (custom to). Also delete all added rules.

validator.destroy()

changeState(state)

Change current state in multi step form. The value must be a key with the rules for the current step

const rules = {
  'step-1': {...stepRules},
  'step-2': {...stepRules},
}

validator.changeState('step-2')

checkForm()

Manually run a form validation like

const nextStepButton = document.querySelector('.next-step');

nextStepButton.addEventListener('click', () => {
  validator.checkForm();
  
  if (validator.isFormValid) {
    // go to the next step
  }
})

addRule(rule)

Accepts object or array of objects with custom rules. Rules need to be added after initialization

const rules = {
  password: 'strong_password'
}

const customRule = {
  name: 'strong_password',
  rules: [{length_between: [15, 20]}],
  error: 'WEAK_PASSWORD'
}

validator.init(rules)
validator.addRule(customRule)

formData

Returns an object with data from the form

validator.formData // {name: 'Leonardo', email: 'leonardo@gmail.com'}

errors

Returns an object with error codes

validator.errors // {name: "REQUIRED", email: "WRONG_EMAIL"}

errorList

Returns human-readable error list. For example, if you need to show all errors somewhere in one place

validator.errorList // {name: "First name required", email: "Email must be valid"}

isFormValid

Returns the current state of form validation

validator.isFormValid // true | false

Events

validator.on(evt, callback);

formValid

This listener is triggered when the form is fully valid, useful if you need to send it in ajax, without reloading the page.

const sendForm = async () => {
  await fetch('https://example.com', {
    method: 'POST',
    body: validator.formData // contain all form data
  })
  console.log('Your form has been submitted successfully')
}

validator.on('formValid', sendForm);

See full example

formInvalid

This listener is triggered when the form is invalid, regardless of whether the click submit, or you manually invoke checkForm() method

const scrollToFirstError = () => {
  const errorEl = document.querySelector('.formurai-error');
  errorEl.scrollIntoView();
}

validator.on('formInvalid', scrollToFirstError);

changeState

This listener works only in multi-step forms and triggered when you use changeState() method

const logCurrentState = (evt) => {
  console.log(evt.detail.state) // console current step
}

validator.on('changeState', scrollToFirstError);

Rules

ALL RULES

All rules are based on LIVR (Language Independent Validation Rules). So all the rules that you find here you can use in this validator

Most common rules

Examples

• Registration form
• Multi step form
• Ajax form

Roadmap

• Add a getter with a list of error messages
• Add a showError method to show errors from backend
• Implement 'formInvalid' and 'changeState' events
• Treeshaking
• Integration with React
• Сover the validator with e2e tests