ES6 form field validation library
vally is a simple ES6, zero-dependency form field validation library, that helps
to determine if -values pass certain tests.
The library just provides a set of useful helper functions. Most of the DOM-manipulation
and validation handling still lies in the hands of the user to ensure as much
flexibility as possible.
ANNOUNCEMENT:
>At this point I would currently advise against the use of vally. I am working heavily on a rewrite, which should be out
in a couple of days. This v2.0.0 will contain a lot of breaking changes, but will make this library
way more flexible. If the current state of _vally_ is exactly what you are looking for, feel free to continue
using it (or just fork it). However I will not continue to develop v1.x.x.
* Installation
* API
* Docs
* FAQ
* How can i specify a field as _required_?
* What happens to inputs that are not displayed?
* How can I bind vally to certain events?
* Why does vally ship so few validator functions?
* How can I use a validator function with multiple arguments?
* Example:
* Examples
* Simple Example
* Complex example
* index.html
* config.js
* index.js
``shell`
npm i --save vally
You can either use the build from inside the dist/ directory and include
it via
`
or
`js
import { isString } from 'vally'
isString(1) // => false
`
Configuration and API details can be found here:
> Just use the regular _required_-Attribute
> on your . This will ensure that vally actually validates the element if the input is empty.isNoneEmptyString()
> You still have to specify validator functions to provide the actual validation functionality.
> I.e. if the field should not be empty use .
> Inputs that are not displayed (i.e. if display: none, type="hidden" or hidden="" is set), are
> simply ignored by the validation.
> vally leaves most of the DOM-manipulation to the user. For simple bindings (i.e. for 'keyup'-events)
> however you can use initWithBindings(). For detailed explaination have a look at our examples below.
> Because validators in vally are simple functions it is very
> easy to either write them yourself our just use a library like
> validator.js.
> Providing only a basic set of functions keeps the footprint of the library small.
> If you need multiple arguments (like some validator.js. functions need additional configuration) you can simply
> partially apply the function and return a validator function.
#### Example:
`js`
const isLessThan = (num: number) => (val: any):boolean => { / actual implementation / }
`html
`
The following example shows how vally can be used to use the same configuration
to manually validate on the submit event and also bind it tokeyup
fire on triggered by individual inputs.
#### index.html
Lets use almost the same markup as before... . This time we ship vally bundled together
with our other js resources in main.bundle.js, though. We also want to insertdisplay
custom error messages into the DOM depending on which validator for a field failed.
There are a lot of ways to achieve this. In this case we simply put hidden divs
below each input and toggle their on validation.
Of course we also insert our custom messages into them.
`html
`
#### config.js
We separate our configuraion from the actual validation logic, to make everything
a bit more maintainable.
`js
// config.js
import {
createConfig,
isEmail,
isNoneEmptyString,
isNumberString
} from 'vally'
// Custom validator
// Because we need another parameter for our function to specify the threshold,
// we simply curry our validator function. The actual invokation to get a
// real validator function would look like this: isLessThan(10)
const isLessThan = (num: number) => (val: any): boolean => {
if (isNumberString(val)) return false
return parseInt(val) < num
}
// Because we only want to fetch DOM-elements via document.querySelector
// we can use the createConfig helper function to create a valid configuration.
// Therefore we specify our specs with selectors, which in turn are used to
// fetch the actual DOM nodes
const specs = [
{
selector: '#mail',
validators: [
{
fn: isNoneEmptyString,
errorSelector: 'mail-error',
msg: 'Please enter a value.'
},
{
fn: isEmail,
errorSelector: 'mail-error',
msg: 'Please enter a valid email address.'
}
]
},
{
selector: '#number',
validators: [{
fn: isNumberString,
errorSelector: 'number-error',
msg: 'Please enter a number.'
}]
},
{
selector: '#custom',
validators: [
{
fn: isNoneEmptyString,
errorSelector: 'custom-error',
msg: 'Please enter a value.'
},
{
fn: isLessThan(10),
errorSelector: 'custom-error',
msg: 'Please enter a number smaller than ten.'
}
]
}
]
export config = createConfig(specs)
`
#### index.js
Here we will define our actual validation logic.
`js
// index.js
import {
initWithBindings,
validate
} from 'vally'
import { config } from './config'
// Our callback will recieve a result object and act on its field validations
const callback = (e: Event, { validations }: { validations: Valiations }): void => {
validations.forEach(v => {
const msgNode = document.getElementById(v.validator.errorSelector)
if (v.isValid) {
v.node.classList.remove('error')
// Hide msg
if (msgNode ) msgNode.classList.add('hidden')
} else {
v.node.classList.add('error')
// Show error msg
if (msgNode) {
msgNode.classList.remove('hidden')
msgNode.innerHTML = v.validator.msg
}
}
})
}
// Create a pre-configured partially applied validate function that we can use
// on our submit button. We technically don't need to do this
// as we only need to validate on submit. But in a real-world application you might
// need to re-use your validate function
// and this makes it easier.
const validateForm = () => validate(config)
const init = () => {
// Bind our callback to the keyup event on each individual field
initWithBindings(config, 'keyup', callback, 100)
// Bind our validate function to our submit button
const btnSubmit = document.getElementById('submit')
if (!btnSubmit) return
btnSubmit.addEventListener('click', (e) => {
e.preventDefault()
const result = validateForm()
if (result.isValid) {
// logic to send our form
} else {
// React to our validation result
callback(e, result)
}
})
}
init()
``