Avol-V/hyperform

Capture form validation back from the browser

Hyperform is a complete implementation of the HTML 5 form validation API in Javascript. It replaces the browser’s native methods (if it even implements them…) and enriches it with custom events and hooks.

Installation

The easiest way is installing via npm:

npm install hyperform

or if you use Bower:

bower install hyperform

or download the current version as ZIP archive.

Then embed dist/hyperform.min.js in your file:

<script src="path/to/hyperform/dist/hyperform.min.js"></script>

In old browsers you will need polyfills for the following features: WeakMap (IE 10 and lower), element.classList (IE 9 and lower), array.filter, array.every, Object.keys and Object.defineProperty (IE 8 and lower).

Usage

The library introduces the global variable hyperform. You can let Hyperform take over a single form:

hyperform(document.forms[0]);

or all forms, current and future ones:

hyperform(window);

Configure settings as second argument:

hyperform(window, {
    strict: false,         // default. En- or disable some high-level APIs

    revalidate: 'oninput', // default. Whether fields should be
                           // re-validated automatically. Valid values:
                           // `oninput`, `onsubmit`, and `never`.

    valid_event: true,     // default. Whether the non-standard `valid`
                           // event should be triggered
});

If you only need a certain feature, you can access it directly by name:

if (hyperform.willValidate(form.elements[0])) {
    var is_valid = hyperform.validityState(form.elements[0]).valid;
}

Examples

Check out the awesome examples!

Status

What parts of the HTML5 validation API are ready for prime time?

feature	status	comment
`willValidate`	🌕	✔️
`setCustomValidity(message)`	🌕	✔️
`validity.valueMissing`	🌕	✔️ (access via `hyperform.validityState`)
`validity.typeMismatch`	🌕	✔️ (access via `hyperform.validityState`)
`validity.patternMismatch`	🌕	✔️ (access via `hyperform.validityState`)
`validity.tooLong`	🌕	✔️ (access via `hyperform.validityState`)
`validity.tooShort`	🌕	✔️ (access via `hyperform.validityState`)
`validity.rangeUnderflow`	🌕	✔️ (access via `hyperform.validityState`)
`validity.rangeOverflow`	🌕	✔️ (access via `hyperform.validityState`)
`validity.stepMismatch`	🌕	✔️ (access via `hyperform.validityState`)
`validity.badInput`	🌕	✔️ (access via `hyperform.validityState`)
`validity.customError`	🌕	✔️ (access via `hyperform.validityState`)
`validity.valid`	🌕	✔️ (access via `hyperform.validityState`)
`checkValidity()`	🌕	✔️
`reportValidity()`	🌕	✔️
`validationMessage`	🌕	✔️
`valueAsDate`	🌕	✔️
`valueAsNumber`	🌕	✔️
`valueLow` / `valueHigh`	🌑	not started, yet
`stepUp(n)` / `stepDown(n)`	🌕	✔️
`accept` attribute	🌕	✔️ for `type=file` inputs. It’s useful to implement a check because there are browsers without support, that implement the File API.
support for `novalidate`	🌕	✔️

What parts of the high-level API are finished?

🌕 Trigger a validate event before validating a form:

form.addEventListener('validate', event => {
  /* cancel validation (will also cancel form submission!) */
  event.preventDefault();
});

🌑 Trigger an event before validating individual elements.
🌕 Trigger a valid event, when an input becomes valid, again:
```
input.addEventListener('valid', () => alert('Yay!'));
```
🌑 Allow functions to hook into the actual validations to accept or reject inputs.
🌓 Translate validation messages. We have some partial translations ready: https://github.com/hyperform/hyperform-l10n
🌕 Provide a registry for user defined validators, that are called automatically in the validity.customError step:
```
hyperform.register(element, function(element) {
  return result_of_convoluted_validation_routine();
});
```
🌕 Catch form submissions before the submit event to do our own validation (clicks on submit buttons and enter keys in text inputs in forms w/o submit buttons).
🌕 Add helper classes hf-valid and hf-invalid as well as proper aria-invalid to elements to become independent of :valid / :invalid pseudo-classes.
🌓 Allow specifying settings to customize the behavior of Hyperform (e. g., specifying a renderer for error messages).
🌕 Take single <input> elements out of validation by supporting a non-standard novalidate attribute and noValidate property for inputs:
```
var element = document.querySelector('input[name="foo"]');
element.noValidate = true;
// done. element won't be validated.
```
🌑 Add support for declarative custom validation messages:
```
<input data-validation-message="We need this field!">
```

🌑 Idea: Add a means of linking two <input>s together so they get validated synchronously:

hyperform.link(element1, element2);
element1.reportValidity();
// element2.reportValidity gets triggered automatically

Do you have a wish or an idea? File an issue and let us discuss it!

License

This library is released under the terms of the MIT license.

Avol-V / hyperform