# frameSubmit

> Submits a form into the frame that renders it: the frame posts the form's data and renders the answer in one request, keeping its own address for later reloads.

```ts
import { frameSubmit } from "@sdxc/ui/mixins";
```

Sends the form's submission through its enclosing frame, marking the form `aria-busy` until
the answer renders there; the frame then returns to its own address, so the action answers a
frame request with the frame's content, a redirect to it included. A newer submission wins.

## Signature

```ts
frameSubmit(options?: FrameSubmit.Options): MixinDescriptor<HTMLFormElement>
```

## Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `options?` | `FrameSubmit.Options` |  |

## Examples

```tsx
<form method="post" action="/actions/rename" mix={[frameSubmit()]}>…</form>
```

```tsx
form.addEventListener("ui:frame-submit", (event) => event.state === "failed" && retry());
```

## Used with it

The events, constants and types its module publishes, each imported from `@sdxc/ui/mixins` too.

### FrameSubmitEvent

Dispatched on a frameSubmit form as a submission moves through its states. Each
submission reports `pending` and then exactly one of the other states.

#### Signature

```ts
new FrameSubmitEvent(init: { state: FrameSubmit.State; action: string; error?: unknown })
```

#### Properties

| Property | Type | Description |
| --- | --- | --- |
| `state` | `readonly FrameSubmit.State` | Where the submission stands; `pending` always comes first. |
| `action` | `readonly string` | The address the form submitted to. |
| `error` | `readonly unknown` | Why the frame could not load the answer, set only on `failed`. |

### FrameSubmit.Options

Configuration for frameSubmit.

#### Members

| Member | Type | Description |
| --- | --- | --- |
| `keepSrc?` | `boolean` | Keeps the frame's own address for later reloads. Set `false` to have the frame adopt the form's action as its address once the submission settles. |

### FrameSubmit.State

Where a submission stands: `pending` once it is sent, `settled` once the frame shows the
answer, `aborted` when a newer reload of the frame replaced it, and `failed` when the
frame could not load the answer.

#### Signature

```ts
type FrameSubmit.State = "pending" | "settled" | "aborted" | "failed"
```

One of `"pending"`, `"settled"`, `"aborted"`, `"failed"`.