Skip to main content
Quick summary
In-field mode is how you embed the Suki Dictation SDK on a text field in an existing web application, so dictation stays tied to that one control instead of floating on its own. You decide how users start dictation in your app and receive the transcript text through callbacks.
Last updated:April 2026

​
Overview

In-field mode allows you to embed the Suki Dictation SDK directly into a text field within your application. This ensures dictation remains tied to a specific control rather than floating independently. You choose the entry point for starting dictation based on your application’s user interface. Launching dictation The entry point is entirely part of your UI. You can use a button, an icon, a menu item, or a keyboard shortcut. To launch the session for a specific field, your code must call show() in JavaScript or mount the Dictation component in React. Managing the dictation interface Once the session is open, the Suki Dictation SDK provides the dictation surface. This includes the microphone, Submit, and Cancel controls. The interface appears as a hosted iframe inside the rootElement you provide. Keep the following requirements in mind to ensure the interface displays correctly:
  • Container sizing: The iframe sizes itself to the container you provide.
  • Dimensions: You must provide a specific height and width for the interface to appear correctly.
  • Data handling: You receive transcript text through defined callbacks.
  • Troubleshooting: If the interface does not appear, check your layout and Content Security Policy (CSP) settings.
The diagram below is a simple healthcare-style form with several text areas. Only one field shows a Dictate control in the top right of that field; the rest are plain.
You can place the button or icon anywhere in your application that fits your design. These screens are only examples.
Subjective and Objective SOAP sections; Subjective shows placeholder text and a Dictate button with microphone in the field header area; Objective shows sample vitals and exam placeholder.
Subjective SOAP section with patient symptoms description; Suki in-field dictation active with microphone, settings gear, and checkmark submit in the note container.

​
When to choose in-field mode

Use in-field mode when:
  • You embed dictation for a specific text field (or editor) and you design the entry point yourself (for example a Dictation button, icon, or toolbar action that calls show() or mounts <Dictation>).
  • You want Suki’s dictation overlay on the field’s container (rootElement), so mic, submit, and cancel sit with that target instead of a standalone floating panel.
For dictation that is not bound to a single input, use Scratchpad mode instead.

​
How to configure in-field mode

For in-field dictation you configure three things: mode, rootElement, and fieldId. Together they tell the SDK which layout to use, where to put the iframe, and how to label this session in callbacks.

​
Mode

Set mode to the string "in-field" so the SDK uses the overlay-on-container layout instead of scratchpad.
  • JavaScript: include mode: "in-field" in the object you pass to DictationClient.show().
  • React: set mode="in-field" on <Dictation>.
Mode configuration
mode: "in-field",

​
Root element

Set rootElement to know which element on your page should contain the dictation iframe. The SDK inserts the iframe inside that element. It is not the answer to “which input gets the text”; you apply transcript text in callbacks (and often target your field by fieldId or your own state). Recommended pattern: Use a parent <div> that wraps the notes area, and pass that div as rootElement. Pass document.getElementById("…") (or a ref in React) for that wrapper, not for the <textarea> or <input> alone. Example markup and how it maps to rootElement: 
<!-- rootElement = this outer div (the iframe mounts inside it) -->
<div id="clinical-notes-dictation-root"></div>
<textarea id="clinical-notes"></textarea>
The wrapper and textarea can be structured however your layout needs; the important part is that rootElement points at the element that should host the iframe, not at the textarea node.
Do thisSo that
Give the host element a visible height and widthThe iframe fills its parent. A parent with no height often produces a blank area where dictation should be.
Set position: relative on the host when you use overlays or stackingThe dictation layer stays aligned with the field region in typical layouts.
Refer to Configuration for every ShowOptions field and matching React props.

​
Field ID

fieldId is a string you invent to name this dictation session. Every callback sends it back with text, so you know which field the result belongs to if you have several on the page. It does not have to match a DOM id, but using the same value as your input’s id is a simple pattern. Each open dictation instance should use a stable, unique fieldId. Examples for SOAP-style sections: soap.subjective, soap.objective, soap.assessment, soap.plan. Refer to Callback contract payload shape for more details.

​
How to use in-field mode

You build how users start dictation: a Dictation button, a link, an icon, or any control that calls show() or mounts <Dictation>. After they start, Suki draws the dictation UI inside the iframe: microphone, submit, cancel, and the rest. You do not rebuild those controls yourself. You receive text and events through onSubmit, onCancel, and optionally onDraft.

​
Quick reference

ItemIn-field behavior
LayoutDictation sits over the input container you target with rootElement
Mode"in-field"
Root elementRecommended: element that wraps the field

​
Next steps

Refer to Scratchpad mode for floating dictation off a single field.
Last modified on April 20, 2026