Using Hyperform’s Validation Enhancements

React to Validation Results in CSS

All validated elements receive helper classes hf-valid and hf-invalid, respectively, as well as proper aria-invalid attributes. After the first validation they receive an additional class hf-validated. Additionally, Hyperform will try to keep the :valid and :invalid pseudo-classes functional (as long as browsers already support them).

So, to address an invalid <input> after a user has first tried to fill it, you can use

.hf-validated.hf-invalid {
  ...
}
/* or */
.hf-validated[aria-invalid="true"] {
  ...
}
/* or, if the browser supports it: */
.hf-validated:invalid {
  ...
}

Control Validation Flow with Events

When an element is validated and found invalid, an event invalid is triggered on this node. The event is cancellable, and if you decide to cancel it, any feedback to the user will be suppressed:

/* never render a warning to the user */
element.addEventListener('invalid', event => event.preventDefault());

When an input becomes valid again, (or is valid on initial validation) a valid event is triggered with the same cancelling behavior.

input.addEventListener('valid', () => alert('Yay! Congratulations.'));

A form element emits a validate event right before validating all its child elements and submitting the form. This event is cancellable, too, which will call off the validation and the subsequent submission.

form.addEventListener('validate', event => {
  /* cancel validation (will also cancel form submission!)
   * This is similar to a `novalidate` attribute on the form, but needs
   * manual form submission.
   */
  event.preventDefault();
});

Adapt Validation Messages

You can translate all validation messages and also set the language used. We have some partial translations ready, that are based on Firefox’s messages. The interface for this consists of two methods, hyperform.setLanguage() and hyperform.addTranslation().

hyperform.addTranslation("de", {
  TextTooLong: "Bitte kürzen Sie diesen Text auf maximal %l Zeichen (Sie verwenden derzeit %l Zeichen).",
  ValueMissing: "Bitte füllen Sie dieses Feld aus.",
  // ...
});

hyperform.setLanguage("de");

Hyperform supports declarative custom validation messages. Set a data-* attribute on the element, that you want to customize, and add the type of validation error that the message describes:

<input required data-value-missing="We need this field!">

If you want to adapt the messages of an element in code, you can do so with the hyperform.setMessage() method. It expects an element, the type of validator and the message in case the validation goes wrong:

hyperform.setMessage(element, 'valueMissing',
                     'Shugs! You need to fill in this form');

Define Custom Validators

Define your own validators per input element, that are called automatically in the validity.customError step:

hyperform.addValidator(element, function(element) {
  var valid = result_of_convoluted_validation_routine();
  // now is a good time to set error messages:
  element.setCustomValidity(valid? '' :
    'Please follow the on-screen instructions to receive your white rabbit.');
  return valid;
});

element.validity.customError? 'the script returned false' :
                              'the script returned true';

Exclude a Single <input> from Validation

You can take single <input> elements out of validation by setting a non-standard novalidate attribute in the HTML or setting the noValidate property in your JS code to true:

var element = document.querySelector('input[name="foo"]');
element.noValidate = true;
// done. element won't be validated.

Prevent Implicit Submits

An implicit submit occurs, when a user presses Enter in a single-line input field. Sometimes this behaviour is not wanted. You can disable it globally with a setting:

hyperform(window, {
  preventImplicitSubmit: true
});

Move Around or Manipulate the Error Message

Hyperform’s error messages are, unlike native messages, simple elements and can be manipulated with standard DOM methods. You can hook into that mechanism by providing your own rendering functions to the global hyperform object.

Example: Place the error message after the element’s parent:

/* @param warning HTMLElement the element containing the error message
 * @param element HTMLElement the form element, i.e., the <input>, that is
 *                            invalid
 */
hyperform.setRenderer('attachWarning', function(warning, element) {
  element.parentNode.appendChild(warning);
});

The renderer methods, that can be overwritten, are:

Next: Conformance & status – what parts of the HTML 5 validation API are supported, and what are the plans for additional features.