Skip to main content
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.

​
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). Like the JavaScript client, this returns an unsubscribe function same pattern as SDKClientInstance.on in 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 v3 migration: init expects an authManager object from @suki-sdk/core on the options object for authentication credentials. See Migrating to Web SDK v3.

​
useSuki hook

​
Usage

Call useSuki() with no arguments from a descendant of SukiProvider.
Typescript
const client: UseSukiReturn = useSuki();

​
Returns

The hook returns a UseSukiReturn object. Its properties and methods mirror those on SDKClientInstance 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.
JavaScript
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

​
Available methods

​
Next steps

Refer to the Provider types to learn more about the provider types.
Last modified on May 22, 2026