tawk-react-widget
v3.0.1
Published
Modern React component for Tawk.to messenger with TypeScript, React 19, and Next.js 13+ support
Maintainers
alphaoReadme
tawk-react-widget
✨ 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.