tawk-react-widget

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

``bash


npm

npm install tawk-react-widget

yarn

yarn add tawk-react-widget

pnpm

pnpm add tawk-react-widget
`

🚀 Quick Start

$3

`tsx
import TawkMessenger from 'tawk-react-widget';

function App() {
return (


);
}

export default App;
`

$3

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

export default function RootLayout({ children }: { children: React.ReactNode }) {
return (


{children}



);
}
`

$3

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

export default function App({ Component, pageProps }: AppProps) {
return (
<>



);
}
`

🎯 Getting Your Credentials

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

📖 Usage with Ref

Control the widget programmatically using refs:

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

function App() {
const tawkRef = useRef(null);

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

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

return (



);
}
`

🔧 API Reference

$3

| 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 |

$3

All methods are available through the component ref:

`typescript
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): void;
setAttributes(attributes: Record, callback?: (error: Error | null) => void): void;
addEvent(
event: string,
metadata?: Record,
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:

- Next.js App Router
- Next.js Pages Router
- React with Ref
- Full TypeScript Example

🧪 Testing

`bash


Run tests

npm test

Run tests in watch mode

npm run test:watch

Generate coverage report

npm run test:coverage
`

🏗️ Building

`bash


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

- Tawk.to Website
- Tawk.to JavaScript API Documentation
- GitHub Repository
- npm Package

💬 Support

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