Submitting

Felte offers two ways to submit your form data:

Default handler

If no onSubmit function is provided on createForm, Felte will send a request using the following attributes from your form element:

If the request succeeds, Felte will emit a feltesuccess event that you can handle on your form element. This is a CustomEvent that contains the Response from fetch in the response property of detail, merged with the context object described below.

If the request fails, Felte will emit a felteerror event that you can handle on your form element. This is a CustomEvent that contains an object with a FelteSubmitError instance in the error property of detail, merged with the context object described below.

These events do not bubble.

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

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

  function handleSuccess(event) {
    const { response, ...context } = event.detail;
    // Do something with the response.
  }

  felteForm.addEventListener('feltesuccess', handleSuccess);

  function handleError(event) {
    const { error, ...context } = event.detail;
    // `FelteSubmitError` contains a `response` property
    // with the response from `fetch`
    const response = error.response;
    // Do something with the error
  }

  felteForm.addEventListener('felteerror', handleError);
</script>

<felte-form>
  <form action="/example" method="post">
    <input type="text" name="email" />
    <input type="password" name="password" />
    <button type="submit">Sign In</button>
  </form>
</felte-form>

Alternatively you can use the onSuccess and onError properties of prepareForm's configuration for this. onSuccess will receive a Response object as a first argument. onError will receive an instance of FelteSubmitError as a first argument.

FelteSubmitError

When using the default handler, if the request fails Felte will throw a FelteSubmitError. This is a a JavaScript error that contains a response property which is the Response object from the fetch request. The class for FelteSubmitError is exported from this package to allow for comparisons with instanceof.

Custom handler

prepareForm accepts an onSubmit function on its configuration object. If you set onSubmit, the default submit handler wil not run. Anything returned by this function will be passed as a first argument to onSuccess, and as the detail property of the feltesuccess custom event. Anything thrown from this function will be passed as a first argument to onError, and as the detail property of the felteerror custom event.

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

  prepareForm('signin-form', {
    onSubmit(values, context) {
      // ...
    },
    onSuccess(response, context) {
      // Do something with the returned value from `onSubmit`.
    },
    onError(err, context) {
      // Do something with the error thrown from `onSubmit`.
    },
  });
</script>

<felte-form id="signin-form">
  <form>
    <input type="text" name="email" />
    <input type="password" name="password" />
    <button type="submit">Sign In</button>
  </form>
</felte-form>

Context object

The onSubmit, onSuccess and onError functions also receive a second argument: an object with your form and input elements, your configuration and some helper functions (just like the ones returned from createForm):

prepareForm('form-id', {
  onSubmit: async (
    values,
    {
      form,
      event,
      controls,
      config,
      setFields,
      setData,
      setTouched,
      setErrors,
      setWarnings,
      unsetField,
      addField,
      resetField,
      reset,
      setInitialValues,
    }
  ) => {
    // ...
  },
});

Events contain these same properties from context alongside a response property for the feltesuccess event, and an errorproperty for the felteerror event.

// `feltesuccess` event handler
function onFelteSuccess({
  detail: {
    // The response from the fetch call
    response,
    // Context properties
    form,
    controls,
    config,
    setFields,
    setData,
    setTouched,
    setErrors,
    setWarnings,
    unsetField,
    addField,
    resetField,
    reset,
    setInitialValues,
  },
}) {
  // ...
}
// `felteerror` event handler
function onFelteError({
  detail: {
    // Instance of `FelteSubmitError`
    error,
    // Context properties
    form,
    controls,
    config,
    setFields,
    setData,
    setTouched,
    setErrors,
    setWarnings,
    unsetField,
    addField,
    resetField,
    reset,
    setInitialValues,
  },
}) {
  // ...
}

NOTE: TypeScript users may import the types FelteSuccessEvent, FelteErrorEvent, FelteSuccessDetail and FelteErrorDetail from this package.