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

# Hooks Reference

> Learn about Web SDK React hooks for state management and SDK integration

The **`useSuki`** hook provides a React-friendly way to use the Suki Web SDK from components. It exposes session state, lets you handle SDK events, and exposes ambient methods without passing a JavaScript client instance through props.

### Prerequisites

**`useSuki`** must be used within a component tree wrapped by [`SukiProvider`](/web-sdk/api-reference/providers).

### Common use cases

* **Initialization:** Call **`init`** with your configuration options. Use **`isInitialized`** to avoid redundant initialization and to gate UI logic.
* **Token management:** Call **`setPartnerToken`** when the host application supplies a new **`partnerToken`**.
* **Ambient session control:** Manage the lifecycle with **`startAmbient`**, **`pauseAmbient`**, **`resumeAmbient`**, **`cancelAmbient`**, and **`submitAmbient`**.
* **State monitoring:** Read **`activeAmbientId`**, **`isAmbientInProgress`**, **`isAmbientPaused`**, and **`error`** to drive UI updates or logging.
* **Event handling:** Use **`on`** to subscribe to SDK events (for example **`ambient:update`** or **`error`**; refer to [Emitter events](/web-sdk/api-reference/types/emitter-events)). Like the JavaScript client, this returns an unsubscribe function same pattern as **`SDKClientInstance.on`** in [Classes](/web-sdk/api-reference/classes).
* **Authentication and encounter data:** Use **`setEncounter`** to push encounter context updates, and **`attemptLogin`** to trigger re-authentication same role as **`SDKClientInstance.attemptLogin`** in [Classes](/web-sdk/api-reference/classes).

<Tip>
  **Web SDK v3 migration:** **`init`** expects an **`authManager`** object from **`@suki-sdk/core`** on the options object for authentication credentials. See [Migrating to Web SDK v3](/web-sdk/product-updates/migration-to-v3).
</Tip>

## useSuki hook

### Usage

Call **`useSuki()`** with no arguments from a descendant of **`SukiProvider`**.

```typescript Typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
const client: UseSukiReturn = useSuki();
```

### Returns

The hook returns a [`UseSukiReturn`](/web-sdk/api-reference/hooks#usesukireturn-type) object. Its properties and methods mirror those on [`SDKClientInstance`](/web-sdk/api-reference/classes) from the JavaScript `initialize()` path. The following sections document each field and method.

## UseSukiReturn type

Return type of the `useSuki` hook containing SDK state and methods.

```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
type UseSukiReturn = {
  activeAmbientId: string | null;
  attemptLogin: () => void;
  cancelAmbient: () => void;
  error: SukiError | null;
  init: (options: ReactInitOptions) => void;
  isAmbientInProgress: boolean;
  isAmbientPaused: boolean;
  isInitialized: boolean;
  on: <T extends keyof EmitterEvents>(
    type: T,
    handler: (args: EmitterEvents[T]) => void | Promise<void>,
  ) => () => void;
  pauseAmbient: () => void;
  resumeAmbient: () => void;
  setEncounter: (encounter: Encounter) => Promise<void>;
  setPartnerToken: (partnerToken: string) => void;
  startAmbient: () => void;
  submitAmbient: () => void;
};
```

### Available properties

<Expandable title="properties" defaultOpen="true">
  <ResponseField name="activeAmbientId" type="string | null">
    The ID of the currently active ambient session, or `null` if no session is active.
  </ResponseField>

  <ResponseField name="error" type="SukiError | null" href="/web-sdk/api-reference/types#sukierror">
    Current error state of the SDK, or `null` if no errors.
  </ResponseField>

  <ResponseField name="isAmbientInProgress" type="boolean">
    Whether an ambient session is currently in progress.
  </ResponseField>

  <ResponseField name="isAmbientPaused" type="boolean">
    Whether the current ambient session is paused.
  </ResponseField>

  <ResponseField name="isInitialized" type="boolean">
    Whether the SDK has been successfully initialized.
  </ResponseField>
</Expandable>

### Available methods

<Expandable title="available methods" defaultOpen="true">
  <ResponseField name="attemptLogin" type="void">
    Attempts to authenticate when SDK is not authenticated after initialization. This method does not take any parameters.
  </ResponseField>

  <ResponseField name="cancelAmbient" type="void">
    Cancels the current ambient session. This method does not take any parameters.
  </ResponseField>

  <ResponseField name="init" type="void">
    Initializes the SDK with the provided options. Web SDK v3 passes `authManager` from `@suki-sdk/core` on `options` instead of partner fields alone. See [Migrating to Web SDK v3](/web-sdk/product-updates/migration-to-v3).

    <Expandable title="parameters" defaultOpen="true">
      <ResponseField name="options" type="ReactInitOptions" href="/web-sdk/api-reference/types#initoptions" required>
        The configuration options required to initialize the SDK.
      </ResponseField>
    </Expandable>
  </ResponseField>

  <ResponseField name="on" type="() => void">
    Subscribes to SDK events. This method returns an unsubscribe function.

    <Expandable title="parameters" defaultOpen="true">
      <ResponseField name="type" type="T" required>
        The type of event to subscribe to (e.g., `'ready'`, `'ambient:update'`).
      </ResponseField>

      <ResponseField name="handler" type="(args: EmitterEvents[T]) => void | Promise<void>" required>
        The callback function to be executed when the event is emitted.
      </ResponseField>
    </Expandable>
  </ResponseField>

  <ResponseField name="pauseAmbient" type="void">
    Pauses the current ambient session. This method does not take any parameters.
  </ResponseField>

  <ResponseField name="resumeAmbient" type="void">
    Resumes a paused ambient session. This method does not take any parameters.
  </ResponseField>

  <ResponseField name="setEncounter" type="Promise<void>">
    Updates the current encounter data.

    <Expandable title="parameters" defaultOpen="true">
      <ResponseField name="encounter" type="Encounter" href="/web-sdk/api-reference/types#encounter" required>
        Full [`Encounter`](/web-sdk/api-reference/types/encounter) payload. **`patient.identifier`** is required. **`encounter.identifier`** is optional. Each value must be **at most 36 characters** (<Tooltip tip="VARCHAR is a variable-length SQL string type. varchar(36) caps these identifiers at 36 characters. See the Glossary." cta="View in Glossary" href="/Glossary/v#varchar-36">varchar(36)</Tooltip>) when present.
      </ResponseField>
    </Expandable>
  </ResponseField>

  <ResponseField name="setPartnerToken" type="void">
    Updates the `partnerToken` after token refresh.

    <Expandable title="parameters" defaultOpen="true">
      <ResponseField name="partnerToken" type="string" required>
        The new `partnerToken` string.
      </ResponseField>
    </Expandable>
  </ResponseField>

  <ResponseField name="startAmbient" type="void">
    Starts a new ambient session. This method does not take any parameters.
  </ResponseField>

  <ResponseField name="submitAmbient" type="void">
    Submits the current ambient session. This method does not take any parameters.
  </ResponseField>
</Expandable>

## Next steps

<Icon icon="file-lines" iconType="solid" /> Refer to the [Provider types](/web-sdk/api-reference/providers) to learn more about the provider types.