Build Dictation into a Chart Field

Use-case tutorial: Mount Dictation SDK in-field mode on a chart textarea in React with one shared DictationClient

What you will build

15 min | Intermediate

• One shared Dictation client for the chart screen.
• A clinical notes field with a stable field id.
• In-field Dictation that writes committed text back into that field.

Using an AI coding tool?

Copy the prompt below to point your agent at the Dictation skill and Documentation MCP. For every task skill, refer to AI coding tools.

Fetch the Dictation skill and connect the documentation MCP.

CopiedCopy promptOpen in Cursor

In this tutorial, you add Dictation SDK in-field mode to a chart note textarea in React. You create one DictationClient, wrap the screen with DictationProvider, and mount <Dictation> only while that field is active.

By the end of this tutorial, starting Dictation inserts text into your chart field through onSubmit.

The Dictation SDK is in beta. Confirm package versions and iframe requirements with your Suki contact before production use.

Prerequisites

Before you begin, make sure you have:

• Completed Partner onboarding.
• A React 18+ browser app that meets Dictation SDK prerequisites (CSP and iframe hosts).
• Staging partnerId and partnerToken values.

Reuse one client for the page. Creating a new DictationClient on every render tears the iframe down and makes the field feel unstable.

Architecture

Project setup

1. Use a React 18+ browser app that meets Dictation SDK prerequisites (CSP and iframe hosts).
2. Install the required dependencies:.

# pnpm
pnpm add @suki-sdk/core @suki-sdk/dictation @suki-sdk/dictation-react

# npm
npm install @suki-sdk/core @suki-sdk/dictation @suki-sdk/dictation-react

3. Configure your credentials:.

   • Keep staging partnerId and partnerToken ready.
   • Reuse one DictationClient for the page. Creating a new client on every render tears the iframe down.

Tutorial steps

Work through each step in order. Read the explanation, review the code example, then continue to the next step. The full code example is available in the accordion below.

1. Create One Auth Manager and DictationClient

   Build SukiAuthManager and DictationClient once inside useMemo. Do not create a new client per render or per field.

   Check: One DictationClient is created in useMemo and reused for the page.

   If it fails: Keep one DictationClient for the page. Creating a new client remounts the iframe and tears down the UI when the clinician types.

   import { useMemo } from "react";
   import { SukiAuthManager } from "@suki-sdk/core";
   import { DictationClient } from "@suki-sdk/dictation";
   
   function useChartDictationClient() {
   return useMemo(() => {
   const authManager = new SukiAuthManager({
     partnerId: "YOUR_PARTNER_ID",
     partnerToken: "YOUR_PARTNER_TOKEN",
     environment: "staging",
     loginOnInitialize: true,
     providerId: "YOUR_PROVIDER_ID", // Replace with your provider ID
     providerName: "Dr. Jane Smith", // Example only — replace with the provider's full name
     providerOrgId: "YOUR_ORG_ID",
   });
   return new DictationClient({ authManager });
   }, []);
   }
   
2. Wrap the Chart Screen with DictationProvider

   Pass the shared client into DictationProvider. Every <Dictation> must be a child of that provider.

   Check: Every <Dictation> is a child of DictationProvider with the shared client.

   import { DictationProvider } from "@suki-sdk/dictation-react";
   
   function ChartNoteScreen({ client }) {
   return (
   <DictationProvider client={client}>
     <ChartNoteField />
   </DictationProvider>
   );
   }
   
3. Dictate into a Chart Field in In-Field Mode

   Use a stable fieldId that matches your textarea id. Pass a wrapper with real height as rootElement. Mount <Dictation> only while that field should own the session. Update the field from onSubmit.

   Check: Starting Dictation commits text into the chart field through onSubmit, and fieldId matches the textarea id.

   If it fails: Confirm your host meets the Dictation SDK prerequisites, especially for iframe and CSP errors.

   import { useEffect, useRef, useState } from "react";
   import { Dictation } from "@suki-sdk/dictation-react";
   
   function ChartNoteField() {
   const dictationRootRef = useRef(null);
   const [dictationRoot, setDictationRoot] = useState(null);
   const [notes, setNotes] = useState("");
   const [dictationActive, setDictationActive] = useState(false);
   
   // Capture the wrapper DOM node for rootElement (stable height host for the iframe).
   useEffect(() => {
   setDictationRoot(dictationRootRef.current);
   }, []);
   
   return (
   <>
     <label htmlFor="clinical-notes">Clinical notes</label>
     {/* rootElement should be a wrapper with real height, not the textarea alone */}
     <div
       ref={dictationRootRef}
       id="clinical-notes-dictation-root"
       style={{ position: "relative", minHeight: 120 }}
     >
       <textarea
         id="clinical-notes"
         value={notes}
         onChange={(e) => setNotes(e.target.value)}
         rows={8}
       />
     </div>
     <button type="button" onClick={() => setDictationActive((v) => !v)}>
       {dictationActive ? "Stop" : "Start"}
     </button>
     {dictationActive && dictationRoot && (
       <Dictation
         fieldId="clinical-notes" // Example — must match the textarea id
         mode="in-field"
         rootElement={dictationRoot} // Recommended for in-field layout
         initialText={notes}
         onSubmit={({ text }) => {
           setNotes(text);
           setDictationActive(false);
         }}
         onCancel={() => setDictationActive(false)}
       />
     )}
   </>
   );
   }
   

Full code example

React

// Dictation SDK chart field tutorial (React, Beta)
// Copy this file into a React app, replace YOUR_* placeholders, then render <App />.
// Flow: DictationClient once → DictationProvider → in-field <Dictation> with rootElement + callbacks

import { useEffect, useMemo, useRef, useState } from "react";
import { SukiAuthManager } from "@suki-sdk/core";
import { DictationClient } from "@suki-sdk/dictation";
import { DictationProvider, Dictation } from "@suki-sdk/dictation-react";

function App() {
  return <ChartNoteWithDictation />;
}

function ChartNoteWithDictation() {
  // 1) Build auth + client once. Creating a new client per render tears down the iframe.
  const client = useMemo(() => {
    const authManager = new SukiAuthManager({
      partnerId: "YOUR_PARTNER_ID", // Required: from partner onboarding
      partnerToken: "YOUR_PARTNER_TOKEN", // Required
      environment: "staging", // "staging" | "production"
      loginOnInitialize: true,
      autoRegister: false, // Optional (default false); when true, provider fields below are often required
      providerId: "YOUR_PROVIDER_ID", // Replace with your provider ID
      providerName: "Dr. Jane Smith", // Example only — replace with the provider's full name
      providerOrgId: "YOUR_ORG_ID",
    });
    return new DictationClient({ authManager });
  }, []);

  const dictationRootRef = useRef(null);
  const [dictationRoot, setDictationRoot] = useState(null);
  const [notes, setNotes] = useState("");
  const [dictationActive, setDictationActive] = useState(false);

  // 2) Capture the wrapper DOM node so rootElement is ready before Dictation mounts.
  useEffect(() => {
    setDictationRoot(dictationRootRef.current);
  }, []);

  return (
    // 3) Every <Dictation> must sit under DictationProvider with the shared client.
    <DictationProvider client={client}>
      <label htmlFor="clinical-notes">Clinical notes</label>
      {/* 4) Wrapper layout: rootElement needs real width/height for the hosted iframe */}
      <div
        ref={dictationRootRef}
        id="clinical-notes-dictation-root"
        style={{ position: "relative", minHeight: 120 }}
      >
        <textarea
          id="clinical-notes" // Example field id — use any stable id; must match fieldId
          value={notes}
          onChange={(e) => setNotes(e.target.value)}
          rows={8}
        />
      </div>
      <button type="button" onClick={() => setDictationActive((v) => !v)}>
        {dictationActive ? "Stop dictation" : "Start dictation"}
      </button>
      {/* 5) Mount in-field dictation only while this field should own the session */}
      {dictationActive && dictationRoot && (
        <Dictation
          fieldId="clinical-notes" // Example — must match the textarea id above
          mode="in-field"
          rootElement={dictationRoot}
          initialText={notes} // Seed the session with current field text
          onSubmit={({ text }) => {
            // onSubmit is required for a good UX; commit transcript, then unmount
            setNotes(text);
            setDictationActive(false);
          }}
          onCancel={() => setDictationActive(false)}
          onDraft={({ text }) => {
            // Optional: persist unstaged text if the user leaves without submit
            console.log("Draft text:", text);
          }}
        />
      )}
    </DictationProvider>
  );
}

export default App;

Troubleshooting

Iframe / CSP Issues

Meet Dictation SDK prerequisites for allowed hosts.

UI Tears Down on Typing

Reuse one DictationClient for the page; recreating it remounts the iframe.

Beta Packaging

Confirm package versions with your Suki contact before production use.

Summary

In this tutorial, you:

• Created one shared DictationClient for the chart screen.
• Wrapped the screen with DictationProvider.
• Mounted in-field Dictation so submitted text updates the notes field.

Other tutorials

Continue with another end-to-end tutorial.