React Integration Guide
This guide shows you how to add Heyo to your React application. Works with Create React App, Vite, and any React setup.
Installation
Method 1: JavaScript SDK (Recommended)
Install the SDK for full TypeScript support and programmatic control:
npm install @heyo.so/js
Then initialize it in your App component:
import { useEffect } from 'react';
import HEYO from '@heyo.so/js'; // or: import { HEYO } from '@heyo.so/js'
function App() {
useEffect(() => {
HEYO.init({ projectId: 'YOUR_PROJECT_ID' });
}, []);
return <div className="App">{/* Your app content */}</div>;
}
export default App;
Method 2: Script Tag with useEffect
Load the script tag dynamically in your App component:
import { useEffect } from 'react';
function App() {
useEffect(() => {
const script = document.createElement('script');
script.src = 'https://heyo.so/embed/script';
script.defer = true;
script.setAttribute('data-project-id', 'YOUR_PROJECT_ID');
document.head.appendChild(script);
return () => {
document.head.removeChild(script);
};
}, []);
return <div className="App">{/* Your app content */}</div>;
}
export default App;
TypeScript Support
The Heyo SDK includes TypeScript definitions. For the script method, you can add type definitions:
declare global {
interface Window {
HEYO: {
init: (config: { projectId: string }) => void;
show: () => void;
hide: () => void;
toggle: () => void;
};
}
}
Advanced Usage
Control the Widget with Hooks
Create a custom hook to control the chat widget:
import { useEffect } from 'react';
const useChatWidget = () => {
useEffect(() => {
// Widget will be available after initialization
return () => {
window.HEYO?.hide();
};
}, []);
const showChat = () => window.HEYO?.show();
const hideChat = () => window.HEYO?.hide();
const toggleChat = () => window.HEYO?.toggle();
return { showChat, hideChat, toggleChat };
};
// Usage in component
function MyComponent() {
const { showChat } = useChatWidget();
return <button onClick={showChat}>Open Chat</button>;
}
Send User Data
Pass user context to provide better support:
useEffect(() => {
HEYO.init({
projectId: 'YOUR_PROJECT_ID',
user: {
name: 'John Doe',
email: '[email protected]',
},
});
}, []);
Best Practices
- Load Heyo in your root App component to ensure it's available throughout your app
- Use the
deferattribute to avoid blocking page rendering - Clean up the script in useEffect's cleanup function if loading dynamically
- For SPAs, the widget will persist across route changes automatically
Troubleshooting
Widget not showing
Make sure you've added your correct Project ID and the script is loading after the DOM is ready.
Multiple instances
If you're seeing multiple widgets, ensure you're only initializing Heyo once in your app.
React StrictMode double rendering
In development, React StrictMode may cause useEffect to run twice. This is normal and won't affect production.