@monology-io/chat-widget

Official React/Next.js package for embedding the Monology 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

npm install @monology-io/chat-widget

Or using yarn:

yarn add @monology-io/chat-widget

Or using pnpm:

pnpm add @monology-io/chat-widget

🎯 Quick Start

Basic React Usage

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:

"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

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:

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: "[email protected]",
          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:

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

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

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
• Embedding Guide
• Widget Configuration

🔗 Links

• Website
• Dashboard
• Documentation
• npm Package

🆘 Support

Need help? We're here for you:

• 📧 Email: [email protected]
• 💬 Chat: monology.io (use our own widget!)
• 📖 Docs: app.monology.io/docs

📝 License

MIT © Monology

Made with ❤️ by the Monology team