Dictation SDK Modes and Callbacks

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

mode: "scratchpad";

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

Callback contract

Payload shape for every callback:

JavaScript

{
  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

onSubmit: ({ fieldId, text }) => save(fieldId, text);

If onSubmit is missing, dictation often closes immediately after the user acts. Always provide onSubmit.

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 for the same tables alongside AuthConfig.

Next steps

JavaScript integration for show() and switching fields
React integration for Dictation props
Error handling if callbacks or layout behave unexpectedly

​Overview

​Dictation modes

​Callback contract

​ShowOptions summary

​Next steps

Overview

Dictation modes

Callback contract

ShowOptions summary

Next steps