# Submit

**`sonic-submit`** sends the form publisher named by `formDataProvider` to a REST endpoint and writes the response to `submitResultDataProvider`. The request is configured like [Fetch](/core/components/functional/fetch): `serviceURL` on an ancestor, path from the ancestor `dataProvider` or from `endPoint`. Form fields such as `sonic-input` fill the publisher through their `name`.

## Basic example

`onClick` sends on a click inside the element, `onEnterKey` on Enter in a focused field inside it. The method defaults to `post` and the body to JSON. Fields are validated first; while the request runs, the content is faded and not clickable.

<docs-lit-demo for="docs-submit-demo"></docs-lit-demo>

## Result key

When the API wraps its payload (`{ data: { id, token } }`), set `submitResultKey` to a dot path so `submitResultDataProvider` receives only that part.

<docs-lit-demo for="docs-submit-result-key-demo"></docs-lit-demo>

## Reset after submit

`clearedDataOnSuccess` on an ancestor lists publisher ids, separated by spaces, that are set to `{}` once the API returns a result. This includes error results with `messages`.

<docs-lit-demo for="docs-submit-clear-demo"></docs-lit-demo>

## Submit event

After each request, `sonic-submit` dispatches a bubbling `submit` event whose `detail` is the result, the same value written to `submitResultDataProvider`.

<docs-lit-demo for="docs-submit-event-demo"></docs-lit-demo>

## Endpoint override

`endPoint` on `sonic-submit` replaces the ancestor `dataProvider` as the request path, for this element only.

<docs-lit-demo for="docs-submit-endpoint-demo"></docs-lit-demo>

## HTTP method

Set `method` to `put` · `patch` · `delete` · `get` (default `post`). It is read on `sonic-submit` only, never inherited. With `get`, the fields are appended to the endpoint as a query string.

<docs-lit-demo for="docs-submit-get-demo"></docs-lit-demo>

## Multipart body

`sendAsFormData` sends the fields as `multipart/form-data` instead of JSON. The response is still parsed as JSON.

<docs-lit-demo for="docs-submit-formdata-demo"></docs-lit-demo>

## Native form

With `native`, no request is made: after validation, the publisher values are copied into the matching controls of the closest `<form>` (hidden inputs are created when missing), then the browser submits the form. `name` and `value` on `sonic-submit` are sent as the submit button pair. Use a `target` iframe to stay on the page.

<docs-lit-demo for="docs-submit-native-demo"></docs-lit-demo>

## Nested fields

A dot in a field `name` stores a nested object in the form publisher, and the body is sent with the same shape.

<sonic-code>
  <template>
    <sonic-scope formDataProvider="submit-example-dot-notation">
      <div class="grid grid-cols-2 gap-4">
        <sonic-input label="Passenger" name="passenger.name" value="Ada Lindqvist"></sonic-input>
        <sonic-input label="Seat" name="passenger.seat" value="2A"></sonic-input>
      </div>
    </sonic-scope>
  </template>
</sonic-code>

<sonic-code language="typescript">
  <template>
{ passenger: { name: "Ada Lindqvist", seat: "2A" } }
  </template>
</sonic-code>

## API reference

| Attribute | Values | Description |
|-----------|--------|-------------|
| `onClick` | boolean | Sends on click inside the element |
| `onEnterKey` | boolean | Sends on Enter in a focused field inside the element |
| `method` | `post` · `put` · `patch` · `delete` · `get` (default `post`) | HTTP method. `get` sends the fields as a query string |
| `endPoint` | string | Request path. Overrides the ancestor `dataProvider` |
| `submitResultKey` | string | Dot path of the response part written to `submitResultDataProvider` |
| `sendAsFormData` | boolean | Sends `multipart/form-data` instead of JSON |
| `native` | boolean | Fills and submits the closest `<form>` instead of calling the API |
| `name` · `value` | string | Submit button pair added to a native form submission |
| `disabled` | boolean | Ignores triggers. Set while a request runs |
| `usernameKey` · `passwordKey` | string (default `username` · `password`) | After a successful response, fields stored with the Credential Management API when both are present |

| Ancestor attribute | Description |
|--------------------|-------------|
| `serviceURL` | API base URL |
| `dataProvider` | Default request path |
| `formDataProvider` | Publisher sent as the body. Required |
| `submitResultDataProvider` | Publisher receiving the result |
| `headersDataProvider` | Publisher sent as request headers |
| `clearedDataOnSuccess` | Space-separated publisher ids reset to `{}` after a result |

When the form or headers publisher has `needsCaptchaValidation`, the request waits for a [Captcha](/core/components/ui/captcha) token. A network failure produces a result with an error message in `messages`.

| Event | Detail |
|-------|--------|
| `submit` | The result (after `submitResultKey`) |

| Slot | Description |
|------|-------------|
| *(default)* | Fields and buttons that trigger the submission |