> ## Documentation Index
> Fetch the complete documentation index at: https://developer.suki.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Dictation SDK Modes and Callbacks

> In-field and scratchpad modes, ShowOptions, and onSubmit, onCancel, and onDraft for the Dictation SDK

## Overview

Dictation supports two **modes** and a small **callback contract**. All callbacks receive **`{ fieldId, text }`**.

This guide follows **Dictation Modes**, **Callback Contract**, and **ShowOptions** in **`Suki Dictation SDK.md`**.

## Dictation modes

| Mode             | Behavior                                                                            |
| :--------------- | :---------------------------------------------------------------------------------- |
| **`in-field`**   | Overlays the **input container**; provide `rootElement` when possible               |
| **`scratchpad`** | **Floating** standalone dictation UI when dictation is not tied to a specific field |

```javascript JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
mode: "scratchpad";
```

Use **`scratchpad`** when dictation is not tied to a specific input field.

## Callback contract

Payload shape for every callback:

```javascript JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{
  fieldId: string,
  text: string
}
```

| Callback       | Required | Purpose                                      |
| :------------- | :------- | :------------------------------------------- |
| **`onSubmit`** | Yes      | Commit dictation result                      |
| **`onCancel`** | No       | Discard session                              |
| **`onDraft`**  | No       | Intermediate updates while the user dictates |

**Example:**

```javascript JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
onSubmit: ({ fieldId, text }) => save(fieldId, text);
```

<Warning>
  If **`onSubmit`** is missing, dictation often **closes immediately** after the user acts. Always provide `onSubmit`.
</Warning>

## ShowOptions summary

| Field         | Required    | Description                    |
| :------------ | :---------- | :----------------------------- |
| `mode`        | Yes         | `"in-field"` or `"scratchpad"` |
| `fieldId`     | Yes         | Identifier echoed in callbacks |
| `rootElement` | Recommended | Container for the iframe       |
| `initialText` | No          | Seed content                   |
| `onSubmit`    | Yes         | Completion callback            |
| `onCancel`    | No          | Cancellation callback          |
| `onDraft`     | No          | Incremental updates            |

See [Configuration reference](./configuration) for the same tables alongside **AuthConfig**.

## Next steps

* [JavaScript integration](./javascript-integration) for `show()` and switching fields
* [React integration](./react-integration) for `Dictation` props
* [Error handling](./error-handling) if callbacks or layout behave unexpectedly