npm package: @monology-io/chat-widget
Description: Monology Chat Widget
Author: Monology
Latest version: 1.0.5

# @monology-io/chat-widget

[![npm version](https://img.shields.io/npm/v/@monology-io/chat-widget.svg)](https://www.npmjs.com/package/@monology-io/chat-widget)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

Official React/Next.js package for embedding the [Monology](https://monology.io) chat widget into your application. Build intelligent, conversational experiences with ease.

## 🚀 Features

- ✅ **React & Next.js Support** - Works seamlessly with both React and Next.js applications
- ✅ **TypeScript Ready** - Full TypeScript support with type definitions included
- ✅ **User Identity Tracking** - Pass authenticated user data for personalized experiences
- ✅ **Customizable** - Control widget behavior, appearance, and interactions
- ✅ **Lightweight** - Optimized bundle size with minimal dependencies
- ✅ **SSR Compatible** - Works with Next.js App Router and Pages Router

## 📦 Installation

```bash
npm install @monology-io/chat-widget
```

Or using yarn:

```bash
yarn add @monology-io/chat-widget
```

Or using pnpm:

```bash
pnpm add @monology-io/chat-widget
```

## 🎯 Quick Start

### Basic React Usage

```jsx
import { RenderWidget } from "@monology-io/chat-widget";

export default function App() {
  return (
    <div className="App">
      <RenderWidget urlId="your-widget-url-id" identity={null} />
    </div>
  );
}
```

### Next.js App Router (Recommended)

For Next.js 13+ with App Router, use dynamic import with SSR disabled:

```jsx
"use client";
import dynamic from "next/dynamic";

const RenderWidget = dynamic(
  () => import("@monology-io/chat-widget").then((mod) => mod.RenderWidget),
  { ssr: false },
);

export default function App() {
  return (
    <div className="App">
      <RenderWidget urlId="your-widget-url-id" identity={null} />
    </div>
  );
}
```

### Next.js Pages Router

```jsx
import { RenderWidget } from "@monology-io/chat-widget";

export default function Home() {
  return (
    <div>
      <h1>My App</h1>
      <RenderWidget urlId="your-widget-url-id" identity={null} />
    </div>
  );
}
```

## 📖 Usage Examples

### With User Identity

Pass authenticated user information for personalized conversations and tracking:

```jsx
import { RenderWidget } from "@monology-io/chat-widget";

export default function App() {
  return (
    <div className="App">
      <RenderWidget
        urlId="your-widget-url-id"
        identity={{
          id: "user-123",
          firstName: "John",
          lastName: "Doe",
          email: "john.doe@example.com",
          phone: "1234567890",
          company: {
            id: "company-456",
            name: "Acme Inc",
          },
        }}
      />
    </div>
  );
}
```

### Manual Control (Custom Trigger Button)

Control when the widget opens and closes with your own UI:

```jsx
import { RenderWidget } from "@monology-io/chat-widget";
import { useState } from "react";

export default function App() {
  const [isWidgetOpen, setIsWidgetOpen] = useState(false);

  return (
    <div className="App">
      <button onClick={() => setIsWidgetOpen(true)}>Open Chat Support</button>

      {isWidgetOpen && (
        <RenderWidget
          urlId="your-widget-url-id"
          onClose={() => setIsWidgetOpen(false)}
          hideLauncherButton={true}
          identity={null}
        />
      )}
    </div>
  );
}
```

### TypeScript Example

```tsx
import { RenderWidget } from "@monology-io/chat-widget";
import type { Identity } from "@monology-io/chat-widget";

interface Props {
  user: Identity | null;
}

export default function ChatWidget({ user }: Props) {
  return <RenderWidget urlId="your-widget-url-id" identity={user} />;
}
```

## 🔧 API Reference

### `<RenderWidget />` Props

| Prop                 | Type               | Required | Default | Description                                    |
| -------------------- | ------------------ | -------- | ------- | ---------------------------------------------- |
| `urlId`              | `string`           | ✅ Yes   | -       | Your widget URL ID from the Monology dashboard |
| `identity`           | `Identity \| null` | ❌ No    | `null`  | User identity object for authenticated users   |
| `hideLauncherButton` | `boolean`          | ❌ No    | `false` | Hide the default launcher button               |
| `onClose`            | `() => void`       | ❌ No    | -       | Callback function when widget is closed        |

### `Identity` Object

```typescript
interface Identity {
  id: string; // Unique user identifier
  firstName?: string; // User's first name
  lastName?: string; // User's last name
  email?: string; // User's email address
  phone?: string; // User's phone number
  company?: {
    id: string; // Company identifier
    name: string; // Company name
  };
}
```

## ⚠️ Important CSS Warning

**The host site should NOT have CSS directly applied to semantic HTML elements** like `p`, `a`, `ul`, `li`, `h1-h6`, etc.

### Why?

Global CSS rules on these elements will conflict with the widget's internal styles and disturb its appearance.

### Solution

Use CSS classes or scoped styles instead of element selectors. For example:

- ❌ Bad: `p { margin: 0; }`
- ✅ Good: `.my-paragraph { margin: 0; }`

## 🌟 Best Practices

1. **Load Asynchronously** - Use dynamic imports in Next.js to avoid blocking initial page load
2. **Pass User Data When Available** - If users are logged in, pass their identity to enable tracking and skip verification
3. **Test on Staging First** - Verify the widget works correctly before deploying to production
4. **Handle Errors Gracefully** - Wrap the widget in error boundaries for production apps
5. **Optimize Bundle Size** - Use tree-shaking and code splitting to minimize impact

## 📚 Documentation

For complete documentation, visit:

- [Monology Documentation](https://app.monology.io/docs)
- [Embedding Guide](https://app.monology.io/docs/widgets/embedding)
- [Widget Configuration](https://app.monology.io/docs/widgets)

## 🔗 Links

- [Website](https://monology.io)
- [Dashboard](https://app.monology.io)
- [Documentation](https://app.monology.io/docs)
- [npm Package](https://www.npmjs.com/package/@monology-io/chat-widget)

## 🆘 Support

Need help? We're here for you:

- 📧 Email: [contact@monology.io](mailto:contact@monology.io)
- 💬 Chat: [monology.io](https://monology.io) (use our own widget!)
- 📖 Docs: [app.monology.io/docs](https://app.monology.io/docs)

## 📝 License

MIT © [Monology](https://monology.io)

---

Made with ❤️ by the [Monology](https://monology.io) team