@ihoomanai/react-chat
v3.0.12
Published
React components and hooks for Ihooman Chat Widget - secure Widget ID based initialization
Maintainers
ihoomanReadme
@ihoomanai/react-chat
React components and hooks for the Ihooman Chat Widget. Provides native React integration with proper lifecycle management and SSR compatibility.
Installation
npm install @ihoomanai/react-chat
# or
yarn add @ihoomanai/react-chat
# or
pnpm add @ihoomanai/react-chatRequirements
- React 17.0.0 or higher
- A valid Widget ID from your Ihooman Dashboard
Quick Start
Basic Usage
import { ChatWidget } from '@ihoomanai/react-chat';
function App() {
return (
<ChatWidget
widgetId="wgt_abc123def456"
position="bottom-right"
onReady={() => console.log('Widget ready!')}
/>
);
}With Provider and Hook
For programmatic control over the widget from any component:
import { ChatWidgetProvider, ChatWidget, useChatWidget } from '@ihoomanai/react-chat';
function SupportButton() {
const { open, isReady } = useChatWidget();
return (
<button onClick={open} disabled={!isReady}>
Need Help?
</button>
);
}
function App() {
return (
<ChatWidgetProvider>
<ChatWidget widgetId="wgt_abc123def456" />
<SupportButton />
</ChatWidgetProvider>
);
}Components
<ChatWidget />
The main component that renders the chat widget.
Props
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| widgetId | string | Yes | Your Widget ID from the Ihooman dashboard |
| serverUrl | string | No | Custom server URL (defaults to production) |
| theme | 'light' \| 'dark' | No | Color theme |
| position | 'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left' | No | Widget position |
| startOpen | boolean | No | Start with widget open |
| user | { name?: string; email?: string; metadata?: Record<string, string> } | No | User information |
| onReady | () => void | No | Called when widget is ready |
| onOpen | () => void | No | Called when widget opens |
| onClose | () => void | No | Called when widget closes |
| onMessage | (message: Message) => void | No | Called on new messages |
| onError | (error: Error) => void | No | Called on errors |
<ChatWidgetProvider />
Context provider for global widget access. Wrap your app with this to use the useChatWidget hook.
<ChatWidgetProvider>
{/* Your app components */}
</ChatWidgetProvider>Hooks
useChatWidget()
Hook for controlling the widget from any component within the provider.
const {
isOpen, // boolean - Whether widget is open
isReady, // boolean - Whether widget is initialized
isConnected, // boolean - Whether connected to server
open, // () => void - Open the widget
close, // () => void - Close the widget
toggle, // () => void - Toggle open/closed
sendMessage, // (content: string) => void - Send a message
setUser, // (user: UserInfo) => void - Set user info
clearHistory,// () => void - Clear chat history
messages, // Message[] - Current messages
unreadCount, // number - Unread message count
} = useChatWidget();Examples
With User Information
<ChatWidget
widgetId="wgt_abc123def456"
user={{
name: 'John Doe',
email: '[email protected]',
metadata: {
plan: 'premium',
customerId: 'cust_123'
}
}}
/>Custom Styling
<ChatWidget
widgetId="wgt_abc123def456"
primaryColor="#6366f1"
gradientFrom="#6366f1"
gradientTo="#8b5cf6"
borderRadius={16}
fontFamily="Inter, sans-serif"
/>Programmatic Messages
function QuickActions() {
const { sendMessage, isReady } = useChatWidget();
return (
<div>
<button
onClick={() => sendMessage('I need help with my order')}
disabled={!isReady}
>
Order Help
</button>
<button
onClick={() => sendMessage('How do I reset my password?')}
disabled={!isReady}
>
Password Help
</button>
</div>
);
}Next.js / SSR
The component is SSR-compatible and defers initialization to the client:
// app/layout.tsx (App Router)
import { ChatWidgetProvider, ChatWidget } from '@ihoomanai/react-chat';
export default function RootLayout({ children }) {
return (
<html>
<body>
<ChatWidgetProvider>
{children}
<ChatWidget widgetId="wgt_abc123def456" />
</ChatWidgetProvider>
</body>
</html>
);
}// pages/_app.tsx (Pages Router)
import { ChatWidgetProvider, ChatWidget } from '@ihoomanai/react-chat';
export default function App({ Component, pageProps }) {
return (
<ChatWidgetProvider>
<Component {...pageProps} />
<ChatWidget widgetId="wgt_abc123def456" />
</ChatWidgetProvider>
);
}TypeScript
Full TypeScript support is included. Import types as needed:
import type {
ChatWidgetProps,
UseChatWidgetReturn,
Message,
UserInfo
} from '@ihoomanai/react-chat';Framework Compatibility
- ✅ React 17+
- ✅ React 18+
- ✅ Next.js (Pages & App Router)
- ✅ Gatsby
- ✅ Remix
- ✅ Vite
- ✅ Create React App
License
MIT © Ihooman AI