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
Register Register
const validate = ; const myForm = document;const myRules = // RegExp rule email: /.+\@.+\..+/ // Function, with custom error messages { if !val return 'Required'; return vallength >= 8 || 'Must be at least 8 characters'; } // Function, comparing to other value { if !val return 'Required'; return val === datapassword || 'Must match your password'; }; myForm { ev; let errors = ; if myFormisValid return ; for let k in errors // TODO: Render errors manually // with {insert favorite UI lib here} console; console; console; };
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;let errors = formee; if !myFormisValid let i=0 item; for ; i < myFormelements; i++ item = myFormelementsi; console; itemisValid || console;
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.
;
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; formee; // Now available:// ---form;form;
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