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

# Advanced Configuration

> Learn to use the advanced JavaScript and React Web SDK configuration options and customization features

Customize the Suki Assistant Web SDK to fit your application's specific needs. This example covers the complete setup, including the **root provider**, **dynamic props**, **UI customization**, and **event handling**, as shown in the comprehensive example.

## Configurations

### Wrapping your application

Wrapping your application with the `SukiProvider` component is the first step in configuring the Suki Assistant Web SDK. This is necessary for the SDK and its hooks to function correctly.

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

  // This is the root of your application
  function Root() { 
    return (
      <SukiProvider>
        <App />
      </SukiProvider>
    );
  }
  ```
</CodeGroup>

### Initializing the SDK

Before you can use advanced features, you must **initialize the SDK** inside the `SukiProvider` context.

Use `SukiAuthManager` from `@suki-sdk/core` for `partnerToken` and provider fields, then call `init` from `useSuki` **once** when your application loads (typically inside a `useEffect`), passing `authManager` on the options object. See [Migrating to Web SDK v3](/web-sdk/product-updates/migration-to-v3).

<CodeGroup>
  ```jsx JavaScript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}

  import { useEffect, useMemo } from "react";
  import { SukiAuthManager } from "@suki-sdk/core";
  import { SukiProvider, useSuki } from "@suki-sdk/react";

  function App() {
    const authManager = useMemo(
      () =>
        new SukiAuthManager({
          partnerId: "f80c8db8-a4d0-4b75-8d63-56c82b5413f0", // Replace with your partner ID
          partnerToken: "YOUR_JWT_HERE", // Replace with your partner token
          providerName: "John Doe", // Replace with your provider's name
          providerOrgId: "1234", // Replace with your provider's organization ID
          providerId: "1234567890", // Replace with the provider's ID
          providerSpecialty: "FAMILY_MEDICINE", // Replace with the provider's specialty
          environment: "production",
          loginOnInitialize: true,
        }),
      [],
    );

    const { init, isInitialized } = useSuki();

    useEffect(() => {
      if (!isInitialized) {
        init({
          authManager,
          theme: {
            primary: "#0066cc", // Replace with your primary color
            background: "#ffffff", // Replace with your background color
          },
        });
      }
    }, [init, isInitialized, authManager]);

    // ... rest of the application
  }
  ```
</CodeGroup>

### Configure the SukiAssistant component

The `<SukiAssistant />` component is the main UI for the SDK. Configure its behavior and appearance by passing it the following props.

#### Handling dynamic encounters

The `encounter` prop is the most important piece of contextual information.

The example below demonstrates how to dynamically change this prop to load different patient encounters into the SDK.

<CodeGroup>
  ```jsx JavaScript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import { useState } from "react";

  // In your main App component...
  const [encounter, setEncounter] = useState(encounters[0]); // encounters is your array of data

  return (
    <>
      {/* Buttons to demonstrate switching the encounter context */}
      <button onClick={() => setEncounter(encounters[0])}>
        Load Encounter 1
      </button>
      <button onClick={() => setEncounter(encounters[1])}>
        Load Encounter 2
      </button>

      {/* Pass the currently selected encounter to the component */}
      <SukiAssistant encounter={encounter} {...otherProps} />
    </>
  );
  ```
</CodeGroup>

#### Ambient and UI options

The `ambientOptions` and `uiOptions` props are used to configure the ambient session and the user interface of the SDK.

<Accordion title="Ambient Prop" icon="microphone" defaultOpen="true">
  `ambientOptions`: Configures the note-generation session.

  <ResponseField name="sections" type="Array" required={false}>
    An array of objects that defines the clinical sections for note generation, identified by [LOINC codes](/documentation/note-sections).

    <Expandable title="properties" defaultOpen="true">
      <ResponseField name="loinc" type="string" required>
        The LOINC code for the clinical section.
      </ResponseField>

      <ResponseField name="isPBNSection" type="boolean">
        A boolean that indicates if the section should be treated as a Problem-Based Noting section.
      </ResponseField>
    </Expandable>
  </ResponseField>

  <ResponseField name="diagnoses" type="object" required={false}>
    **Optional.** Use this when you have Problem-Based Charting (PBC) enabled. Pass the patient's existing diagnoses (e.g. from the EMR) so the session can merge them with what's discussed during the visit and avoid duplicate problems in the note.

    Each item in <code>values</code> is one diagnosis: give it a single <code>code</code> (ICD10 only for now) and optionally a <code>description</code> or <code>diagnosis\_note</code>. Refer to the [Existing patient diagnoses](/web-sdk/guides/ambient-problem-based-charting#existing-patient-diagnoses) guide for more details.
  </ResponseField>

  <CodeGroup>
    ```jsx JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    const ambientOptions = {
      sections: [
        {
          loinc: "51847-2", // Assessment and Plan
          isPBNSection: true,
        },
        {
          loinc: "10164-2", // History of Present Illness
        },
        {
          loinc: "10187-3", // Review of Systems
        },
      ],
      diagnoses: { // [!code ++:14] New in v2.1.2
        values: [
          {
            codes: [
              {
                code: "I10",
                description: "Essential hypertension",
                type: "ICD10",
              },
            ],
            diagnosisNote: "Hypertension",
          },
        ],
      },
    };
    ```
  </CodeGroup>
</Accordion>

<Accordion title="UI Prop" icon="eye" defaultOpen="true">
  `uiOptions`: Controls the visibility and functionality of UI elements like the **close button** or editing features within note sections.

  <ResponseField name="showCloseButton" type="boolean">
    Controls visibility of the close button in the header.
  </ResponseField>

  <ResponseField name="showCreateEmptyNoteButton" type="boolean">
    Controls visibility of the create empty note button in the patient profile.
  </ResponseField>

  <ResponseField name="showStartAmbientButton" type="boolean">
    Controls visibility of the start ambient button in the patient profile.
  </ResponseField>

  <ResponseField name="sectionEditing" type="object">
    Controls the visibility and functionality of editing features within note sections.

    <Expandable title="properties" defaultOpen="true">
      <ResponseField name="enableDictation" type="boolean">
        **(Default: true)** Enables or disables the dictation (microphone) icon for editing text.
      </ResponseField>

      <ResponseField name="enableCopy" type="boolean">
        **(Default: false)** Enables or disables the copy-to-clipboard icon for section content.
      </ResponseField>
    </Expandable>
  </ResponseField>

  <CodeGroup>
    ```jsx JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    const uiOptions = {
      showCloseButton: true,
      showStartAmbientButton: true,
      showCreateEmptyNoteButton: false,
      sectionEditing: {
        enableDictation: true,
        enableCopy: false,
      },
    };
    ```
  </CodeGroup>
</Accordion>

#### Event handlers

Listen for key events from the SDK by providing `callback` functions as props. This allows your application to react when a user takes an action.

* `onNoteSubmit`: This function is called when a note is successfully generated and submitted. It receives an object containing the `noteId` and the `contents` of the note.

* `onClose`: This function is called when the user clicks the close button in the UI.

## Complete example

This example ties all the concepts together, showing the `SukiProvider`, `SukiAssistant`, `useSuki` hook, dynamic encounters, and all configuration props in a single, working component structure.

<CodeGroup>
  ```jsx JavaScript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import React, { useEffect, useMemo, useState } from "react";
  import { SukiAuthManager } from "@suki-sdk/core";
  import { SukiAssistant, SukiProvider, useSuki } from "@suki-sdk/react";

  // Mock data for demonstration
  const encounters = [
    {
      identifier: "6ec3920f-b0b1-499d-a4e9-889bf788e5ab",
      patient: {
        identifier: "905c2521-25eb-4324-9978-724636df3436",
        name: { family: "Smith", given: ["John"] },
        birthDate: "1980-01-15",
        gender: "male",
      },
    },
    {
      identifier: "qsc2393g-b0b1-499d-a4e9-983cq125g5op",
      patient: {
        identifier: "25eb905-1232-082132-aw12320do4r",
        name: { family: "Johnson", given: ["Sarah"] },
        birthDate: "1985-03-20",
        gender: "female",
      },
    },
  ];

  // 1. SukiProvider must wrap the root of your application
  function Root() {
    return (
      <SukiProvider>
        <App />
      </SukiProvider>
    );
  }

  // 2. The main application component handles initialization and state
  function App() {
    const authManager = useMemo(
      () =>
        new SukiAuthManager({
          partnerId: "f80c8db8-a4d0-4b75-8d63-56c82b5413f0", // Replace with your actual partner ID
          partnerToken: "YOUR_JWT_HERE", // Replace with your actual partner token
          providerName: "John doe",
          providerOrgId: "1234",
          providerId: "1234567890", // Replace with the provider's ID
          providerSpecialty: "FAMILY_MEDICINE", // Replace with the provider's specialty
          environment: "production",
          loginOnInitialize: true,
        }),
      [],
    );

    const { init, isInitialized } = useSuki();
    const [encounter, setEncounter] = useState(encounters[0]);

    useEffect(() => {
      if (!isInitialized) {
        init({
          authManager,
          theme: {
            primary: "#0066cc",
            background: "#ffffff",
          },
        });
      }
    }, [init, isInitialized, authManager]);

    // Define ambient options for note generation
    const ambientOptions = {
      sections: [
        { loinc: "51847-2", isPBNSection: true }, // Assessment and Plan
        { loinc: "10164-2" }, // History of Present Illness
        { loinc: "10187-3" }, // Review of Systems
      ],
      diagnoses: { // [!code ++:14] New in v2.1.2
        values: [
          {
            codes: [
              {
                code: "I10",
                description: "Essential hypertension",
                type: "ICD10",
              },
            ],
            diagnosisNote: "Hypertension",
          },
        ],
      },
    };

    return (
      <>
        <h3>Select an Encounter:</h3>
        <button onClick={() => setEncounter(encounters[0])}>
          Load John Smith
        </button>
        <button onClick={() => setEncounter(encounters[1])}>
          Load Sarah Johnson
        </button>
        <hr />
        <AdvancedSDKComponent
          encounter={encounter}
          ambientOptions={ambientOptions}
        />
      </>
    );
  }

  // 3. This component renders and manages the SukiAssistant UI
  function AdvancedSDKComponent({ encounter, ambientOptions }) {
    const [isVisible, setIsVisible] = useState(true);

    // Define UI options to customize the interface
    const uiOptions = {
      showCloseButton: true,
      showStartAmbientButton: true,
      showCreateEmptyNoteButton: false,
      sectionEditing: {
        enableDictation: true,
        enableCopy: false,
      },
    };

    // Define event handlers to react to SDK events
    const handleNoteSubmit = (data) => {
      console.log("Note submitted successfully:", data.noteId);
      data.contents.forEach((section) => {
        console.log(`- ${section.title}: ${section.content}`);
      });
    };

    const handleClose = () => {
      setIsVisible(false);
      console.log("SDK closed by user");
    };

    if (!isVisible) {
      return <div>SDK has been closed.</div>;
    }

    return (
      <SukiAssistant
        encounter={encounter}
        uiOptions={uiOptions}
        ambientOptions={ambientOptions}
        onNoteSubmit={handleNoteSubmit}
        onClose={handleClose}
      />
    );
  }

  ```
</CodeGroup>

## Next steps

<Icon icon="file-lines" iconType="solid" /> Read the [Theming and customization](/web-sdk/examples/theming-and-customization) example to learn how to customize the UI of the SDK.