# onSubmit()

### Overview

`onSubmit` is a [\<Feathery.Form>](https://docs.feathery.io/develop/react/api-guide/form) prop and callback function to access and modify form state when a form step is successfully submitted. It's called every time the user is about to successfully submit a step of the form, but before the actual submission happens. This function can be asynchronous.

### Usage <a href="#usage" id="usage"></a>

You can use `onSubmit` to store the submitted user data, update your rendered components, set custom errors, and more. It takes a single [Context](#context-api) object that provides form-related state and handlers.

```
import { init, Form } from '@feathery/react';

function App() {
  // Initialize Feathery
  init('SDKKey', 'bob@feathery.io');

  // Show the `aBcDeF` Feathery form
  return <Form
    formId='aBcDeF'
    // Store form data in backend
    onSubmit={(context) => {
      writeToBackend(context.submitFields);
      if (context.lastStep) console.log("User finished form!");
    }}
  />
}
```

### Context API

<table><thead><tr><th width="230.33333333333331" align="center">Key</th><th align="center">Type</th><th>Description</th></tr></thead><tbody><tr><td align="center"><a href="../../../../context-api">Form Context</a></td><td align="center"></td><td>Consistently available form state and functions</td></tr><tr><td align="center"><code>submitFields</code></td><td align="center"><a href="#fielddata-definition">fieldData</a></td><td>The data of fields that the user just submitted. Excludes fields hidden by conditional rules.</td></tr><tr><td align="center"><code>trigger</code></td><td align="center"><a href="#triggerdata-object">triggerData</a></td><td>Info of the element that triggered the submission.</td></tr></tbody></table>

#### `triggerData` Object <a href="#triggerdata-object" id="triggerdata-object"></a>

|      Key      |      Type     | Description                                                                                                                                                      |
| :-----------: | :-----------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|      `id`     |    `string`   | The ID of the element that triggered the submission                                                                                                              |
|     `text`    |    `string`   | The text displayed on the element that triggered the submission.                                                                                                 |
|     `type`    | `string enum` | The type of element that triggered the submission. Can be `button`, `text`, or `field`.                                                                          |
| `repeatIndex` |   `integer`   | If the element that triggered the submission repeats, this specifies which repetition it is. This value is 0-indexed and equals 0 if the element doesn't repeat. |

#### `fieldData` Definition&#x20;

The object keys are unique field IDs, defined in the Feathery dashboard. They map to objects that store additional field-specific information, defined below.

|      Key      |                 Type                | Description                                                                                                                                                  |
| :-----------: | :---------------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `displayText` |          `optional string`          | Text to display to your user along with the field                                                                                                            |
|     `type`    |            `string enum`            | Field type (e.g. `textarea`, `checkbox`, etc.)                                                                                                               |
|    `value`    |        `optional polymorphic`       | User-submitted value for this field. `null` if no submission, `Promise<File>` if file submission, Base64 `string` if signature, array of values if repeated. |
|   `position`  |              `number[]`             | Indices reflect the current element's position relative to other elements on the page.                                                                       |
|   `options`   | `{value: string, label?: string}[]` | Allowed options to choose from, if the field specifies them (e.g. dropdown, radio buttons, etc.)                                                             |

#### `fieldData` example <a href="#fielddata-example" id="fielddata-example"></a>

```
{
  age: {
    displayText: 'How old are you?',
    type: 'integer_field',
    value: 21 
  },
  photo_id: {
    displayText: 'Upload a photo of your ID',
    type: 'rich_file_upload',
    value: Promise<File>
  }
}
```

### Return value

A promise can be optionally returned from this function if it's asynchronous and you want execution to await.