Validate Form

To help with form validation, Joystick includes a built-in validation utility accessible via the component instance as instance.validate_form().

Example Usage

import joystick from '@joystick.js/ui';

const Index = joystick.component({
  events: {
    'submit form': (event = {}, instance = {}) => {
      event.preventDefault();
      instance.validate_form(event.target, {
        rules: {
          email_address: {
            required: true,
            email: true,
          },
        },
        messages: {
          email_address: {
            required: 'An email address is required.',
            email: 'A valid email is required.',
          },
        },
      }).then(() => {
        // Form is valid. Handle submission here.
      }).catch(() => {
        // Form is invalid. Handle warnings, etc., here.
      });
    },
  },
  render: () => {
    return `
      <div>
        <form>
          <label>Email Address</label>
          <input type="email" name="email_address" placeholder="Email Address" />
          <button type="submit">Subscribe</button>
        </form>
      </div>
    `;
  },
});

export default Index;

When called, validate_form() takes two arguments:

• A form_dom_node, which is the <form> element being validated.
• An options object containing validation rules (see the full list of rules below), messages, and optionally, a custom on_render_error() function.

If validation passes, the returned Promise resolves. If it fails, the Promise rejects and error messages are rendered automatically.

Custom Error Placement

To change where error messages are rendered, provide an on_render_error() function on the options object:

on_render_error: (element = {}, message = '') => {
  const error = document.createElement('p');
  error.classList.add('input-hint', 'error');
  error.setAttribute('id', `error-${element.name}`);
  error.innerText = message;
  return element?.closest('form').before(error);
}

API

Definition

validate_form(form_dom_node: DOMNode, options: object) => Promise;

Parameters

form_dom_node DOMNode required

A DOM node reference to the

element being validated.

options object required

An object of options to configure form validation.

rules object required

Validation rules keyed by input name, each with one or more validation rules.

messages object

Error messages keyed by input name and rule name.

on_render_error function

A function to customize where and how error messages are rendered. Receives the input DOM element and message.

Validation Rules

credit_card boolean

Validates whether the field contains a valid credit card number.

email boolean

Validates whether the field contains a valid email address.

equals string

Validates whether the field input equals the given value.

matches any

Validates whether the field input matches the given value in value and type.

max_length integer

Validates whether the field input is less than or equal to the given value.

min_length integer

Validates whether the field input is greater than or equal to the given value.

phone boolean

Validates whether the field input is a valid phone number.

postal_code boolean|object

Validates whether the field input is a valid postal code. May be an object containing ISO and rule.

required boolean

Validates whether the field input exists (is not empty).

semver boolean

Validates whether the field input is a valid semantic version.

slug boolean

Validates whether the field input is a valid slug (e.g., a-slug-like-this).

strong_password boolean

Validates whether the input matches a strong password pattern (min 8 chars, one upper, one lower, one number, one special).

url boolean

Validates whether the field input is a valid URL.

vat boolean|object

Validates whether the field input is a valid VAT number. May be an object with ISO and rule.