npm package: @sessioniq/widget-react
Description: SessionIQ Widget React
Author: SessionIQ
Latest version: 0.4.6

# SessionIQ React Widget (`@sessioniq/widget-react`)

[![npm version](https://badge.fury.io/js/%40sessioniq%2Fwidget-react.svg)](https://badge.fury.io/js/%40sessioniq%2Fwidget-react)

## Overview

This package provides a pre-built React component (`AgentWidget`) that acts as a user interface for interacting with the `@sessioniq/client-sdk`. It allows users to:

- Select an active analysis agent.
- Start and stop session recording.
- Trigger session analysis.
- View analysis status updates and results (including AI insights and suggestions) in a chat interface.
- Interact with the AI agent via chat messages after analysis is complete.

The widget handles communication with the SDK, including subscribing to real-time updates and sending commands like `startRecording`, `stopRecording`, `analyzeSession`, and `sendChatMessage`.

## Installation

```bash
# Using npm (or pnpm or yarn)
npm install @sessioniq/widget-react @sessioniq/client-sdk
```

_Note: `@sessioniq/client-sdk` is a required **peer dependency**._

## Usage

```jsx
import React, { useState, useEffect, useRef } from "react";
import { SessionIQSdk } from "@sessioniq/client-sdk";
import { AgentWidget } from "@sessioniq/widget-react";
// Import the CSS if your bundler supports it
import "@sessioniq/widget-react/widget-react.css";

function App() {
  const [isInitialized, setIsInitialized] = useState(false);
  // Use a ref to hold the SDK instance to avoid re-creating it on re-renders
  const sdkRef = useRef<InstanceType<typeof SessionIQSdk> | null>(null);

  useEffect(() => {
    // Initialize SDK only once
    if (!sdkRef.current) {
      console.log("Initializing SessionIQ SDK...");
      const sdkInstance = new SessionIQSdk();
      sdkRef.current = sdkInstance;

      sdkInstance.init({
        clientId: "YOUR_CLIENT_ID", // Replace with your actual Client ID
        logLevel: "debug", // Optional: Set desired log level
      })
      .then(() => {
        console.log("SessionIQ SDK Initialized!");
        setIsInitialized(true);
      })
      .catch((error) => {
        console.error("Failed to initialize SessionIQ SDK:", error);
        // Handle initialization error (e.g., show error message)
      });
    }

    // Cleanup function to destroy SDK instance on component unmount
    return () => {
      if (sdkRef.current) {
        console.log("Destroying SessionIQ SDK instance.");
        sdkRef.current.destroy();
        sdkRef.current = null;
        setIsInitialized(false);
      }
    };
  }, []); // Empty dependency array ensures this runs only once on mount

  return (
    <div>
      {/* Other application content */}

      {/* Render AgentWidget only after SDK is initialized */}
      {isInitialized && sdkRef.current && (
        <AgentWidget sdk={sdkRef.current} position="bottom-right" />
      )}

      {/* Example of using the useWidget hook (optional) */}
      {/* <WidgetController /> */}
    </div>
  );
}

/*
// Example of a separate component to control the widget
import { useWidget } from "@sessioniq/widget-react";

function WidgetController() {
  const { isWidgetOpen, openWidget, closeWidget } = useWidget();

  return (
    <div style={{ position: 'fixed', top: '10px', left: '10px' }}>
      <button onClick={openWidget}>Open Widget</button>
      <button onClick={closeWidget}>Close Widget</button>
      <p>Widget is: {isWidgetOpen ? 'Open' : 'Closed'}</p>
    </div>
  );
}
*/

export default App;
```

## Exports

This package exports:

- `AgentWidget`: The main React component.
- `useWidget`: A custom React hook to control the widget's visibility programmatically.

## Component Props (`AgentWidget`)

- `sdk` (Required): An **initialized** instance of `SessionIQSdk` from `@sessioniq/client-sdk`.
- `position` (Optional, default: `'bottom-right'`): Controls the floating position of the widget button. Options: `'bottom-right'`, `'top-right'`, `'bottom-left'`, `'top-left'`, `'hidden'`.

## Custom Hook (`useWidget`)

Provides functions and state to control the widget UI:

```typescript
import { useWidget } from "@sessioniq/widget-react";

function MyComponent() {
  const { isWidgetOpen, toggleWidget, openWidget, closeWidget } = useWidget();

  // Example usage:
  return (
    <div>
      <button onClick={openWidget}>Open Support Widget</button>
      <p>Widget is currently {isWidgetOpen ? 'open' : 'closed'}.</p>
    </div>
  );
}
```

- `isWidgetOpen`: A `boolean` state indicating if the widget panel is open.
- `toggleWidget()`: Function to toggle the widget panel's visibility.
- `openWidget()`: Function to open the widget panel.
- `closeWidget()`: Function to close the widget panel.

## License

MIT License - Copyright (c) 2025 SessionIQ