Form Filling Implementation In Web SDK For React

Start Form filling sessions in React with SukiAuthManager, FormFillingProvider, and the FormFilling component in Web SDK

This guide shows how to integrate Form filling capabilities into a browser-based React application with the Suki Web SDK. You will create the Auth Manager and Form filling Client (typically inside useMemo so they are not recreated on every render), wrap your component tree with the Form filling Provider, and render FormFilling when the clinician should fill forms.

Use this approach if you are building with React and want to manage Form filling through components and hooks instead of imperative calls.

Let’s get started!

Prerequisites

Before you start:

• Install @suki-sdk/react and @suki-sdk/core
• Get your partnerId from Partner onboarding. Pass a partnerToken (JWT from your identity provider) with that Partner ID to sign in.
• Decide which forms to fill: Suki Medical form templates (ask Suki support for the template IDs), your own form schema, or both. Refer to Dynamic Form filling.
• Have an encounter ID ready to pass as correlation_id.
• Run the app in a browser over HTTPS, with microphone access, and space for the Form filling UI.

For more setup detail, refer to Prerequisites.

Install the packages

Add the following packages to the same project you load in the browser:

pnpm

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

After you install, pull the SDK into your files with import, the same way as in the examples below. Use whatever approach your project already uses for other npm libraries. Import FormFillingClient, FormFillingProvider, FormFilling, and useFormFilling from @suki-sdk/react. You do not need @suki-sdk/form-filling-react.

Step 1: Style the container

React renders the hosted UI inside .suki-form-filling. Give that container explicit height, or the iframe looks blank.

CSS

.suki-form-filling {
  width: 100%;
  height: min(80vh, 720px);
  min-height: 400px;
}

Refer to Configuration for recommended CSS.

Step 2: Create auth manager

Now create the Auth Manager. You need your partnerId from Partner onboarding and a partnerToken (JWT from your identity provider).

In React you usually create the auth manager inside the same useMemo as the Form filling client (see Step 3), so both exist once per page or shell. The snippet below shows only the auth piece for clarity.

Code example for creating auth manager

JavaScript

import { SukiAuthManager } from "@suki-sdk/core";

const authManager = new SukiAuthManager({
  partnerId: "YOUR_PARTNER_ID", // replace with your partner ID - required
  partnerToken: "YOUR_PARTNER_TOKEN", // replace with your partner token - required
  environment: "staging", // optional: "staging" | "production"
  loginOnInitialize: true, // optional: sign in as soon as this runs
  autoRegister: false, // optional: enable provider auto-registration
  providerId: "YOUR_PROVIDER_ID", // optional: provider identifier in your system
  providerName: "YOUR_PROVIDER_NAME", // optional: full provider display name
  providerOrgId: "YOUR_PROVIDER_ORG_ID", // optional: organization identifier for the provider in your system
  providerSpecialty: "YOUR_PROVIDER_SPECIALTY", // optional: clinical specialty
});

Step 3: Create Form filling client

After you have created the auth manager, you can create the Form filling client for your application. The Form filling Client is the object the React components use under the hood.

Create one Form filling client and reuse it for the whole tree under FormFillingProvider. Use useMemo with an empty dependency array so you do not run new FormFillingClient(...) on every render.

Code example for creating Form filling client in React

React

import { useMemo } from "react";
import { SukiAuthManager } from "@suki-sdk/core";
import { FormFillingClient } from "@suki-sdk/react";

const client = useMemo(() => {
  const authManager = new SukiAuthManager({
    partnerId: "YOUR_PARTNER_ID", // replace with your partner ID - required
    partnerToken: "YOUR_PARTNER_TOKEN", // replace with your partner token - required
    environment: "staging", // optional: "staging" | "production"
    loginOnInitialize: true, // optional: sign in as soon as this runs
    autoRegister: false, // optional: enable provider auto-registration
    providerId: "YOUR_PROVIDER_ID", // optional: provider identifier in your system
    providerName: "YOUR_PROVIDER_NAME", // optional: full provider display name
    providerOrgId: "YOUR_PROVIDER_ORG_ID", // optional: organization identifier for the provider in your system
    providerSpecialty: "YOUR_PROVIDER_SPECIALTY", // optional: clinical specialty
  });
  return new FormFillingClient({
    authManager,
    onError: (err) => console.error(err.code, err.reason, err.message),
  });
}, []);

Step 4: Wrap with FormFillingProvider

Pass the client from Step 3 into FormFillingProvider. Every component that renders FormFilling must be a child of that provider.

Code example for wrapping with FormFillingProvider

React

import { FormFillingProvider } from "@suki-sdk/react";

export function App() {
  const client = useMemo(/* ... Step 3 ... */, []);

  return (
    <FormFillingProvider client={client}>
      {/* children that render <FormFilling /> */}
    </FormFillingProvider>
  );
}

You can put FormFillingProvider at app root or only around the screen that needs Form filling.

Step 5: Render FormFilling

Render FormFilling only while Form filling should be open (for example when the clinician clicked “Fill Forms with Suki”). When FormFilling unmounts, the SDK tears down the hosted UI for you.

Pass forms, onSubmit, and any optional props you need. In forms, use Suki template IDs, your own schema, or both. Refer to Configuration for the full option list.

Code example for rendering FormFilling in React

React

import { useState } from "react";
import { FormFilling } from "@suki-sdk/react";

function EncounterFormFilling({ encounterId }) {
  const [isFormOpen, setIsFormOpen] = useState(false);

  const handleSubmit = (result) => {
    for (const row of result.structured_data.generated_values ?? []) {
      // Dynamic: match row.partner_form_id === "partner-vitals-1" // New in v3.3.1
      // Static: match row.form_template_id or title
      console.log(row.partner_form_id, row.form_template_id, row.data);
    }
    setIsFormOpen(false);
  };

  return (
    <>
      <button
        type="button"
        onClick={() => setIsFormOpen(true)}
        disabled={isFormOpen}
      >
        Fill Forms with Suki
      </button>
      {isFormOpen && (
        <FormFilling
          correlation_id={encounterId}
          forms={[ // New in v3.3.1
            { form_template_id: "YOUR_TEMPLATE_ID" },
            {
              id: "partner-vitals-1",
              name: "Custom vitals",
              schema: {
                items: [
                  { id: "heart_rate", type: "int", question: "Heart rate?", unit: "bpm" },
                ],
              },
            },
          ]}
          onReady={() => console.log("Ready")}
          onSubmit={handleSubmit}
          onCancel={() => setIsFormOpen(false)}
          onBackgroundSubmit={handleSubmit}
        />
      )}
    </>
  );
}

You can also drive Form filling with a single isFormOpen boolean and mount one FormFilling when it is true, which scales cleanly across encounter screens.

onSubmit is required. It runs when structured JSON is ready after processing, not when the clinician taps submit in the hosted UI.

Each forms[] entry must use exactly one of form_template_id (Suki template) or schema (your form). You can mix both entry types in one session.

Callbacks

Props such as onReady, onSubmit, and onCancel mirror the JavaScript start() callbacks. onBackgroundSubmit is React-only (results for a superseded session while the iframe is still open). You can also listen with client.on() for handlers that stay active across many sessions:

React

client.on("form-filling:submitted", (result) => {
  console.log(result.ambient_session_id);
});

Refer to Callbacks for the FormFillingResult shape and Events for every event and payload.

useFormFilling hook

Inside FormFillingProvider, use useFormFilling() to read session state and errors in sibling components:

React

import { useFormFilling } from "@suki-sdk/react";

function FormFillingStatus() {
  const { isSessionActive, error } = useFormFilling();

  if (isSessionActive) {
    return <p>Form session active</p>;
  }
  if (error) {
    return (
      <p role="alert">
        Error ({error.code}): {error.message}
      </p>
    );
  }
  return null;
}

Starting another session

Use the same client and FormFillingProvider. Mount FormFilling again (for example set isFormOpen back to true). You do not need a new FormFillingClient. Mount only one FormFilling at a time per client.

Unmounting

When FormFilling unmounts, the SDK automatically tears down the hosted UI. You do not need to call stop() yourself for normal React flows.

Complete code example

Below is a complete code example in React with FormFillingProvider, a launch button, and one Form filling session.

React

import { useMemo, useState } from "react";
import { SukiAuthManager } from "@suki-sdk/core";
import {
  FormFillingClient,
  FormFillingProvider,
  FormFilling,
} from "@suki-sdk/react";

export function EncounterWithFormFilling({ encounterId }) {
  const client = useMemo(() => {
    const authManager = new SukiAuthManager({
      partnerId: "YOUR_PARTNER_ID", // replace with your partner ID - required
      partnerToken: "YOUR_PARTNER_TOKEN", // replace with your partner token - required
      environment: "staging", // optional: "staging" | "production"
      loginOnInitialize: true, // optional: sign in as soon as this runs
      autoRegister: false, // optional: enable provider auto-registration
      providerId: "YOUR_PROVIDER_ID", // optional: provider identifier in your system
      providerName: "YOUR_PROVIDER_NAME", // optional: full provider display name
      providerOrgId: "YOUR_PROVIDER_ORG_ID", // optional: organization identifier for the provider in your system
      providerSpecialty: "YOUR_PROVIDER_SPECIALTY", // optional: clinical specialty
    });
    return new FormFillingClient({
      authManager,
      onError: (err) => console.error(err.code, err.message),
    });
  }, []);

  const [isFormOpen, setIsFormOpen] = useState(false);

  const handleSubmit = (result) => {
    for (const row of result.structured_data.generated_values ?? []) {
      console.log(row.partner_form_id, row.form_template_id, row.data); // New in v3.3.1
    }
    setIsFormOpen(false);
  };

  return (
    <FormFillingProvider client={client}>
      <h1>Encounter {encounterId}</h1>
      <button
        type="button"
        onClick={() => setIsFormOpen(true)}
        disabled={isFormOpen}
      >
        Fill Forms with Suki
      </button>
      {isFormOpen && (
        <FormFilling
          correlation_id={encounterId}
          forms={[ // New in v3.3.1
            { form_template_id: "YOUR_TEMPLATE_ID" },
            {
              id: "partner-vitals-1",
              name: "Custom vitals",
              schema: {
                items: [
                  { id: "heart_rate", type: "int", question: "Heart rate?", unit: "bpm" },
                ],
              },
            },
          ]}
          onReady={() => console.log("Ready")}
          onSubmit={handleSubmit}
          onCancel={() => setIsFormOpen(false)}
          onBackgroundSubmit={handleSubmit}
        />
      )}
    </FormFillingProvider>
  );
}

Your integration is working when turning Form filling on shows the hosted UI, onSubmit returns structured_data, and only one FormFilling is mounted at a time for that client.

Best practices

• Reuse one Form filling client. Build a single FormFillingClient inside useMemo (or equivalent) for the page or shell. Creating a new client on every render breaks that pattern and often resets the hosted UI.

• Reuse one auth manager. Create SukiAuthManager once inside the same useMemo as the client, as in the steps above.

• Pass templates, your schema, or both in forms. Use form_template_id for Suki Medical form templates and schema for your own forms. Keep template IDs unique, and keep dynamic id values unique.

• Handle when structured results arrive. You must pass onSubmit so the SDK can deliver structured_data. For dynamic forms, map by partner_form_id (and/or name), not list index.

• Pass correlation_id. Use your encounter ID so callbacks and Partner webhooks match the correct record.

• Use onBackgroundSubmit when results arrive for a session the clinician has already replaced or reopened.

• One active FormFilling at a time. Use boolean state so you do not mount multiple Form filling UIs against the same client at once.

• Give the Form filling host real height. Style .suki-form-filling with height you control. Otherwise the Form filling area can look blank.

• Rely on unmount for teardown. Removing FormFilling is the normal way to close the UI; you usually do not call stop() yourself in React.

Next steps

Configuration - forms, correlation_id, and callbacks.

Dynamic Form filling - XOR rules, schema shapes, and mixed sessions.

JavaScript integration - Integrate Form filling in a plain JavaScript application using the Suki Web SDK.