Introduction

Working with the WixForms API

To work with a WixForms $w element using the API:

1. Add and set up the Wix Form app on your site.

   When you add the $w WixForms element, a $w Form element is also added, with its own properties and events. Think of the Form element as a container for the Wix Form's input elements and buttons. These two elements work together, meaning, if you hide or collapse either the WixForms or the Form element, the other element is also hidden/collapsed. All Wix Forms app's APIs are used on the WixForms element, not the Form element.

2. Set up the collection for form data.

   Depending on the form you choose, a Wix app starter collection is added to your site. You can see it in the Velo sidebar in Content Collections in the Databases section. You can use this collection "as is," or you can use the collection as a template, modifying its fields as you like.

3. Use the WixForms APIs to handle events and submit data to the server for processing.

The WixForms API does not use functionality provided by FormElement, but the user input elements that are wrapped within the corresponding Form element can. For example, you cannot check if a Wix Form has changed using onChange, but you can check if one of the Wix Form's Form fields has changed.

Note: Alternatively, instead of using the Wix Forms APIs, you can use the Velo API to create your own custom form without the Wix Forms app and connect the form's fields to a custom collection. You can create the custom form with standard input elements and a button for submission. When customizing your own form, you have options that might not yet be available from the Wix Forms app. For example, you can add more varied input elements not yet supported by the app.

Event Handling

This diagram shows the order that Wix Forms events are handled:

When a visitor clicks the Submit button:

1. The onWixFormSubmit() event handler sets events that fire when a site visitor submits a Wix Form yet before the Wix Form is actually sent to the server.

   The onWixFormSubmit() event handler runs on the client side.

   Generally you define all validations and operations in one onWixFormSubmit event handler. You can define more than one onWixFormSubmit event handler, for example, if you like to split your code into chunks.

   Use the onWixFormSubmitted() event handler to check that the data for the Wix Form was successfully submitted to the server.

   Note: assuming an onClick() event handler is also defined, both its events and the onWixFormSubmitted events fire when a site visitor clicks the Wix Form's Submit button.

2. After the WixFormSubmit events are fired, the Wix Form is sent to the server. The submission either succeeds or fails:

   • If the Wix Form submission succeeds, the onWixFormSubmitted event handler runs. onWixFormSubmitted sets events that fire when a site visitor submits a Wix Form and the form is successfully sent to the server for asynchronous processing.

     Use this event handler to handle client side operations, such as displaying a message indicating the successful submission. The event handler starts even while the server is still performing its own backend operations.

   • If the Wix Form submission fails, the onWixFormSubmittedError event handler is fired.

     Use this event handler to define client side operations for failed submits, such as displaying a message requesting the visitor try again later.

3. The onFormSubmit() backend event handler starts as soon as the Wix Form is received by the server. and asynchronous backend processing starts. For example, use this event handler to send an email indicating that the Wix Form was submitted and at what time it was submitted.