A React component library for integrating the Copilot chat widget into your applications. This library provides a flexible and type-safe way to manage single or multiple Copilot instances with custom tools, user configurations, and full telemetry observab
npm install @copilotlive/react-sdkA React component library for integrating the Copilot chat widget into your applications. This library provides a flexible and type-safe way to manage single or multiple Copilot instances with custom tools, user configurations, and full telemetry observability.
- 🔄 Automatic Single/Multi Mode: Automatically detects and supports both single and multiple Copilot instances.
- 🛠 Custom Tools Integration: Register powerful tools with support for async handlers.
- 👥 User Management: Easily set/unset user information across sessions.
- 🪝 Ergonomic Hooks: Intuitive and declarative hooks to register tools, context, eventLoggers, and users via useCopilotTool, useCopilotContext, useTelemetry, and useCopilotUser.
- 🧠 Smart Resolution: Access Copilot instance by name or index, with graceful fallback and validation.
- ⚡ Type-Safe: Built in TypeScript with full type support and validation helpers.
- 🔌 Simple Integration: Drop-in provider and hook system for seamless integration.
- 📊 Telemetry Observability: Full telemetry event tracking with fallback handling, throttling, and section-level filtering.
``bash`
npm install @copilotlive/react-sdkor
yarn add @copilotlive/react-sdk
`tsx
import { CopilotProvider } from '@copilotlive/react-sdk';
function App() {
return (
config={{ theme: 'light', position: 'bottom-right' }}
>
);
}
`
`tsx
import { useTelemetry } from '@copilotlive/react-sdk';
import { TelemetryEvent } from '@copilotlive/react-sdk/types';
// All events
const all = useTelemetry();
// All 'user:*' events
const userEvents = useTelemetry(TelemetryEvent.User);
// Specific telemetry
const widgetClose = useTelemetry(TelemetryEvent.Widget.Close);
// Only unknown/unclassified telemetry
const unknown = useTelemetry(TelemetryEvent.Other);
// Throttled
const throttled = useTelemetry(TelemetryEvent.Call.Connect, { throttleDuration: 1000 });
`
`tsx
import { CopilotProvider } from '@copilotlive/react-sdk';
function App() {
return (
{ token: 'token-1', config: { theme: 'light' } },
{ token: 'token-2', config: { theme: 'dark' } }
]}
>
);
}
`
`tsx
import { Copilot, ToolDefinition } from '@copilotlive/react-sdk';
const tools: ToolDefinition[] = [
{
name: 'get_user_info',
description: 'Retrieves user info',
parameters: {
type: 'object',
properties: {
userId: { type: 'string', description: 'User ID' },
},
required: ['userId']
},
handler: async ({ userId }) => fetch(/api/users/${userId}).then(res => res.json())
}
];
function ToolsLoader() {
return
}
`
`tsx
import { useCopilotTool } from '@copilotlive/react-sdk';
useCopilotTool({
name: 'calculate_sum',
description: 'Adds two numbers',
parameters: {
type: 'object',
properties: {
a: { type: 'number' },
b: { type: 'number' }
},
required: ['a', 'b']
},
handler: ({ a, b }) => ({ result: a + b })
}, { removeOnUnmount: true });
`
`tsx
import { useCopilotUser } from '@copilotlive/react-sdk';
useCopilotUser({
id: 'user123',
name: 'Jane Doe',
email: 'jane@example.com'
}, { unsetOnUnmount: true });
`
`tsx
import { useCopilotContext } from '@copilotlive/react-sdk';
useCopilotContext(
{
description: "Product the user is viewing",
store: "product",
value: {
product_id: "12345",
product_name: "Men's Classic T-Shirt",
price: 19.99,
currency: "USD",
in_stock: true,
},
},
{
unsetOnUnmount: true,
}
);
`
`tsx
import { useCopilot } from '@copilotlive/react-sdk';
function Controls() {
const copilot = useCopilot(); // Defaults to index 0
return (
<>
);
}
`
`tsx`
const copilotA = useCopilot('copilot1');
const copilotB = useCopilot(1);
Includes CopilotProvider, useCopilot, useTelemetry, and all telemetry types.
Refer to source or documentation for full schemas.
`bash``
yarn build
yarn typecheck
yarn lint