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

# Migrating To Web SDK v2

> Complete guide to migrate from Suki.js v1 to v2 with enhanced provider onboarding, LOINC standardization, and improved UI customization

<Warning>
  We will remove this guide in future updates. If you are still on v1.x, complete your migration to `v2.0.0` first before you migrate to `v3.0.0`.
</Warning>

<div className="quick-summary-wrapper">
  <div className="quick-summary-header">
    <span className="quick-summary-icon" aria-hidden="true" />

    <span className="quick-summary-title">Quick summary</span>
  </div>

  <div className="quick-summary-content">
    The `v2.0.0` release adds new features and changes that enhance clinical documentation workflows.

    <br />

    <br />

    <Danger>
      The new version introduces breaking changes that require immediate attention.

      Refer to [Breaking changes reference](/web-sdk/product-updates/migration-to-v2#breaking-changes-reference) for more information.
    </Danger>

    <table>
      <thead>
        <tr>
          <th>Change Category</th>
          <th>Details</th>
          <th>Migration Impact</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><strong>Required Provider Information</strong></td>
          <td>Two new required fields:<br />• <code>providerName</code> (string): The full name of the healthcare provider using the SDK<br />• <code>providerOrgId</code> (string): The unique identifier of the healthcare organization</td>
          <td>These fields enable automatic provider onboarding in the Suki system without manual registration. Add both fields to your initialization configuration.</td>
        </tr>

        <tr>
          <td><strong>Ambient Options Restructure</strong></td>
          <td><strong>Deprecated</strong>: <code>prefill.noteTypeIds</code> approach (is removed from `v2.1.1` and is no longer supported)<br /><strong>New</strong>: <code>sections</code> array using LOINC codes for standardized note sections</td>
          <td>You must migrate from <code>noteTypeIds</code> to LOINC-based section configurations. The <code>prefill.noteTypeIds</code> approach is deprecated and will be removed in future versions.</td>
        </tr>

        <tr>
          <td><strong>Theme Configuration Changes</strong></td>
          <td><strong>Renamed</strong>: <code>primaryColor</code> → <code>primary</code><br /><strong>New properties</strong>: <code>background</code>, <code>secondaryBackground</code>, <code>foreground</code>, <code>warning</code></td>
          <td>Update all <code>primaryColor</code> references to <code>primary</code> in your theme configuration. New properties are optional but recommended for better visual control.</td>
        </tr>

        <tr>
          <td><strong>Mount Configuration</strong></td>
          <td><code>ambientOptions</code> parameter is now required when mounting the SDK. You must provide at least one section defined using LOINC codes.</td>
          <td>Previously optional in v1.x, now required in v2.0. You must provide <code>ambientOptions</code> with at least one section defined using LOINC codes when calling <code>mount()</code>.</td>
        </tr>
      </tbody>
    </table>
  </div>

  <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">June 2026</span>
  </div>
</div>

The v2.0.0 release of Suki.js includes significant improvements that enhance clinical documentation workflows and standardize healthcare integrations. This guide provides step-by-step instructions to migrate your integration from v1.x to v2.0.

### Improvements

The `v2.0.0` release adds new features and changes that enhance clinical documentation workflows. Key improvements include:

* Automatic provider registration
* Standardized LOINC codes for note sections
* Expanded theme customization options
* Improved section editing with dictation copy capabilities
* Enhanced error handling with better validation and reporting

## Migration steps

Follow these steps in order to migrate your integration from v1.x to v2.0.

### Step 1: Update package version

Update to the latest version of the Suki SDK:

<View title="JavaScript" icon="js">
  <CodeGroup>
    ```shell pnpm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    pnpm add @suki-sdk/js@latest
    ```

    ```shell npm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    npm install @suki-sdk/js@latest
    ```

    ```shell yarn theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    yarn add @suki-sdk/js@latest
    ```
  </CodeGroup>
</View>

<View title="React" icon="react">
  <CodeGroup>
    ```shell pnpm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    pnpm add @suki-sdk/react@latest
    ```

    ```shell npm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    npm install @suki-sdk/react@latest
    ```

    ```shell yarn theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    yarn add @suki-sdk/react@latest
    ```
  </CodeGroup>
</View>

### Step 2: Update provider initialization

Add the required provider information to your initialization configuration. The initialization process now requires additional provider information for automatic onboarding.

<View title="JavaScript" icon="js">
  #### Before (v1.x)

  ```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import { initialize } from "@suki-sdk/js";

  const sdkClient = initialize({
    partnerId: "your-partner-id",
    partnerToken: "your-token",
    enableDebug: true,
    theme: {
      primaryColor: "#4287f5",
    },
  });
  ```

  #### After (v2.0)

  ```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import { initialize } from "@suki-sdk/js";

  const sdkClient = initialize({
    // Required partner details
    partnerId: "your-partner-id",
    partnerToken: "your-token",
    providerName: "Dr. John Q. Doe", // NEW: Required
    providerOrgId: "organization-id", // NEW: Required

    // Optional fields
    providerSpecialty: "FAMILY_MEDICINE", // NEW: Optional
    enableDebug: true,
    logLevel: "info", // NEW: Optional
    isTestMode: false, // NEW: Optional
    theme: {
      primary: "#4287f5", // CHANGED: renamed from primaryColor
      background: "#ffffff", // NEW: Optional
      secondaryBackground: "#f5f5f5", // NEW: Optional
      foreground: "#333333", // NEW: Optional
      warning: "#ff9900", // NEW: Optional
    },
  });
  ```
</View>

<View title="React" icon="react">
  #### Before (v1.x)

  ```jsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import { SukiProvider, useSuki } from "@suki-sdk/react";

  const initOptions = {
    partnerId: "your-partner-id",
    partnerToken: "your-token",
    enableDebug: true,
    theme: {
      primaryColor: "#4287f5",
    },
  };

  function App() {
    const { init, isInitialized } = useSuki();

    useEffect(() => {
      if (!isInitialized) {
        init(initOptions);
      }
    }, [init, isInitialized]);

    return <div>Your app content</div>;
  }
  ```

  #### After (v2.0)

  ```jsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import { SukiProvider, useSuki } from "@suki-sdk/react";

  const initOptions = {
    // Required partner details
    partnerId: "your-partner-id",
    partnerToken: "your-token",
    providerName: "Dr. John Q. Doe", // NEW: Required
    providerOrgId: "organization-id", // NEW: Required

    // Optional fields
    providerSpecialty: "FAMILY_MEDICINE", // NEW: Optional
    enableDebug: true,
    logLevel: "info", // NEW: Optional
    isTestMode: false, // NEW: Optional
    theme: {
      primary: "#4287f5", // CHANGED: renamed from primaryColor
      background: "#ffffff", // NEW: Optional
      secondaryBackground: "#f5f5f5", // NEW: Optional
      foreground: "#333333", // NEW: Optional
      warning: "#ff9900", // NEW: Optional
    },
  };

  function App() {
    const { init, isInitialized } = useSuki();

    useEffect(() => {
      if (!isInitialized) {
        init(initOptions);
      }
    }, [init, isInitialized]);

    return <div>Your app content</div>;
  }
  ```
</View>

#### New required fields explained

<AccordionGroup>
  <Accordion title="providerName (Required)" icon="user">
    The full name of the healthcare provider using the SDK, including first name, middle name (if applicable), and last name separated by spaces.

    This information enables automatic provider onboarding in the Suki system without manual registration.

    **Example**: `"Dr. Jane Marie Smith"`
  </Accordion>

  <Accordion title="providerOrgId (Required)" icon="building">
    The unique identifier of the healthcare organization to which the provider belongs in your system.

    This ID maps the provider to the correct organization and keeps data separate across organizations in the Suki platform. This should match the organization ID in your system's database for consistency across platforms.

    **Example**: `"northwell-1234"` or `"memorial-hermann-5678"`
  </Accordion>

  <Accordion title="providerSpecialty (Optional)" icon="stethoscope">
    The medical specialty of the provider, which helps tailor the SDK's functionality to specific clinical contexts.

    If omitted, the system defaults to `"FAMILY_MEDICINE"` as the provider specialty. This information improves the relevance of automated suggestions and templates during onboarding.

    Refer to the [Specialties documentation](/documentation/specialties) for a comprehensive list of supported specialties.
  </Accordion>
</AccordionGroup>

### Step 3: Update ambient options configuration

Replace the deprecated `prefill.noteTypeIds` approach with the new LOINC-based section configuration. We completely redesigned the ambient options structure to use standardized LOINC codes instead of custom note type IDs.

<View title="JavaScript" icon="js">
  #### Before (v1.x)

  ```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  sdkClient.mount({
    rootElement: document.getElementById("suki-root"),
    encounter: encounterDetails,
    ambientOptions: {
      prefill: {
        noteTypeIds: ["note-type-1", "note-type-2"],
      },
    },
  });
  ```

  #### After (v2.0)

  ```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  sdkClient.mount({
    rootElement: document.getElementById("suki-root"),
    encounter: encounterDetails,
    ambientOptions: {
      sections: [
        {
          loinc: "29545-1", // Physical Examination
        },
        {
          loinc: "10164-2", // History of Present Illness
        },
        {
          loinc: "51847-2", // Assessment and Plan
          isPBNSection: true, // NEW: Problem-based charting support
        },
      ],
    },
  });
  ```
</View>

<View title="React" icon="react">
  #### Before (v1.x)

  ```jsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  <SukiAssistant
    encounter={encounter}
    ambientOptions={{
      prefill: {
        noteTypeIds: ["note-type-1", "note-type-2"],
      },
    }}
    onNoteSubmit={(note) => {
      console.log("Note submitted:", note);
    }}
  />
  ```

  #### After (v2.0)

  ```jsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  <SukiAssistant
    encounter={encounter}
    ambientOptions={{
      sections: [
        {
          loinc: "29545-1", // Physical Examination
        },
        {
          loinc: "10164-2", // History of Present Illness
        },
        {
          loinc: "51847-2", // Assessment and Plan
          isPBNSection: true, // NEW: Problem-based charting support
        },
      ],
    }}
    onNoteSubmit={(note) => {
      console.log("Note submitted:", note);
    }}
  />
  ```
</View>

<Note>
  The `prefill.noteTypeIds` approach is still supported but deprecated and will be removed in future versions. We strongly recommend migrating to the new section-based configuration using LOINC codes.

  Refer to the [Note sections documentation](/documentation/note-sections) for a complete list of supported sections and corresponding LOINC codes.
</Note>

### Step 4: Update UI options

The `uiOptions` property now provides more granular control over the SDK's user interface elements, including new section editing capabilities.

<View title="JavaScript" icon="js">
  #### Before (v1.x)

  ```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  sdkClient.mount({
    rootElement: document.getElementById("suki-root"),
    encounter: encounterDetails,
    ambientOptions: { /* ... */ },
    uiOptions: {
      showCloseButton: true,
      showCreateEmptyNoteButton: true,
    },
    onClose: () => {
      console.log("SDK closed");
    },
  });
  ```

  #### After (v2.0)

  ```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  sdkClient.mount({
    rootElement: document.getElementById("suki-root"),
    encounter: encounterDetails,
    ambientOptions: { /* ... */ },
    uiOptions: {
      showCloseButton: true,
      showCreateEmptyNoteButton: true,
      showStartAmbientButton: true, // NEW: Control ambient button visibility
      sectionEditing: { // NEW: Section-level editing controls
        enableDictation: true, // NEW: Voice input for sections
        enableCopy: true, // NEW: Copy functionality
      },
    },
    onClose: () => {
      console.log("SDK closed");
    },
  });
  ```
</View>

<View title="React" icon="react">
  #### Before (v1.x)

  ```jsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  <SukiAssistant
    encounter={encounter}
    ambientOptions={{ /* ... */ }}
    uiOptions={{
      showCloseButton: true,
      showCreateEmptyNoteButton: true,
    }}
    onClose={() => {
      console.log("SDK closed");
    }}
  />
  ```

  #### After (v2.0)

  ```jsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  <SukiAssistant
    encounter={encounter}
    ambientOptions={{ /* ... */ }}
    uiOptions={{
      showCloseButton: true,
      showCreateEmptyNoteButton: true,
      showStartAmbientButton: true, // NEW: Control ambient button visibility
      sectionEditing: { // NEW: Section-level editing controls
        enableDictation: true, // NEW: Voice input for sections
        enableCopy: true, // NEW: Copy functionality
      },
    }}
    onClose={() => {
      console.log("SDK closed");
    }}
  />
  ```
</View>

#### UI options reference

Use the UI configuration options to control the visibility and functionality of various interface elements like buttons and editing features.

<Expandable title="UI Options Properties">
  <ResponseField name="showCloseButton" type="boolean" default="false" required={false}>
    Controls visibility of the close button in the header.
  </ResponseField>

  <ResponseField name="showCreateEmptyNoteButton" type="boolean" default="false" required={false}>
    Controls visibility of the "Create Empty Note" button on the patient profile.
  </ResponseField>

  <ResponseField name="showStartAmbientButton" type="boolean" default="true" required={false}>
    Controls visibility of the "Start Ambient" button for ambient mode initiation.
  </ResponseField>

  <ResponseField name="sectionEditing.enableDictation" type="boolean" default="true" required={false}>
    Controls the microphone icon for voice input (activates voice-to-text feature).
  </ResponseField>

  <ResponseField name="sectionEditing.enableCopy" type="boolean" default="false" required={false}>
    Controls the copy icon for text copying functionality.
  </ResponseField>
</Expandable>

<Tip>
  You should only provide explicit values when you need to enable specific features. For example:

  ```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  // Enable only the copy feature and showStartAmbientButton
  uiOptions: {
    showStartAmbientButton: true,
    sectionEditing: {
      enableCopy: true
    }
  }
  ```
</Tip>

### Step 5: Update note submission handling

Update your note submission handlers to work with the new response structure that includes LOINC codes and enhanced diagnosis information.

#### Before (v1.x)

```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
onNoteSubmit: (note) => {
  console.log("Note ID:", note.noteId);
  note.contents.forEach((section) => {
    console.log(`Section: ${section.title} - ${section.content}`);
  });
}
```

#### After (v2.0)

```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
onNoteSubmit: (note) => {
  console.log("Note ID:", note.noteId);
  note.contents.forEach((section) => {
    console.log(`Section: ${section.title} - ${section.content}`);
    console.log(`LOINC Code: ${section.loinc_code}`); // NEW: LOINC code included
    if (section.diagnosis) { // NEW: Enhanced diagnosis information
      console.log(`Diagnosis: ${section.diagnosis.icdDescription}`);
    }
  });
}
```

#### Example response structure

The note submission payload now includes LOINC codes for better standardization:

```json JSON theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{
  "noteId": "82467ba8-71bc-46e2-8232-20d4d5629973",
  "contents": [
    {
      "title": "History",
      "content": "The patient is a 50-year-old female who has been experiencing fever for the last 10 days...",
      "loinc_code": "18233-4",
      "diagnosis": null
    },
    {
      "title": "Review of Systems",
      "content": "- No additional symptoms or pertinent negatives discussed during the encounter.",
      "loinc_code": "10164-2",
      "diagnosis": null
    },
    {
      "title": "Assessment and Plan",
      "content": "Viral hepatitis B with hepatic coma",
      "loinc_code": "51847-2",
      "diagnosis": {
        "icdCode": "B19.11",
        "icdDescription": "Unspecified viral hepatitis B with hepatic coma",
        "snomedCode": "26206000",
        "snomedDescription": "Hepatic coma due to viral hepatitis B",
        "hccCode": "HCC-1",
        "panelRanking": 1,
        "billable": true,
        "problemLabel": "Unspecified viral hepatitis B with hepatic coma"
      }
    }
  ]
}
```

Refer to [NoteContent](/web-sdk/api-reference/types/note-content) for the complete structure of the note content.

## Complete migration examples

Here are complete examples showing the migration from v1.x to v2.0:

<View title="JavaScript" icon="js">
  <CodeGroup>
    ```js Before (v1.x) expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import { initialize } from "@suki-sdk/js";

    const encounterDetails = {
      identifier: "encounter-id",
      patient: {
        identifier: "patient-id",
        name: {
          use: "official",
          family: "Doe",
          given: ["John"],
          suffix: ["MD"],
        },
        birthDate: "1990-01-01",
        gender: "Male",
      },
    };

    const sdkClient = initialize({
      partnerId: "your-partner-id",
      partnerToken: "your-token",
      enableDebug: true,
      theme: {
        primaryColor: "#4287f5",
      },
    });

    const unsubscribeInit = sdkClient.on("init:change", (isInitialized) => {
      if (isInitialized) {
        sdkClient.mount({
          rootElement: document.getElementById("suki-root"),
          encounter: encounterDetails,
          ambientOptions: {
            prefill: {
              noteTypeIds: ["note-type-1", "note-type-2"],
            },
          },
          uiOptions: {
            showCloseButton: true,
            showCreateEmptyNoteButton: true,
          },
          onNoteSubmit: (note) => {
            console.log("Note submitted:", note.noteId);
          },
          onClose: () => {
            console.log("SDK closed");
          },
        });
      }
    });
    ```

    ```js After (v2.0) expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import { initialize } from "@suki-sdk/js";

    const encounterDetails = {
      identifier: "encounter-id",
      patient: {
        identifier: "patient-id",
        name: {
          use: "official",
          family: "Doe",
          given: ["John"],
          suffix: ["MD"],
        },
        birthDate: "1990-01-01",
        gender: "Male",
      },
    };

    const sdkClient = initialize({
      // Required partner details
      partnerId: "your-partner-id",
      partnerToken: "your-token",
      providerName: "Dr. John Q. Doe",
      providerOrgId: "organization-id",

      // Optional fields
      providerSpecialty: "CARDIOLOGY",
      enableDebug: true,
      theme: {
        primary: "#4287f5",
        background: "#ffffff",
        secondaryBackground: "#f5f5f5",
        foreground: "#333333",
        warning: "#ff9900",
      },
    });

    const unsubscribeInit = sdkClient.on("init:change", (isInitialized) => {
      if (isInitialized) {
        sdkClient.mount({
          rootElement: document.getElementById("suki-root"),
          encounter: encounterDetails,
          ambientOptions: {
            sections: [
              {
                loinc: "29545-1", // Physical Examination
              },
              {
                loinc: "10164-2", // History of Present Illness
              },
              {
                loinc: "51847-2", // Assessment and Plan
                isPBNSection: true,
              },
            ],
          },
          uiOptions: {
            showCloseButton: true,
            showCreateEmptyNoteButton: true,
            showStartAmbientButton: true,
            sectionEditing: {
              enableDictation: true,
              enableCopy: true,
            },
          },
          onNoteSubmit: (note) => {
            console.log("Note submitted:", note.noteId);
            note.contents.forEach((section) => {
              console.log(`LOINC: ${section.loinc_code}, Content: ${section.content}`);
            });
          },
          onClose: () => {
            console.log("SDK closed");
          },
        });
      }
    });
    ```
  </CodeGroup>
</View>

<View title="React" icon="react">
  <CodeGroup>
    ```jsx Before (v1.x) expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import React, { useEffect } from "react";
    import { SukiAssistant, SukiProvider, useSuki } from "@suki-sdk/react";

    const initOptions = {
      partnerId: "your-partner-id",
      partnerToken: "your-token",
      enableDebug: true,
      theme: {
        primaryColor: "#4287f5",
      },
    };

    const encounter = {
      identifier: "encounter-123",
      patient: {
        identifier: "patient-456",
        name: {
          use: "usual",
          family: "Smith",
          given: ["John"],
          suffix: [],
        },
        birthDate: "1980-01-15",
        gender: "male",
      },
    };

    function App() {
      const { init, isInitialized } = useSuki();

      useEffect(() => {
        if (!isInitialized) {
          init(initOptions);
        }
      }, [init, isInitialized]);

      return (
        <SukiAssistant
          encounter={encounter}
          ambientOptions={{
            prefill: {
              noteTypeIds: ["note-type-1", "note-type-2"],
            },
          }}
          onNoteSubmit={(note) => {
            console.log("Note submitted:", note.noteId);
          }}
          uiOptions={{
            showCloseButton: true,
            showCreateEmptyNoteButton: true,
          }}
          onClose={() => {
            console.log("SDK closed");
          }}
        />
      );
    }

    function AppWithProvider() {
      return (
        <SukiProvider>
          <App />
        </SukiProvider>
      );
    }

    export default AppWithProvider;
    ```

    ```jsx After (v2.0) expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import React, { useEffect } from "react";
    import { SukiAssistant, SukiProvider, useSuki } from "@suki-sdk/react";

    const initOptions = {
      // Required partner details
      partnerId: "your-partner-id",
      partnerToken: "your-token",
      providerName: "Dr. John Q. Doe",
      providerOrgId: "organization-id",

      // Optional fields
      providerSpecialty: "CARDIOLOGY",
      enableDebug: true,
      theme: {
        primary: "#4287f5",
        background: "#ffffff",
        secondaryBackground: "#f5f5f5",
        foreground: "#333333",
        warning: "#ff9900",
      },
    };

    const encounter = {
      identifier: "encounter-123",
      patient: {
        identifier: "patient-456",
        name: {
          use: "usual",
          family: "Smith",
          given: ["John"],
          suffix: [],
        },
        birthDate: "1980-01-15",
        gender: "male",
      },
    };

    function App() {
      const { init, isInitialized } = useSuki();

      useEffect(() => {
        if (!isInitialized) {
          init(initOptions);
        }
      }, [init, isInitialized]);

      const handleNoteSubmit = (note) => {
        console.log("Note submitted:", note.noteId);
        note.contents.forEach((section) => {
          console.log(`LOINC: ${section.loinc_code}, Content: ${section.content}`);
        });
      };

      return (
        <SukiAssistant
          encounter={encounter}
          ambientOptions={{
            sections: [
              {
                loinc: "29545-1", // Physical Examination
              },
              {
                loinc: "10164-2", // History of Present Illness
              },
              {
                loinc: "51847-2", // Assessment and Plan
                isPBNSection: true,
              },
            ],
          }}
          onNoteSubmit={handleNoteSubmit}
          uiOptions={{
            showCloseButton: true,
            showCreateEmptyNoteButton: true,
            showStartAmbientButton: true,
            sectionEditing: {
              enableDictation: true,
              enableCopy: true,
            },
          }}
          onClose={() => {
            console.log("SDK closed");
          }}
        />
      );
    }

    function AppWithProvider() {
      return (
        <SukiProvider>
          <App />
        </SukiProvider>
      );
    }

    export default AppWithProvider;
    ```
  </CodeGroup>
</View>

## Breaking changes reference

This section provides detailed information about each breaking change and its migration impact.

### Provider information

<ResponseField name="providerName" type="string" required>
  The provider's full name. This field is now required during SDK initialization to enable automatic provider onboarding to the Suki system.

  **Migration Impact**: Previously optional, now required in `InitializationConfig`.
</ResponseField>

<ResponseField name="providerOrgId" type="string" required>
  The unique identifier for the provider's organization. This field is now required during SDK initialization.

  **Migration Impact**: Previously optional, now required in `InitializationConfig`. This enables seamless provider registration without manual onboarding steps.
</ResponseField>

### AmbientOptions structure

<Warning>
  The `ambientOptions` structure has been completely redesigned in v2.0. The previous `prefill.noteTypeIds` approach is deprecated.
</Warning>

<ResponseField name="sections" type="array" required>
  An array of section objects that define which note sections to generate. Each section is identified by a LOINC code for improved standardization and interoperability with healthcare systems.

  **v1.x Deprecated approach**:

  ```typescript TypeScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  ambientOptions: {
    prefill: {
      noteTypeIds: ['soap', 'hpi']
    }
  }
  ```

  **v2.0 Required approach**:

  ```typescript TypeScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  ambientOptions: {
    sections: [
      { loinc: '48765-2' }, // Allergies
      { loinc: '10164-2' }  // History of Present Illness
    ]
  }
  ```

  **Migration impact**: You must replace all `noteTypeIds` references with LOINC-based section configurations. Refer to the [Note sections documentation](/documentation/note-sections) for complete LOINC code mappings.
</ResponseField>

### Theme configuration

<ResponseField name="primary" type="string">
  Renamed from `primaryColor`. Defines the primary brand color for the SDK interface.

  **Migration impact**: Update all `primaryColor` references to `primary` in your theme configuration.
</ResponseField>

<ResponseField name="background" type="string">
  New property. Defines the main background color for the SDK interface.

  **Migration impact**: This is a new optional property that enhances UI customization capabilities.
</ResponseField>

<ResponseField name="secondaryBackground" type="string">
  New property. Defines the secondary background color for panels and cards within the SDK interface.

  **Migration impact**: This is a new optional property that provides more granular control over the visual hierarchy.
</ResponseField>

<ResponseField name="foreground" type="string">
  New property. Defines the primary text color for the SDK interface.

  **Migration impact**: This is a new optional property that ensures text readability across different background colors.
</ResponseField>

<ResponseField name="warning" type="string">
  New property. Defines the color used for warning messages and alerts.

  **Migration impact**: This is a new optional property that improves the visibility of important notifications.
</ResponseField>

### Mount configuration

<ResponseField name="ambientOptions" type="AmbientOptions" required>
  Configuration options for ambient mode functionality. This field is now required when mounting the SDK.

  **Migration Impact**: Previously optional in v1.x, now required in v2.0. You must provide `ambientOptions` with at least one section defined when calling `mount()`.

  **Example**:

  ```typescript TypeScript  theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  await sukiSDK.mount({
    target: document.getElementById('suki-container'),
    ambientOptions: {
      sections: [
        { loinc: '48765-2' }
      ]
    }
  });
  ```
</ResponseField>

## Troubleshooting

### Common migration errors

<AccordionGroup>
  <Accordion title="Initialization Errors">
    * `missing-partner-details`: Provider information is incomplete
    * `no-partner-token`: Authentication token is missing
    * `no-init`: SDK not properly initialized
  </Accordion>

  <Accordion title="Ambient Mode Errors">
    * `no-ambient`: Ambient mode not available
    * `ambient-in-progress`: Another ambient session is active
    * `already-started`: Ambient session already running
  </Accordion>

  <Accordion title="LOINC Code Errors">
    * `unsupported-loinc-codes`: One or more LOINC codes are not supported
    * `no-supported-loinc-codes`: No valid LOINC codes provided
  </Accordion>
</AccordionGroup>

### Validation checklist

After migration, verify the following:

* All required provider information is supplied in initialization (`providerName` and `providerOrgId`)
* `AmbientOptions` uses the new section-based configuration with LOINC codes
* Theme configuration uses the new property names (`primary` instead of `primaryColor`)
* Section editing features are configured as needed (`sectionEditing.enableDictation` and `sectionEditing.enableCopy`)
* All UI options are properly configured
* Note submission handlers account for new LOINC code fields (`section.loinc_code`)

## Next steps

<CardGroup cols={2}>
  <Card title="Note Sections" icon="list" arrow={true} href="/documentation/note-sections">
    Learn about supported LOINC codes and section configurations
  </Card>

  <Card title="Specialties" icon="stethoscope" arrow={true} href="/documentation/specialties">
    View the complete list of supported medical specialties
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" arrow={true} href="/web-sdk/guides/error-handling">
    Implement proper error handling for your integration
  </Card>

  <Card title="Basic Usage" icon="play" arrow={true} href="/web-sdk/examples/basic-usage">
    See complete examples of the v2.0 implementation
  </Card>

  <Card title="Migration to v3" icon="rocket" arrow={true} href="/web-sdk/product-updates/migration-to-v3">
    Move authentication to SukiAuthManager from @suki-sdk/core
  </Card>
</CardGroup>