> ## 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.

# Configuration

> Learn how to configure the Suki Dictation SDK by configuring AuthConfig and ShowOptions

<div className="quick-summary-wrapper">
  <div className="quick-summary-header">
    <span className="quick-summary-icon" aria-hidden="true" />

    <span className="quick-summary-title">Quick summary</span>
  </div>

  <div className="quick-summary-content">
    Configuration has two parts. First, `AuthConfig`: the object you pass to `new SukiAuthManager({ ... })` from `@suki-sdk/core`. That step covers sign-in, tokens, and optional provider registration before dictation can run.

    <br />

    <br />

    Second, `ShowOptions`: what you pass to `DictationClient.show()` or as props on `Dictation` in React. That step sets mode and field, anchors the iframe in your layout, seeds text, and registers callbacks for each dictation session.
  </div>

  <div className="quick-summary-footer">
    <span className="quick-summary-footer-icon" aria-hidden="true" />

    <span className="quick-summary-footer-text">Last updated:</span>
    <span className="quick-summary-footer-date">June 2026</span>
  </div>
</div>

Dictation configuration has two steps: authenticate with **Suki for Partners**, then define how each dictation session is shown in your app.

<Steps>
  <Step title="Authenticate with the Suki for Partners">
    Build an **`AuthConfig`** object and pass it to **`new SukiAuthManager({ ... })`** from **`@suki-sdk/core`**. The manager handles your connection to the platform. Configure:

    * **`partnerId` and `partnerToken`:** Credentials Suki issues for your integration.
    * **Provider:** Optional fields that identify the clinician (for example **`providerId`**, **`providerName`**).
    * **Environment:** Target deployment (**`"staging"`** or **`"production"`**).
    * **Login behavior:** Whether the manager signs in when it is created (**`loginOnInitialize`**) or you call **`login()`** later.

    **`SukiAuthManager`** signs in and refreshes tokens from these settings. Authentication must succeed before the hosted dictation iframe can open.
  </Step>

  <Step title="Define session options">
    Pass a **`ShowOptions`** object whenever you start a session. In JavaScript, pass it to **`DictationClient.show()`**. In React, pass the same fields as props on **`Dictation`**.

    Typical **`ShowOptions`** fields include:

    * **Mode:** How the dictation UI is presented (for example in-field vs scratchpad).
    * **Field:** Stable field identifiers the SDK uses for callbacks.
    * **Mounting:** Where the iframe attaches in your DOM (**`rootElement`**).
    * **Seed text:** Optional starting text for the session.
    * **Callbacks:** Handlers for submit, cancel, and draft events.
  </Step>
</Steps>

<Tip>
  Modes control where the iframe lives. Read [In-field mode](/dictation-sdk/guides/in-field-mode) and [Scratchpad mode](/dictation-sdk/guides/scratchpad-mode) for UX and layout. For when each callback runs, see [Callbacks](/dictation-sdk/guides/callbacks).
</Tip>

## AuthConfig

**`AuthConfig`** is the object you pass to **`new SukiAuthManager({ ... })`**. It is used to configure the Suki Auth Manager.

**`SukiAuthManager`** runs first in the lifecycle: it validates this configuration, signs in to the **Suki platform** with your partner credentials, and refreshes tokens so the hosted dictation iframe can open. Until auth succeeds, dictation does not start.

### AuthConfig properties

<Expandable title="AuthConfig fields" defaultOpen="true">
  <ResponseField name="partnerId" type="string" required>
    Partner identifier from Suki. Without a valid value, the iframe cannot initialize.
  </ResponseField>

  <ResponseField name="partnerToken" type="string" required>
    Partner auth token from Suki. Invalid credentials block the hosted dictation UI.
  </ResponseField>

  <ResponseField name="environment" type="string">
    **Optional**. Use **`"staging"`** or **`"production"`** so the SDK targets the right environment.
  </ResponseField>

  <ResponseField name="autoRegister" type="boolean">
    **Optional**. When **`true`**, enables provider auto-registration. Provider metadata may be required; confirm with your package README or Suki contact.
  </ResponseField>

  <ResponseField name="loginOnInitialize" type="boolean">
    **Optional**. When **`true`**, the SDK logs in during **`SukiAuthManager`** construction. You can instead construct the manager and call **`login()`** later when your app is ready.
  </ResponseField>

  <ResponseField name="providerId" type="string">
    **Optional**. Identifier for the provider in your system.
  </ResponseField>

  <ResponseField name="providerName" type="string">
    **Optional**. Full provider display name (for example, first, middle, and last name separated by spaces). It is **required** when **`autoRegister`** is **`true`**.
  </ResponseField>

  <ResponseField name="providerOrgId" type="string">
    **Optional**. Organization identifier for the provider in your system. It is **required** when **`autoRegister`** is **`true`**.
  </ResponseField>

  <ResponseField name="providerSpecialty" type="string">
    **Optional**. Clinical specialty (for example, **`FAMILY_MEDICINE`**). Refer to [Specialties](/documentation/specialties) for values your integration may use.
  </ResponseField>
</Expandable>

<Note>
  If **`autoRegister`** is enabled, **provider metadata** may be required in addition to the fields above.
</Note>

## ShowOptions

**`ShowOptions`** is what you pass to **`await dictationClient.show({ ... })`**. It is used to configure the Suki Dictation Client using the JavaScript package.

In React, **`Dictation`** accepts the same fields as props wherever the shipped types expose them (**`mode`**, **`fieldId`**, **`rootElement`**, **`initialText`**, **`onSubmit`**, **`onCancel`**, **`onDraft`**, and so on). Think of it as one contract: **imperative** object vs **declarative** props.

### ShowOptions properties

<Expandable title="ShowOptions fields" defaultOpen="true">
  <ResponseField name="mode" type="string" required>
    **`"in-field"`** overlays dictation on a container you own (next to or over a field). **`"scratchpad"`** uses a standalone floating surface. See [In-field mode](/dictation-sdk/guides/in-field-mode) and [Scratchpad mode](/dictation-sdk/guides/scratchpad-mode).
  </ResponseField>

  <ResponseField name="fieldId" type="string" required>
    A **stable**, **unique** string that names this dictation instance. The SDK echoes it on every callback as `{ fieldId, text }`. See [Field IDs in practice](#field-ids-in-practice) below for naming patterns.
  </ResponseField>

  <ResponseField name="rootElement" type="HTMLElement">
    **Recommended**. DOM node that hosts the dictation iframe. The iframe sizes to this container. A collapsed or zero-height parent produces a blank area. For layout patterns, refer to [Wrapper layout](#wrapper-layout).
  </ResponseField>

  <ResponseField name="initialText" type="string">
    **Optional**. Seed text shown when the session opens (for example the current value of your textarea).
  </ResponseField>

  <ResponseField name="onSubmit" type="function" required>
    Runs when the user **commits** the transcript. You receive `{ fieldId, text }`. Always implement this callback; without it, dictation often closes immediately after the user acts. Details: [Callbacks](/dictation-sdk/guides/callbacks).
  </ResponseField>

  <ResponseField name="onCancel" type="function">
    **Optional**. Runs when the user leaves without committing. Same payload shape as other callbacks.
  </ResponseField>

  <ResponseField name="onDraft" type="function">
    **Optional**. May run when the user does not submit and switches context (for example, another field). Not fired on each live transcript edit. Same payload shape. See [Callbacks](/dictation-sdk/guides/callbacks).
  </ResponseField>
</Expandable>

<Warning>
  If **`onSubmit`** is missing, dictation often **closes immediately** after the user acts. Treat it as required in real integrations.
</Warning>

## Field IDs in practice

**`fieldId`** is a **stable string you choose** to identify which note field or dictation target this session is for. The SDK includes it on every callback together with **`text`**, so you can match each transcript to the correct field in your app.

You can use any stable string. A common shortcut is to use the **same value** as the target control's HTML **`id`**: then in **`onSubmit`** you can run **`document.getElementById(fieldId)`** and assign **`text`** to that element. If you prefer another naming scheme, **`fieldId`** does not have to match a DOM **`id`**; just route **`text`** in your handler using the **`fieldId`** you chose.

For structured notes, common examples are **`soap.subjective`**, **`soap.objective`**, **`soap.assessment`**, and **`soap.plan`**. For a scratchpad or floating session, a dedicated id such as **`scratchpad`** (or a namespaced value if you run more than one) keeps callbacks unambiguous.

<Note>
  * Each **active** dictation instance should have its own stable id. If you call **`show()`** again, you **replace** the active session; you do not need **`hide()`** between fields for that pattern.

  * The object every callback receives is documented in [Callback contract payload shape](/dictation-sdk/guides/callbacks#callback-contract-payload-shape) in the Callbacks guide.
</Note>

## Callback argument shape

For the callback argument payload shape, refer to [Callback argument shape](/dictation-sdk/guides/callbacks#callback-contract-payload-shape).

## Wrapper layout

<span id="wrapper-layout" />

A **wrapper layout** is the layout where **`rootElement`** is a **dedicated container** (usually a **`div`**) with **stable width and height**, not the raw **`<textarea>`** or **`<input>`** you dictate into. Note fields grow and reflow with content; the iframe needs a host whose dimensions **you** control.

Set **`rootElement`** to that container. The SDK inserts the dictation UI there and sizes it to that element’s width and height.

When that element is **too small**, has **no height**, or **resizes often** (for example when a flex or grid parent collapses), the UI may show a **blank** area, look **clipped**, or **jump** when the page reflows.

To create a wrapper layout, follow these best practices:

* Add that **`div`** where the iframe should live, often **beside or over** the note field.
* Give it a **real height** (**`height`**, **`min-height`**, or a parent that already has height) so the iframe has room to draw.
* Use **`position: relative`** on the wrapper when you need the overlay to align with the rest of your layout.

### Recommended wrapper CSS

```css CSS theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
/* Class on the element you pass as rootElement, or on an outer host that sizes the region */
.wrapper {
  position: relative;
  height: 100%;
}
```

If problems persist, check parent **`overflow`**, flex or grid **shrink rules**, container **`position`**, and **CSP** rules that block the iframe.

## Best practices

<Accordion title="For callbacks">
  For callbacks, you should always implement the `onSubmit` callback. If you do not, dictation will often close immediately after the user acts.

  ```javascript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  onSubmit: ({ fieldId, text }) => {
    // Your code to handle the submitted text
  }
  ```
</Accordion>

<Accordion title="For layout">
  For layout, you should use a dedicated wrapper container instead of attaching directly to inputs.

  ```html theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  <div class="wrapper">
    <textarea id="clinical-notes"></textarea>
  </div>
  ```

  ```css theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  .wrapper {
    position: relative;
    height: 100%;
  }
  ```
</Accordion>

<Accordion title="For mode usage">
  For mode usage, you should use the `in-field` mode when dictation is tied to a specific text field or editor, and the `scratchpad` mode when dictation is not tied to a specific text field or editor.

  ```javascript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  mode: "in-field",
  ```

  ```javascript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  mode: "scratchpad",
  ```
</Accordion>

## Next steps

<Icon icon="file-lines" iconType="solid" /> Refer to the [Error handling](/dictation-sdk/guides/error-handling) guide for more details on common issues and how to troubleshoot them.