JSPM – tawk-react-widget@3.0.1

Package Exports

tawk-react-widget
tawk-react-widget/nextjs

Readme

Modern React component for Tawk.to live chat messenger

✨ Features

⚛️ React 19 Support - Full compatibility with the latest React version
📘 TypeScript First - Written in TypeScript with comprehensive type definitions
⚡ Next.js 13+ Ready - Built-in support for both App Router and Pages Router
🪝 React Hooks - Modern hooks-based API
🎯 Fully Typed API - All Tawk.to JavaScript API methods with TypeScript support
📦 Zero Dependencies - No external runtime dependencies (except React peer deps)
🔧 ESM & CJS - Dual module format support
🧪 Well Tested - Comprehensive test coverage with Vitest
📝 Documented - Extensive documentation and examples
🚀 Optimized - Small bundle size, tree-shakeable

📦 Installation

# npm
npm install tawk-react-widget

# yarn
yarn add tawk-react-widget

# pnpm
pnpm add tawk-react-widget

🚀 Quick Start

Basic Usage (React)

import TawkMessenger from 'tawk-react-widget';

function App() {
  return (
    <div className="App">
      <h1>My Application</h1>
      <TawkMessenger propertyId="YOUR_PROPERTY_ID" widgetId="YOUR_WIDGET_ID" />
    </div>
  );
}

export default App;

Next.js 13+ (App Router)

// app/layout.tsx
import { TawkMessenger } from 'tawk-react-widget/nextjs';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <TawkMessenger propertyId="YOUR_PROPERTY_ID" widgetId="YOUR_WIDGET_ID" />
      </body>
    </html>
  );
}

Next.js (Pages Router)

// pages/_app.tsx
import type { AppProps } from 'next/app';
import { TawkMessenger } from 'tawk-react-widget/nextjs';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Component {...pageProps} />
      <TawkMessenger propertyId="YOUR_PROPERTY_ID" widgetId="YOUR_WIDGET_ID" />
    </>
  );
}

🎯 Getting Your Credentials

Log in to your Tawk.to Dashboard
Go to Administration → Channels → Chat Widget
Copy your Property ID and Widget ID

📖 Usage with Ref

Control the widget programmatically using refs:

import { useRef } from 'react';
import TawkMessenger, { TawkMessengerRef } from 'tawk-react-widget';

function App() {
  const tawkRef = useRef<TawkMessengerRef>(null);

  const handleOpenChat = () => {
    tawkRef.current?.maximize();
  };

  const handleMinimizeChat = () => {
    tawkRef.current?.minimize();
  };

  return (
    <div>
      <button onClick={handleOpenChat}>Open Chat</button>
      <button onClick={handleMinimizeChat}>Minimize Chat</button>

      <TawkMessenger ref={tawkRef} propertyId="YOUR_PROPERTY_ID" widgetId="YOUR_WIDGET_ID" />
    </div>
  );
}

🔧 API Reference

Props

Prop	Type	Required	Default	Description
`propertyId`	`string`	✅	-	Your Tawk.to Property ID
`widgetId`	`string`	✅	-	Your Tawk.to Widget ID
`embedId`	`string`	❌	`''`	ID for embedded widget mode
`basePath`	`string`	❌	`'tawk.to'`	Custom base path for self-hosted
`autoStart`	`boolean`	❌	`true`	Auto-start the widget
`customStyle`	`object`	❌	`undefined`	Custom widget styling
`onLoad`	`() => void`	❌	-	Called when widget loads
`onStatusChange`	`(status: string) => void`	❌	-	Called when status changes
`onChatStarted`	`() => void`	❌	-	Called when chat starts
`onChatEnded`	`() => void`	❌	-	Called when chat ends
`onChatMaximized`	`() => void`	❌	-	Called when chat is maximized
`onChatMinimized`	`() => void`	❌	-	Called when chat is minimized
`onChatMessageVisitor`	`(message: string) => void`	❌	-	Called on visitor message
`onChatMessageAgent`	`(message: string) => void`	❌	-	Called on agent message

Ref Methods

All methods are available through the component ref:

interface TawkMessengerRef {
  // Widget Control
  maximize(): void;
  minimize(): void;
  toggle(): void;
  popup(): void;
  showWidget(): void;
  hideWidget(): void;
  toggleVisibility(): void;
  endChat(): void;

  // Widget State
  getWindowType(): 'inline' | 'popup' | null;
  getStatus(): 'online' | 'away' | 'offline';
  isChatMaximized(): boolean;
  isChatMinimized(): boolean;
  isChatHidden(): boolean;
  isChatOngoing(): boolean;
  isVisitorEngaged(): boolean;

  // Visitor Management
  setVisitor(data: Record<string, any>): void;
  setAttributes(attributes: Record<string, any>, callback?: (error: Error | null) => void): void;
  addEvent(
    event: string,
    metadata?: Record<string, any>,
    callback?: (error: Error | null) => void
  ): void;
  addTags(tags: string[], callback?: (error: Error | null) => void): void;
  removeTags(tags: string[], callback?: (error: Error | null) => void): void;
}

📚 Examples

Check out the examples directory for more detailed examples:

🧪 Testing

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

🏗️ Building

# Build the package
npm run build

# Type check
npm run typecheck

📄 Documentation

For detailed documentation, see:

How to Use - Comprehensive usage guide
API Reference - Complete API documentation

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📝 License

This project is licensed under the Apache-2.0 License - see the LICENSE file for details.

🙏 Credits

This package is a modern TypeScript fork of @tawk.to/tawk-messenger-react with additional features and improvements.

🔗 Links

💬 Support

For issues, questions, or contributions, please visit our GitHub Issues.