npm package: @kookee/react
Description: Official Kookee React Chat Widget - Embeddable AI-powered support chat
Latest version: 0.0.42

# @kookee/react

Official React chat widget for [Kookee](https://kookee.dev) - AI-powered support chat using your help center articles.

## Features

- **AI Chat** - Answers questions using your help center content via RAG
- **Lightweight** - Small bundle, React as peer dependency
- **Two Modes** - Floating widget (Intercom-like) or inline chat component
- **Themeable** - Light, dark, auto themes with CSS variable customization
- **TypeScript-first** - Full type definitions out of the box
- **Open source** - [MIT licensed](https://github.com/kookee-dot-dev/kookee-react)

## Installation

```bash
npm install @kookee/react
# or
pnpm add @kookee/react
# or
yarn add @kookee/react
```

Don't forget to import the styles:

```typescript
import '@kookee/react/styles.css';
```

## Quick Start

### Floating Widget (Intercom-like)

```tsx
import { KookeeChatWidget } from '@kookee/react';
import '@kookee/react/styles.css';

function App() {
  return (
    <>
      {/* Your app */}
      <KookeeChatWidget
        clientOptions={{ apiKey: 'your-api-key' }}
        position="bottom-right"
        theme="auto"
        primaryColor="#6366f1"
        greeting="Hi! How can I help?"
        placeholder="Ask a question..."
        suggestions={['How do I get started?', 'What are the pricing plans?']}
      />
    </>
  );
}
```

### Inline Chat

```tsx
import { KookeeChat } from '@kookee/react';
import '@kookee/react/styles.css';

function SupportPage() {
  return (
    <div style={{ height: 500 }}>
      <KookeeChat
        clientOptions={{ apiKey: 'your-api-key' }}
        locale="en"
        suggestions={['How do I get started?']}
      />
    </div>
  );
}
```

## Components

### `KookeeChatWidget`

Floating bubble + chat panel. Props:

| Prop | Type | Default | Description |
|---|---|---|---|
| `clientOptions` | `{ apiKey: string }` | required | SDK client configuration |
| `position` | `'bottom-right' \| 'bottom-left'` | `'bottom-right'` | Widget position |
| `theme` | `'light' \| 'dark' \| 'auto'` | `'light'` | Color theme |
| `primaryColor` | `string` | `#6366f1` | Accent color |
| `greeting` | `string` | — | Welcome message |
| `placeholder` | `string` | `'Ask a question...'` | Input placeholder |
| `locale` | `string` | — | Locale for responses |
| `suggestions` | `string[]` | — | Quick-start suggestion pills |
| `onSourceClick` | `(source: HelpChatSource) => void` | — | Callback when user clicks a source |

### `KookeeChat`

Inline chat component (renders in parent container). Same props as above except `position` and `theme`.

### `KookeeChatProvider` + `useKookeeChat`

For advanced usage with custom layouts:

```tsx
import { KookeeChatProvider, useKookeeChat } from '@kookee/react';

function CustomChat() {
  const { messages, isLoading, sendMessage, isOpen, toggle } = useKookeeChat();
  // Build your own UI
}

function App() {
  return (
    <KookeeChatProvider clientOptions={{ apiKey: 'your-api-key' }}>
      <CustomChat />
    </KookeeChatProvider>
  );
}
```

## Theming

Customize via CSS variables:

```css
:root {
  --kookee-primary: #6366f1;
  --kookee-primary-hover: #4f46e5;
  --kookee-bg: #ffffff;
  --kookee-bg-secondary: #f9fafb;
  --kookee-text: #111827;
  --kookee-text-secondary: #6b7280;
  --kookee-border: #e5e7eb;
  --kookee-radius: 12px;
  --kookee-font-size: 14px;
}
```

## License

MIT