Features
- Includes
serialize
andvalidation
methods - 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
<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|button
will 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
rules
key 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
RegExp
or aFunction
- Must return
false
or an error message (String
) if invalid - Otherwise, must return
true
if 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
rules
and 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.preventDefault
the"submit"
event- Perform
validate
, then a) If all validation passed, call youroptions.onSubmit
function b) Otherwise, call youroptions.onError
function
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