> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: $w

## Namespace: wix-forms

## Article: Introduction

## Article Link: https://dev.wix.com/docs/velo/velo-only-apis/$w/wix-forms/introduction.md

## Article Content:

# Introduction
The [Wix Forms app](https://support.wix.com/en/article/about-wix-forms) lets site visitors enter values for fields in a Wix Form and then submit it. 

 The `WixForms` API contains what you need to work with the [Wix Forms app](https://support.wix.com/en/article/velo-working-with-forms)
 using Velo APIs. You can customize how site visitors work with the Wix Form, while 
 taking advantage of the Wix Forms app's ease of design, automatic creation of submission collections, 
 payment receipt, automatic setup of email notifications, and more. 
 
 You do not need to import `$w` or `wix-crm` to work with `WixForms` APIs.

<blockquote class='important'>

__Important:__

 `WixForms` only works with old forms. 
 If a site is using a new form, you need to use the [`WixFormsV2`](https://dev.wix.com/docs/velo/velo-only-apis/$w/wix-forms-v2/introduction.md) API. 
 You can see which forms are old forms and which are new forms by looking at the forms and submissions page in a site dashboard, where there's a tab for each. 

 Learn more: [Migrate from WixForms to WixFormsV2](https://dev.wix.com/docs/velo/velo-only-apis/$w/wix-forms/migrate-from-wix-forms.md) 
</blockquote>

 ### Working with the WixForms API


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

 1. [Add and set up](https://support.wix.com/en/article/adding-and-setting-up-a-form-on-your-site) the 
    Wix Form app on your site. 

    When you add the `$w` `WixForms` element, a `$w` [`Form`](https://dev.wix.com/docs/velo/api-reference/$w/form/introduction.md) 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. 
 
 1. Set up the collection for form data.

    Depending on the form you choose, a [Wix app starter collection](https://support.wix.com/en/article/velo-working-with-wix-app-collections-and-code#what-are-wix-app-starter-collections) 
    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.

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

 
 > **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:  
 
 ![Wix Forms Event Handling](https://wixmp-833713b177cebf373f611808.wixmp.com/images/velo-images/media_wix_forms_events_flow.png)
  
 When a visitor clicks the Submit button:
 

 1. The [`onWixFormSubmit()`](#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()`](#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.  

 1. 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`](#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`](#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.

 1. The [`onFormSubmit()`](wix-crm-backend/events/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.