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

# Content Rewrite

> Rewrite selected Dictation text with Concise, Verbose, or Patient Friendly in the hosted Dictation UI without changing ShowOptions or callbacks

export const QuickSummary = ({title = "Quick summary", updated, children}) => <div className="quick-summary-wrapper">
    <div className="quick-summary-header">
      <span className="quick-summary-icon" aria-hidden="true" />
      <span className="quick-summary-title">{title}</span>
    </div>
    <div className="quick-summary-content">{children}</div>
    {updated ? <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">{updated}</span>
      </div> : null}
  </div>;

<QuickSummary updated="October 2026">
  Content Rewrite is built into Suki's hosted Dictation experience. Clinicians can select text in the Dictation editor, choose **Concise**, **Verbose**, or **Patient Friendly**, and replace that selection in place. You keep the same `show()` options and the same `onSubmit`, `onDraft`, and `onCancel` callbacks. There is no new SDK method and no rewrite-specific handler to wire.
</QuickSummary>

**Content Rewrite** lets clinicians rewrite selected text in the hosted Dictation iframe before they submit.

It is available in the Dictation SDK (`@suki-sdk/dictation` and `@suki-sdk/dictation-react`) and in Web SDK Dictation, which uses `DictationClient` from `@suki-sdk/js` and `@suki-sdk/react`. It works in both [In-field mode](/dictation-sdk/guides/in-field-mode) and [Scratchpad mode](/dictation-sdk/guides/scratchpad-mode).

Content Rewrite runs entirely in the hosted iframe. You do not send a rewrite API call, handle selection offsets, or apply the rewritten span. When a clinician selects text with the microphone off, the iframe shows the rewrite tooltip, sends the request, and applies the result. Your existing `onSubmit` and `onDraft` callbacks receive the updated field text.

<Note>
  No additional package, `ShowOptions` field, or callback is required.
</Note>

Use `@suki-sdk/dictation` or `@suki-sdk/dictation-react` **v0.1.0-beta.3** or later. For Web SDK Dictation, use the matching release from the same release train. If Dictation is already integrated, you do not install another package.

<Warning>
  Content Rewrite requires backend enablement for your organization. You do not configure it in the SDK. If it is not enabled, the rewrite request fails and the UI shows an error. Confirm with Suki that it is enabled before you test with clinicians.
</Warning>

## Common use cases

<CardGroup cols={2}>
  <Card title="Shorten Long Dictation" icon="compress">
    After dictating into a note or form field, the clinician selects a long span, chooses **Concise**, and keeps documenting in the same session.
  </Card>

  <Card title="Expand Short Notes" icon="expand">
    The clinician selects brief wording, chooses **Verbose**, and replaces that span in the Dictation editor without starting another session.
  </Card>

  <Card title="Write for Patients" icon="user">
    The clinician selects clinical wording, chooses **Patient Friendly**, and reviews the rewritten span in the hosted UI before they submit.
  </Card>

  <Card title="Rewrite in a Target Field" icon="input-text">
    Use in-field mode so the clinician dictates into a chart field, then rewrites part of that field with the microphone off.
  </Card>

  <Card title="Rewrite in a Scratchpad" icon="window">
    Use scratchpad mode so the clinician drafts in the floating panel, rewrites selected text there, then submits the full scratchpad text to your app.
  </Card>

  <Card title="Same Experience in Web SDK Dictation" icon="browser">
    Web SDK Dictation uses the same hosted iframe, so clinicians get the same rewrite tooltip and styles when Dictation is already in your Web SDK app.
  </Card>
</CardGroup>

## How clinicians use Content Rewrite

The rewrite happens in the Dictation iframe. Your app still receives the full field text through the callbacks you already register.

<Steps>
  <Step title="Open Dictation">
    The clinician opens Dictation in in-field or scratchpad mode the same way they do today.
  </Step>

  <Step title="Turn Off the Microphone and Select Text">
    The clinician turns the microphone off, then selects the text they want to change. While the microphone is streaming, the rewrite tooltip stays hidden. The tooltip appears only when the selection has at least two words.
  </Step>

  <Step title="Choose a Rewrite Style">
    From the rewrite tooltip, the clinician chooses **Concise**, **Verbose**, or **Patient Friendly**. The hosted iframe sends the rewrite request. The UI shows **Rewriting…**. The clinician can select **Cancel** while the rewrite runs. Your app does not handle that HTTP call.
  </Step>

  <Step title="Replace the Selection or Retry">
    On success, Suki replaces only the selected span. The rest of the field stays as it is. If the rewrite fails, the UI shows **Rewrite failed. Please try again.** with **Try again** and **Cancel**. The SDK does not retry on its own.
  </Step>

  <Step title="Submit the Field">
    When the clinician submits, `onSubmit` receives `{ fieldId, text }` for the full field value, including any rewritten spans. Optional `onDraft` works the same way for unfinished text.
  </Step>
</Steps>

```mermaid actions={false} theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFF394','primaryTextColor':'#111827','primaryBorderColor':'#FFE148','lineColor':'#6B7280','fontSize':'14px','edgeLabelBackground':'#FFFADE','clusterBkg':'#FFFADE','clusterBorder':'#FFE148'}}}%%
flowchart TD
    subgraph iframe["Hosted Dictation iframe"]
        A[Turn the microphone off] --> B[Select at least two words]
        B --> C[Choose Concise, Verbose, or Patient Friendly]
        C --> D{Rewrite succeeds?}
        D -->|Yes| E[Replace only the selected span]
        D -->|No| F[Try again or Cancel]
        F --> C
        E --> G[Submit the field]
    end

    G --> H[onSubmit or onDraft receives the full field]

    style A fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style B fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style C fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style D fill:#FFFADE,stroke:#FFE148,stroke-width:2px,color:#111827
    style E fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style F fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style G fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style H fill:#FFE148,stroke:#111827,stroke-width:2px,color:#111827
    style iframe fill:#FFFADE,stroke:#FFE148,stroke-width:2px,color:#111827
```

## ShowOptions and callbacks

Content Rewrite does not change the `ShowOptions` contract. Pass the same options you pass for any Dictation session.

| Option | Required | What changes with Content Rewrite |
| - | - | - |
| [`mode`](/dictation-sdk/guides/configuration#showoptions) | Required | [`"in-field"`](/dictation-sdk/guides/in-field-mode) or [`"scratchpad"`](/dictation-sdk/guides/scratchpad-mode) |
| [`fieldId`](/dictation-sdk/guides/configuration#field-ids-in-practice) | Required | Echoed on every callback |
| [`rootElement`](/dictation-sdk/guides/configuration#wrapper-layout) | Required in JavaScript to show Dictation | Host for the iframe. The React `<Dictation>` component provides its own container |
| [`initialText`](/dictation-sdk/guides/configuration#showoptions) | Optional | Starting editor text |
| [`onSubmit`](/dictation-sdk/guides/callbacks#supported-callbacks) | Required | Receives `{ fieldId, text }`. `text` includes any rewritten text |
| [`onCancel`](/dictation-sdk/guides/callbacks#supported-callbacks) | Optional | Unchanged |
| [`onDraft`](/dictation-sdk/guides/callbacks#supported-callbacks) | Optional | Unchanged. Draft text includes any rewritten text |

<Tip>
  Keep the `onSubmit`, `onDraft`, and `onCancel` callbacks you already register. Content Rewrite does not add a flag on `show()` or a rewrite-specific handler. The updated field text still arrives through those same callbacks.
</Tip>

<Note>
  Content Rewrite also does not support custom rewrite instructions from your app, and it does not run while the microphone is streaming.
</Note>

## Code examples

The following JavaScript and React code examples use the same Dictation setup you already have. When a clinician rewrites text in the iframe, `onSubmit` and `onDraft` receive the updated field text.

This section has JavaScript and React tabs. Both use the same ShowOptions and callbacks. Content Rewrite adds no options or callbacks in either.

<Tabs>
  <Tab title="JavaScript">
    Pass your usual options to `DictationClient.show()`. Web SDK Dictation uses the same call with `DictationClient` from `@suki-sdk/js`.

    ```javascript JavaScript expandable theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
    import { SukiAuthManager } from "@suki-sdk/core";
    import { DictationClient } from "@suki-sdk/dictation";

    const authManager = new SukiAuthManager({
      partnerId: "YOUR_PARTNER_ID",
      partnerToken: "YOUR_PARTNER_TOKEN",
      environment: "staging",
      providerId: "YOUR_PROVIDER_ID",
    });

    const dictationClient = new DictationClient({ authManager });

    await dictationClient.show({
      mode: "in-field",
      fieldId: "soap.assessment",
      rootElement: document.getElementById("dictation-root"),
      initialText: existingAssessmentText,
      onSubmit: ({ fieldId, text }) => {
        // text is the full field value, including any Content Rewrite edits
        saveField(fieldId, text);
      },
      onDraft: ({ fieldId, text }) => {
        // Optional: save unfinished text, including rewritten text, for the next show()
        cacheDraft(fieldId, text);
      },
      onCancel: ({ fieldId }) => {
        clearDraft(fieldId);
      },
    });
    ```
  </Tab>

  <Tab title="React">
    Pass your usual props to `<Dictation>`. Web SDK Dictation uses the same component from `@suki-sdk/react`.

    ```jsx React expandable theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
    import { useMemo, useState } from "react";
    import { SukiAuthManager } from "@suki-sdk/core";
    import { DictationClient } from "@suki-sdk/dictation";
    import { Dictation, DictationProvider } from "@suki-sdk/dictation-react";

    const authManager = new SukiAuthManager({
      partnerId: "YOUR_PARTNER_ID",
      partnerToken: "YOUR_PARTNER_TOKEN",
      environment: "staging",
      providerId: "YOUR_PROVIDER_ID",
    });

    function AssessmentField() {
      const client = useMemo(() => new DictationClient({ authManager }), []);
      const [text, setText] = useState("");
      const [open, setOpen] = useState(false);

      return (
        <DictationProvider client={client}>
          <textarea value={text} onChange={(e) => setText(e.target.value)} />
          <button type="button" onClick={() => setOpen(true)}>
            Dictate
          </button>

          {open && (
            <Dictation
              mode="in-field"
              fieldId="soap.assessment"
              initialText={text}
              onSubmit={({ text: next }) => {
                // next includes any Content Rewrite edits from the hosted UI
                setText(next);
                setOpen(false);
              }}
              onCancel={() => setOpen(false)}
              onDraft={({ text: draft }) => setText(draft)}
            />
          )}
        </DictationProvider>
      );
    }
    ```
  </Tab>
</Tabs>

### Scratchpad mode

Content Rewrite works the same way in scratchpad mode. The clinician turns off the microphone, selects text, and rewrites it in the hosted UI. The final text still arrives on `onSubmit`.

```javascript JavaScript theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
await dictationClient.show({
  mode: "scratchpad",
  fieldId: "scratchpad",
  rootElement: document.getElementById("scratchpad-root"),
  onSubmit: ({ text }) => {
    insertIntoFocusedField(text);
  },
});
```

## Best practices

<Tip>
  * Confirm with Suki that Content Rewrite is enabled for your partner before you test with clinicians. The tooltip can still appear; the rewrite call fails if enablement is off.

  * Keep your existing `onSubmit`, `onDraft`, and `onCancel` handlers. Do not add `enableRewrite`, `onRewrite`, or custom rewrite instructions. Content Rewrite does not add `ShowOptions` fields.

  * Treat the text on `onSubmit` and `onDraft` as the full field, including any rewritten spans. The iframe applies the selection. Your app does not patch offsets.

  * Rewrite requires the microphone off and a selection of at least two words. While the microphone is streaming, the tooltip stays hidden.

  * If rewrite fails, the clinician retries from the hosted UI. The SDK does not retry on its own.

  * If you ship both modes, verify Content Rewrite in in-field and scratchpad. The clinician flow is the same in both.
</Tip>

## Next steps

<Icon icon="file-lines" iconType="solid" /> **[Callbacks](/dictation-sdk/guides/callbacks)** - `onSubmit`, `onCancel`, and `onDraft` payload shape.

<Icon icon="file-lines" iconType="solid" /> **[Configuration](/dictation-sdk/guides/configuration)** - Every `ShowOptions` field.

<Icon icon="file-lines" iconType="solid" /> **[In-field mode](/dictation-sdk/guides/in-field-mode)** - Attach Dictation to a single field.

<Icon icon="file-lines" iconType="solid" /> **[Scratchpad mode](/dictation-sdk/guides/scratchpad-mode)** - Run Dictation in a floating panel.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.