Form Filling SDK Basic Usage

Build a React encounter page with FormFillingClient, FormFillingProvider, onSubmit handling, and useFormFilling session status

This example shows how to create a React encounter page that integrates the Form filling SDK. The clinician starts Form filling from a button, completes the assessment, and your app receives the structured results in the onSubmit callback.

The example creates a FormFillingClient with useMemo, wraps the app with FormFillingProvider, and renders FormFilling only while a session is active. A sibling component uses useFormFilling() to track the session state and error without letting a stale error hide an active session.

React

import { useMemo, useState } from "react";
import { SukiAuthManager } from "@suki-sdk/core";
import {
  FormFillingClient,
  FormFillingProvider,
  FormFilling,
  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: speak to fill fields.</p>;
  }

  if (error) {
    return (
      <p role="alert">
        Form filling error ({error.code}): {error.message}
      </p>
    );
  }

  return null;
}

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

  const [showForms, setShowForms] = useState(false);

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

  return (
    <FormFillingProvider client={client}>
      <h1>Encounter {encounterId}</h1>
      <FormFillingStatus />
      <button type="button" onClick={() => setShowForms(true)} disabled={showForms}>
        Start Form filling
      </button>
      {showForms && (
        <FormFilling
          forms={[{ form_template_id: "YOUR_TEMPLATE_ID_A" }, { form_template_id: "YOUR_TEMPLATE_ID_B" }]}
          correlation_id={encounterId}
          onSubmit={handleSubmit}
          onCancel={() => setShowForms(false)}
          onBackgroundSubmit={handleSubmit}
        />
      )}
    </FormFillingProvider>
  );
}

Pass one form_template_id to skip the selection screen. Pass two or more to show multi-form selection. Refer to Session workflow for more details.

Next steps

Configuration examples - Minimal auth and client setup.

EHR handoff - Map structured_data to your EHR.

FormFillingClient - useFormFilling() return values.