Form Validation

To help with form validation, Joystick includes a built-in form validation library that's accessible directly via the component instance.

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;

The form validator is accessed via the component instance as component.validate_form(). It takes two arguments: the DOM element representing the <form></form> you wish to validate and an options object containing the validation rules and error messages to render if the user's input fails validation.

On the options object, the rules property is set to an object where each of its properties corresponds to the name attribute on some input in your form. Set to that property is another object containing the rules for that field.

When component.validate_form() is called, it will attempt to validate the form per the rules you've specified. If it succeeds, it will resolve the JavaScript Promise it returns (meaning you can handle any post-validation work in the .then() callback of component.validate_form()). If it fails, error messages will automatically be rendered beneath the offending inputs and the JavaScript Promise returned is rejected (meaning you can handle any failure in the .catch() callback of component.validate_form()).

Error placement

By default, Joystick will automatically render error messages immediately after the offending input. In the event that your UI requires a different location, the on_render_error() option can be added to the options object passed to instance.validate_form():

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.',
          },
        },
        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);
        },
      }).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;

Instead of allocation errors to after the offending input, above, we use on_render_error() to move the error messages to render above the <form></form> element.

Validation Rules

Currently, component.validate_form() offers the following validation rules:

API Reference

validate_form()

Function API

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

// Alias:
validateForm(form_dom_node: DOMNode, options: object) => Promise;

Arguments