Form Filling SDK React Integration

This guide walks you through integrating the Form filling SDK in a React 18+ application. You create SukiAuthManager and FormFillingClient once inside useMemo, wrap your tree with FormFillingProvider, and render <FormFilling> when the clinician opens Form filling.

Prerequisites

Before you begin, confirm you have:

Packages: @suki-sdk/form-filling-react and @suki-sdk/core
Partner credentials: partnerId and partnerToken from Partner onboarding
Template IDs: template_id UUIDs from your Suki support team for form_template_ids.
Encounter ID: pass your encounter ID as correlation_id, refer to Configuration for more details.
Browser and layout: HTTPS, microphone access, and space for the Form filling UI (the .suki-form-filling container needs height)

Refer to Prerequisites for webhooks and CSP.

Integration pattern

Create auth and the client once per page inside useMemo. Mount <FormFilling> only when the clinician is ready to open Form filling.

Suki Auth Manager

One SukiAuthManager after the partner token is available.

Form Filling Client

One FormFillingClient in useMemo. Reuse it for every session on that page.

FormFillingProvider

Wrap the part of your tree that renders <FormFilling>.

Conditional FormFilling

Mount <FormFilling> only while Form filling should be open.

Do not run new FormFillingClient(...) on every render. Use useMemo with stable dependencies.

Install the packages

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

npm install @suki-sdk/form-filling-react @suki-sdk/core

yarn add @suki-sdk/form-filling-react @suki-sdk/core

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 and client in useMemo

Create both objects once per page inside useMemo. Optionally wire onError on the client for configuration and runtime errors.

React

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

export function EncounterPage({ encounterId }: { encounterId: string }) {
  const client = useMemo(() => {
    const authManager = new SukiAuthManager({
      partnerId: "YOUR_PARTNER_ID", // Required
      partnerToken: "YOUR_PARTNER_TOKEN", // Required
      environment: "staging", // Optional
      loginOnInitialize: true, // Optional
      autoRegister: false, // optional (default true); when true, provider fields below are often required
      providerId: "YOUR_PROVIDER_ID", // Optional
      providerName: "Dr. Jane Smith", // Optional
    });
    return new FormFillingClient({
      authManager, // Required
      onError: (err) => console.error(err.code, err.reason, err.message), // Optional
    });
  }, []);

  // Steps 3–4 below
}

Refer to Authentication for provider fields and other sign-in options.

Step 3: Wrap with FormFillingProvider

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

React

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

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

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

Step 4: Render FormFilling when the clinician opens Form filling

Use state (for example isFormOpen) so <FormFilling> mounts only while Form filling should be visible. When it unmounts, the SDK tears down the hosted UI. Pass the same session fields you would pass to client.start(), except rootElement (React supplies the container):

form_template_ids: Required template_id UUIDs from your Suki support team.
correlation_id: Optional Your encounter or appointment ID. Strongly recommended so results map to the correct record.
onSubmit: Required Called when structured JSON is ready after processing, not when the clinician taps submit. Receives a FormFillingResult.
onReady, onCancel: Optional
onBackgroundSubmit: Optional React only. Results for a superseded session while the iframe is still open.

React

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

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

  const handleSubmit = (result) => {
    for (const form of result.structured_data.generated_values) {
      console.log(form.form_template_id, form.data);
    }
    setIsFormOpen(false);
  };

  return (
    <>
      <button type="button" onClick={() => setIsFormOpen(true)} disabled={isFormOpen}>
        Fill Forms with Suki
      </button>

      {isFormOpen && (
        <FormFilling
          form_template_ids={["YOUR_TEMPLATE_ID"]} // Required
          correlation_id={encounterId} // Optional
          onReady={() => console.log("Ready")} // Optional
          onSubmit={handleSubmit} // Required
          onCancel={() => setIsFormOpen(false)} // Optional
          onBackgroundSubmit={handleSubmit} // Optional
        />
      )}
    </>
  );
}

Callbacks and events

Your app needs to know when Form filling is ready, when structured results arrive, and when the clinician cancels. You can handle that in two ways. Option 1: Pass props on <FormFilling> Use this for logic tied to one session. Props mirror client.start() callbacks:

Prop	When it runs
`onReady`	The hosted UI loaded and is ready for the clinician
`onSubmit`	Structured JSON is ready after processing (map this to your EHR or show results in your app)
`onCancel`	The clinician left without submitting
`onBackgroundSubmit`	Results for a superseded session while the iframe is still open (React only)

Option 2: Listen with client.on() Use this for handlers that stay active across many sessions, such as logging, analytics, or a shared error handler. Register once when you create the client in useMemo:

React

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

Common events include form-filling:session-started, form-filling:background-submitted, and form-filling:error. Refer to Callbacks for FormFillingResult shape and Events for every event and payload.

Starting another session

When the clinician opens Form filling again, 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.

useFormFilling hook

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

React

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

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

  // Prefer session state. The provider keeps the last error until the next
  // form-filling:error, so do not return early on error alone after a retry.
  if (isSessionActive) {
    return <p>Form session active</p>;
  }
  if (error) {
    return <p role="alert">Error ({error.code}): {error.message}</p>;
  }
  return null;
}

Complete code example

Below is a full page example: sign-in, client setup in useMemo, provider wiring, and a button that opens Form filling.

React

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

export function EncounterPage({ encounterId }: { encounterId: string }) {
  const client = useMemo(() => {
    const authManager = new SukiAuthManager({
      partnerId: "YOUR_PARTNER_ID", // Required
      partnerToken: "YOUR_PARTNER_TOKEN", // Required
      environment: "staging", // Optional
      loginOnInitialize: true, // Optional
      autoRegister: false, // optional (default true); when true, providerName and providerOrgId are often required
    });
    return new FormFillingClient({
      authManager, // Required
      onError: (err) => console.error(err.code, err.message), // Optional
    });
  }, []);

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

  const handleSubmit = (result) => {
    for (const form of result.structured_data.generated_values) {
      console.log(form.form_template_id, form.data);
    }
    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
          form_template_ids={["YOUR_TEMPLATE_ID"]} // Required
          correlation_id={encounterId} // Optional
          onReady={() => console.log("Ready")} // Optional
          onSubmit={handleSubmit} // Required
          onCancel={() => setIsFormOpen(false)} // Optional
          onBackgroundSubmit={handleSubmit} // Optional
        />
      )}
    </FormFillingProvider>
  );
}

Your integration works when the Form filling UI appears, the microphone is active, and onSubmit returns structured_data.

Best practices

Reuse one client in useMemo. Do not create FormFillingClient on every render.
Mount one <FormFilling> at a time per client.
Pass onSubmit. It is required. Map structured_data.generated_values to your EHR or backend.
Pass correlation_id. Use your encounter ID so callbacks and webhooks match the correct record.
Use onBackgroundSubmit when results arrive for a session the clinician has already replaced or reopened.
Register a partner webhook for production saves on your server, not browser onSubmit alone.
Style .suki-form-filling with height before the UI mounts. Zero height is the most common cause of a blank UI.
Use template IDs from Suki support. The SDK validates IDs when <FormFilling> mounts and drops unsupported values.

Troubleshooting

Blank Form Filling Area

Set CSS height on .suki-form-filling. Add CSP frame-src for https://sdk.suki.ai (production) or https://sdk.suki-stage.com (staging). Refer to Configuration and Prerequisites.

Session Resets or Flickers

Do not create FormFillingClient on every render. Keep one client in useMemo and pass the same instance to FormFillingProvider.

Multiple Sessions Conflict

Mount only one <FormFilling> at a time per client. Unmount the previous session before starting another.

`SUKI_FF_001` Immediately

form_template_ids is empty, or no IDs match your partner account. Pass at least one template_id UUID from Suki support. Refer to Form filling templates.

`SUKI_FF_002` Handshake Timeout

The iframe did not complete the ready handshake within 10 seconds. Check network, ad blockers, and CSP. Confirm the page uses HTTPS.

`SUKI_FF_003` Fetch Templates Failed

Auth failed or the wrong environment (staging vs production) while loading the template list. Retry and confirm partnerId, partnerToken, and environment.

`SUKI_FF_004` Iframe Runtime Error

Microphone permission denied, session start/submit failed, or form generation failed. Read err.message, show a retry option, and confirm network access.

UI Never Opens

Sign-in failed before the hosted UI loads. Verify partnerId and partnerToken for your environment. Refer to Authentication.

No `onSubmit` Callback

The clinician closed the processing screen early, or the tab closed before processing finished. Register a partner webhook for server-side delivery.

`onSubmit` Never Maps to Your Encounter

Pass your encounter ID as correlation_id at session start so callbacks and webhooks match the correct record.

Late Results After Offline Submit

Handle onBackgroundSubmit on <FormFilling> or listen for form-filling:background-submitted on the client.

Log Errors During Development

Wire onError on the client, useFormFilling() error, or client.on("form-filling:error", ...):

React

client.on("form-filling:error", (err) => {
  console.error(err.code, err.reason, err.message);
});

Refer to Error handling for the full error code table.

Next steps

Basic usage example for a fuller sample with useFormFilling Session workflow for single-form vs multi-form behavior Configuration for all <FormFilling> props Javascript integration for plain JavaScript

Get Started

Integration Guides

Concepts & Feature Guides

API Reference

Resources

Form Filling SDK React Integration

Prerequisites

Integration pattern

Suki Auth Manager

Form Filling Client

FormFillingProvider

Conditional FormFilling

Install the packages

Step 1: Style the container

Step 2: Create auth manager and client in useMemo

Step 3: Wrap with FormFillingProvider

Step 4: Render FormFilling when the clinician opens Form filling

Callbacks and events

Starting another session

useFormFilling hook

Complete code example

Best practices

Troubleshooting

Next steps

​Prerequisites

​Integration pattern

Suki Auth Manager

Form Filling Client

FormFillingProvider

Conditional FormFilling

​Install the packages

​Step 1: Style the container

​Step 2: Create auth manager and client in useMemo

​Step 3: Wrap with FormFillingProvider

​Step 4: Render FormFilling when the clinician opens Form filling

​Callbacks and events

​Starting another session

​useFormFilling hook

​Complete code example

​Best practices

​Troubleshooting

​Next steps

Prerequisites

Integration pattern

Install the packages

Step 1: Style the container

Step 2: Create auth manager and client in useMemo

Step 3: Wrap with FormFillingProvider

Step 4: Render FormFilling when the clinician opens Form filling

Callbacks and events

Starting another session

useFormFilling hook

Complete code example

Best practices

Troubleshooting

Next steps