@useknest/widget-react

Native React component for the Knest chat widget with streaming support.

Installation

npm install @useknest/widget-react
# or
pnpm add @useknest/widget-react
# or
yarn add @useknest/widget-react

Usage

Basic Example

import { ChatWidget } from '@useknest/widget-react';

function App() {
	return (
		<div>
			<ChatWidget publishableApiKey="pk_your_public_key_here" />
		</div>
	);
}

That's it! Styles are automatically included - no separate CSS import needed.

Props

ChatWidget

| Prop | Type | Required | Default | Description | | ------------------- | ---------------------- | -------- | ---------- | ---------------------------------------------------------------- | | publishableApiKey | string | Yes | - | Your project's publishable API key | | mode | 'inline' \| 'bubble' | No | 'inline' | Display mode: inline or floating bubble button | | defaultOpen | boolean | No | false | Whether the chat starts open (only applies to bubble mode) | | user | WidgetUser | No | - | Identifies the logged-in user; requires at least id or email |

WidgetUser

interface WidgetUser {
	id?: string; // Your system's user ID (cross-device dedup key)
	email?: string;
	fullName?: string;
	metadata?: Record<string, unknown>; // Custom attributes (e.g. plan, company)
}

<ChatWidget
	publishableApiKey="pk_..."
	user={{ id: currentUser.id, email: currentUser.email, fullName: currentUser.name }}
/>

Features

• ✅ Native React Component - Built with React hooks, no web component wrapper
• ✅ Streaming Support - Real-time message streaming via Server-Sent Events (SSE)
• ✅ TypeScript - Full TypeScript support with exported types
• ✅ Customizable - Fetches branding (avatar, colors, welcome message) from your project config
• ✅ Lightweight - ~17KB minified (~4.4KB gzipped)
• ✅ Framework-Agnostic Core - Shares business logic with other platform packages

TypeScript

The package includes TypeScript definitions. You can import types:

import { ChatWidget, type ChatWidgetProps, type Message } from '@useknest/widget-react';

Customization

The widget automatically loads customization from your project's configuration at useknest.com:

• Avatar image
• Brand color
• Welcome message
• Example questions

No additional props needed - just provide your publishableApiKey.

Architecture

This package uses @useknest/widget-core for all business logic (API calls, streaming, markdown rendering). The React component handles only the UI rendering with React-specific optimizations.

Benefits:

• Efficient re-renders during streaming
• Native React state management
• React DevTools compatibility
• Optimized bundle size

Browser Support

• Modern browsers (Chrome, Firefox, Safari, Edge)
• Requires native ES modules support
• Requires EventSource API for streaming (available in all modern browsers)

Examples

Full-Height Widget

import { ChatWidget } from '@useknest/widget-react';

function FullPageChat() {
	return (
		<div style={{ height: '100vh', width: '100vw' }}>
			<ChatWidget publishableApiKey="pk_your_public_key_here" />
		</div>
	);
}

Widget in a Container

import { ChatWidget } from '@useknest/widget-react';

function ChatContainer() {
	return (
		<div style={{ maxWidth: '900px', height: '600px', margin: '0 auto' }}>
			<ChatWidget publishableApiKey="pk_your_public_key_here" />
		</div>
	);
}

Floating Bubble Mode

import { ChatWidget } from '@useknest/widget-react';

function App() {
	return <ChatWidget publishableApiKey="pk_your_public_key_here" mode="bubble" />;
}

Bubble Mode (Auto-Open)

import { ChatWidget } from '@useknest/widget-react';

function App() {
	return <ChatWidget publishableApiKey="pk_your_public_key_here" mode="bubble" defaultOpen />;
}

License

Proprietary - All rights reserved. This software is for use by authorized Knest customers only.

Support

For issues and questions, please email us at [email protected]