Validation

The prepareForm function can also accept a validation function. It's a function that accepts the current form values and needs to return an object with the same shape, but instead of the property values it can have a string or array of strings containing the validation messages.

prepareForm('felte-form-id', {
  // ...
  validate: (values) => {
    const errors = {}
    if (!values.email || !/^[^@ \t\r\n]+@[^@ \t\r\n]+\.[^@ \t\r\n]+/.test(values.email)) {
      errors.email = 'Must be a valid email';
    }
    if (!values.password) errors.password = [
      'Must not be empty',
      'Must be over 8 characters',
    ];
    if (values.password && values.password.length < 8) {
      errors.password = ['Must be over 8 characters'];
    }
    return errors;
  },
  // ...
});

It shouldn't be a hard task to use a third party library, as long as you transform their result into something that Felte understands.

Note that the validate function can be asynchronous.

Felte will validate whichever field it considers as touched as you fill the form, and it will validate all fields (and set them as touched) when submitting it.

Server errors

You can add an onError function to the createForm configuration that will be called if the onSubmit function throws an error. It will be called with the value thrown from the onSubmit function, or with an instance of FelteSubmitError if using Felte's default submit handler. You can use the onError function to shape your server errors into the same shape that the validate function expects and return them from the same function for them to be handled.

prepareForm('felte-form-id', {
  // ...
  // Assuming your server already returns them with the appropriate shape.
  // Might not be the case for most cases.
  onError: (errors) => errors,
  // ...
});

Alternatively, you can capture the felteerror custom event from your form element. You'd need to update your errors store manually if you use this.

Error handling

prepareForm returns also its errors and touched values as accessors.

The <felte-form> element exposes the current value of its errors and touched stores in properties of the same name. You can react to its changes by either assigning a function to .onErrorsChange and .onTouchedChange, or using an event listener for the events errorschange and touchedchange.

There are similar methods and events for all the other available stores.

<script type="module">
  import '@felte/element/felte-form';

  const felteForm = document.querySelector('felte-form');

  felteForm.configuration = { \* ... *\ };

  const errorsContainer = document.querySelector('#errors');
  felteForm.onErrorsChange = () => {
    errorsContainer.textContent = JSON.stringify(felteForm.errors, null, 2);
  };

  const touchedContainer = document.querySelector('#touched');
  felteForm.addEventListener('touchedchange', () => {
    touchedContainer.textContent = JSON.stringify(felteForm.touched, null, 2);
  });
</script>

<pre id="errors"></pre>

<pre id="touched"></pre>

You can read more above them in the stores section.

You don't need to manually handle this errors. Felte provides four official packages to handle your errors for you, either using Tippy, directly mutating the DOM, providing a custom element or using the browser's built-in constraint validation API. You can read more about this in the reporters section.

Multiple validations

The validate property of the configuration object can also be an array of validation functions. The resulting errors from running each validation function will be merged into a single object. If a single property was assigned two or more errors from the validation functions, the property will be an array of strings. This might not be useful for common scenarios, but it will come useful when using any of our validator packages.

Warnings

Sometimes you may want to display certain validation messages that do not prevent the form from submitting, such as a password security message. Felte provides a store called warnings for this, and such warnings can be added to the store by using the warn property on the configuration (either directly in the element or using prepareForm).

const felteForm = document.querySelector('felte-form');
felteForm.configuration = {
  // ...
  warn: (values) => {
    const warnings = {}
    if (values.password && values.password.length < 8) {
      warnings.password = 'Your password could be more secure';
    }
    return warnings;
  },
  // ...
};

The warn function works exactly the same as the validate function. With the same features and constraints. Multiple warn functions can be passed as an array, and the shape of warnings can contain either a string or an array of strings.

Async validations

Felte supports asynchronous validations by default by returning a promise from your validation functions, either for warnings or errors. Felte takes care of possible race conditions by ignoring the results of previous async validations if it's executed again before the previous one finishes.

const felteForm = document.querySelector('felte-form');
felteForm.configuration = {
  // ...
  validate: async (values) => {
    const response = await someAsyncAction(values);
    // Do something with the response and return the errors
  },
  // ...
};

Validations execute at every keypress, so make sure to not execute anything you don't want to spam. For these kinds of actions, Felte also supports for your validations to be debounced.

Debounced validations

If your validation shouldn't be called for every keypress of the user, such as an expensive synchronous validation or an API call, Felte can debounce said validations for you. These validations should be added within the debounced property of Felte's configuration:

const felteForm = document.querySelector('felte-form');
felteForm.configuration = {
  // ...
  debounced: {
    // defaults to 300
    timeout: 300,
    validate: async (values) => {
      const response = await someFetchCall(values);
      // Do something with the response and return the errors
    },
    warn: async (values) => {
      const response = await someOtherFetchCall(values);
      // Do something with the response and return the warnings
    },
  },
  // ...
};

The debounced object accepts the following properties: