Form Validation

Validator is a form validation module. It only reads form fields, runs validation rules, writes failed states, and creates error hint nodes.

Example

Import

JavaScript
import { createValidator } from 'vanilla-jui';

Basic Usage

Use createValidator to create a Validator instance:

JavaScript
const validator = createValidator(form, {  rules: {    email: { required: true, email: true },    password: { required: true, minLength: 6 },    plan: { selected: true },  },  messages: {    email: { required: 'Email required', email: 'Invalid email' },    password: { minLength: 'Password too short' },    plan: { selected: 'Plan required' },  },  vanilla: false,  onSubmit: (validator) => {    console.log(validator.runtime.valid);  },});

Parameters

createValidator(element, props, bindEvents)

element

The first parameter element must be resolvable to an HTMLFormElement; otherwise, an error is thrown.

props

The second parameter props is a validation configuration object, including validation rules, error messages, and more.

• vanilla: false is the default behavior. It sets the form’s noValidate to true. Even if fields render native constraints such as required or type="email", the browser’s native validation bubbles will not be triggered; only Validator’s own rules run on submit.
• To enable the browser’s native form validation capability, set vanilla: true. This automatically skips Validator’s own rules.
• destroy() restores the noValidate state from before the instance was created.

bindEvents

The third parameter bindEvents is a Boolean, defaulting to false.

• false: You need to call the validate method manually. Advantage: custom validation interactions, such as showing errors through toast or other UI.
• true: Automatically binds the form’s submit and reset events. submit prevents the default submission and runs validate() automatically.

Instance Properties

After destroy(), both element and props become null; event listeners and validation hints are cleaned up.

Instance Methods

validate()

Run form validation and return whether it passes. It only validates fields that have a name and are configured in props.rules. After all fields pass, it calls props.onSubmit(validator).

JavaScript
if (validator.validate()) {  // passed}

reset(options)

Reset validation state.

JavaScript
validator.reset();validator.reset({ native: false });

destroy()

Destroy the Validator instance: unbind events, clean validation hints, release the form reference, and mark the instance as destroyed.

JavaScript
validator.destroy();

Built-in Rules

Text Fields

Select

Radio

Validator currently has no radio-specific built-in rule. To validate a radio group, you can use a custom validate rule to read the checked state of radios with the same name.

Checkbox

JavaScript
const validator = createValidator('#form', {  rules: {    features: { min: 2, max: 3 },  },  messages: {    features: {      min: 'Select at least 2 items',      max: 'Select at most 3 items',    },  },});

Switch

File Fields

Custom Rules

JavaScript
const validator = createValidator('#form', {  rules: {    username: {      validate: (element, validator) => {        if (element.value.includes('admin')) return 'Cannot contain admin';        return true;      },    },  },});

The validate function receives the field element and the current Validator instance, and returns:

Error Hint DOM

Validator first uses the nearest [data-field-control] as the field container. If it cannot find one, it uses the field’s direct parent element. The error hint node is written into the current field container:

HTML
<div data-field-control="email">  <input name="email" />  <div class="help-block" data-validator-help="email" data-valid="false">    Email required  </div></div>

• Attribute selectors: Validator relies on attribute names as interaction selectors. Existing static help text under [data-field-help] is not overwritten. Dynamic error hints are only created and deleted through [data-validator-help].
• Validation interaction: When validation fails, the error field is marked with [data-validator-help] and [data-valid]. After validation passes, the markers are removed.
• Automatic validation: After submit or a manual validate() call fails, Validator uses the error field records stored in runtime.error to automatically revalidate on input / change events. After the runtime.error records are cleared, the automatic validation events are also cleared.
• Custom error styles: You can use the className configuration to customize error hint styles.