Events

A number of events, triggered on form submission, give you full control over the submit process. They are triggered every time the form is submitted.

Event flowchart

Usage

const { form, enhance } = superForm(data.form, {
  onSubmit: ({ action, formData, formElement, controller, submitter, cancel }) => void
  onResult: ({ result, formEl, cancel }) => void
  onUpdate: ({ form, cancel }) => void
  onUpdated: ({ form }) => void
  onError: (({ result, message }) => void) | 'apply'
})

onSubmit

onSubmit: ({
  action,
  formData,
  formElement,
  controller,
  submitter,
  cancel
}) => void;

The onSubmit event is the first one triggered, hooking you into SvelteKit’s own use:enhance function, and also giving you a chance to cancel the submission altogether. See the SvelteKit docs for the SubmitFunction signature.

onResult

onResult: ({ result, formEl, cancel }) => void

If the submission isn’t cancelled, the form is posted to the server. It then responds with a SvelteKit ActionResult, triggering the onResult event.

result contains the ActionResult. You can modify it; changes will be applied further down the event chain. formEl is the HTMLFormElement of the form. cancel() is a function which will cancel the rest of the event chain and any form updates.

Common usage

onResult is useful when you have set applyAction = false and still want to redirect, since the form doesn’t do that automatically in that case. Then you can do:

const { form, enhance } = superForm(data.form, {
  applyAction: false,
  onResult({ result }) {
    if (result.type === 'redirect') {
      goto(result.location);
    }
  }
});

Also, if applyAction is false, which means that $page.status won’t update, you’ll find the status code for the request in result.status.

Strongly typed ActionResult

Usually, you check the ActionResult status in onResult, not the form validation result, which is more conveniently handled in onUpdate (see below). But if you return additional data in the form action, there is a helper type called FormResult, that you can use to make the ActionResult data strongly typed:

<script lang="ts">
  import { superForm, type FormResult } from 'sveltekit-superforms/client';
  import type { PageData, ActionData } from './$types';

  export let data: PageData;

  const { form, enhance } = superForm(data.form, {
    onResult: (event) => {
      const result = event.result as FormResult<ActionData>;
      if (result.type == 'failure') {
        // Strongly typed now:
        console.log(result.data?.form.data.name);
      }
    }
  });
</script>

onUpdate

onUpdate: ({ form, formEl, cancel }) => void

The onUpdate event is triggered just before the form update is being applied, giving you the option to modify the validation result in form, or use cancel() to negate the update altogether. You also have access to the form’s HTMLFormElement with formEl.

When you don’t want to modify or cancel the validation result, the last event is the most convenient to use:

onUpdated

onUpdated: ({ form }) => void

When you just want to ensure that the form is validated and do something extra afterwards, like showing a toast notification, onUpdated is the easiest way.

The form parameter contains the validation result, and is read-only here, since the stores have updated at this point.

Example

const { form, enhance } = superForm(data.form, {
  onUpdated({ form }) {
    if (form.valid) {
      // Successful post! Do some more client-side stuff,
      // like showing a toast notification.
      toast(form.message, { icon: '✅' });
    }
  }
});

onError

onError: (({ result }) => void) | 'apply'

When the SvelteKit error function is thrown on the server, you can use the onError event to catch it.

result is the error ActionResult, with the error property casted to App.Error. In this simple example, the message store is set to the error:

const { form, enhance, message } = superForm(data.form, {
  onError({ result }) {
    $message = result.error.message;
  }
});

You can also set onError to the string value 'apply', in which case the SvelteKit applyAction error behaviour will be used, which is to render the nearest +error page, also wiping out the form. To avoid data loss even for non-javascript users, returning a status message instead of throwing an error is recommended.