Features
- Includes
serializeandvalidationmethods - Compatible with any UI library
- Fully tree-shakeable
Additionally, this module is delivered as:
- ES Module:
dist/formee.mjs - CommonJS:
dist/formee.js - UMD:
dist/formee.min.js
Install
$ npm install --save formee
Usage
:wave: View a full demo on CodePen
<form id="foo">
<h2>Register</h2>
<input type="email" name="email" />
<input type="password" name="password" />
<input type="password" name="confirm" />
<button>Register</button>
</form>
const { validate } = require('formee');
const myForm = document.querySelector('#foo');
const myRules = {
// RegExp rule
email: /.+\@.+\..+/,
// Function, with custom error messages
password(val) {
if (!val) return 'Required';
return val.length >= 8, 'Must be at least 8 characters';
},
// Function, comparing to other value
confirm(val, data) {
if (!val) return 'Required';
return val === data.password, 'Must match your password';
}
};
myForm.onsubmit = function (ev) {
ev.preventDefault();
let errors = validate(myForm, myRules);
if (myForm.isValid) return alert('Success!');
for (let k in errors) {
// TODO: Render errors manually
// with {insert favorite UI lib here}
console.log(`My rule & element's name: ${k}`);
console.log('> Error message:', errors[k], 'Required');
console.log('> My form element(s):', myForm.elements[k]);
}
};
API
formee.serialize(form)
Return: Object
Serializes a <form> into a data object.
Important: Any inputs that are unnamed, disabled, or are of
type=file, reset, submit, buttonwill be ignored.
form
Type: HTMLFormElement
The <form> element to evaluate.
formee.validate(form, rules, toCheck)
Return: Object
Validates a <form> according to its rules.
To check an individual input, you may pass its name as the toCheck value.
Important: The
ruleskey names must matchform.elements' names~!
Returns an Object of errors, whose keys are the failing rules keys (and the name=""s of failing elements) and whose values are your error messages (if provided) else false.
Additionally, the <form> and each of its elements will receive a new isValid property with a Boolean value.For example:
let myForm = document.querySelector('#myform');
let errors = formee.validate(myForm, { ... });
if (!myForm.isValid) {
let i=0, item;
for (; i < myForm.elements; i++) {
item = myForm.elements[i];
console.log(`${item.name} – Am I valid?`, item.isValid);
item.isValid, console.log('>> my error message:', errors[item.name]);
}
}
form
Type: HTMLFormElement
The <form> element to validate.
rules
Type: Object
An object of rules for your form's inputs.
Important: The key names must match a
<form>element'sname=""attribute!
The form values will be serialized before reaching your rule(s). (see serialize)
For example, a select[multiple] may present its value as undefined, a String, or an Array of Strings.
Each rule:
- May be a
RegExpor aFunction - Must return
falseor an error message (String) if invalid - Otherwise, must return
trueif valid
Your Function-type rules will receive the corresponding input's value and the entire data object.
validate(form, {
password(val, data) {
if (!val) return 'Required';
if (val.length < 8) return 'Must be at least 8 characters';
if (val !== data.confirmPassword) return 'Please confirm your password!';
return true; // all good homie
}
});
toCheck
Type: String
Default: undefined
If set, only the corresponding form element (with name={toCheck}) will be validated.
When unset (default), all form elements will be validated.
Important: The value must match a key within
rulesand aname=""attribute for one of<form>'s elements.
formee.bind(form, options)
Return: HTMLFormElement
Attaches serialize and validate methods to the <form> element.
Also registers a custom onsubmit handler that will:
event.preventDefaultthe"submit"event- Perform
validate, then
a) If all validation passed, call youroptions.onSubmitfunction
b) Otherwise, call youroptions.onErrorfunction
let myForm = document.querySelector('#myform');
formee.bind(myForm, {
rules: {
// ...
},
onSubmit(ev) {
// validation passed!
console.log(ev.errors); //=> {}
console.log(ev.target === myForm); //=> true
console.log(myForm.isValid, myForm.errors); //=> true {}
},
onError(ev) {
// validation failed!
console.log(ev.errors); //=> { ... }
console.log(ev.target === myForm); //=> true
console.log(myForm.isValid, myForm.errors); //=> false { ... }
}
});
// Now available:
// ---
form.serialize();
form.validate(/* specific item? */);
form
Type: HTMLFormElement
The <form> element to evaluate.
options.rules
Type: Object
Passed directly to validate – see rules.
options.onSubmit
Type: Function
Required: true
The callback to run when validation succeeds fails.
It receives the original event – however, a event.errors property is added, containing the output from validate.
options.onError
Type: Function
Required: true
The callback to run when validation fails.
It receives the original event – however, a event.errors property is added, containing the output from validate.
License
MIT © Luke Edwards