@tglivechat/widget
v1.1.0
Published
TGLiveChat React component
Maintainers
tglivechatReadme
@tglivechat/widget
The official React and Next.js component for TGLiveChat.
If you are looking for the best alternative to Intercom for React, or you want a completely free customer support live chat widget that links directly to your Telegram, this is the package.
TGLiveChat is a frictionless, zero-bloat customer support widget that routes website visitor messages directly into your Telegram account (or a group). You reply to customers simply by texting them back on Telegram — no bulky dashboards, no hidden seats, just instant communication.
Installation
npm install @tglivechat/widget
# or
yarn add @tglivechat/widget
# or
pnpm add @tglivechat/widgetUsage (React / Next.js Client Components)
Since TGLiveChat relies on the browser document, ensure this component is rendered on the client side (e.g., using 'use client' in Next.js App Router).
'use client'
import { TGLiveChat } from '@tglivechat/widget'
export default function App() {
return (
<>
<main>
<h1>My Awesome App</h1>
</main>
{/* Best practice: Use an environment variable for your ID */}
<TGLiveChat widgetId={process.env.NEXT_PUBLIC_TGLIVECHAT_WIDGET_ID || ''} />
</>
)
}Environment Variables (Vercel / Netlify)
When deploying to Vercel, Netlify, or similar platforms, it's a standard practice to store your Widget ID in your environment variables.
For Next.js / Create React App:
Add this to your .env or Vercel project settings:
NEXT_PUBLIC_TGLIVECHAT_WIDGET_ID=your-widget-id-hereFor Vite:
VITE_TGLIVECHAT_WIDGET_ID=your-widget-id-hereThen use import.meta.env.VITE_TGLIVECHAT_WIDGET_ID within your component.
Next.js App Router Alternate (Zero Bundle Impact)
If you strictly want zero JavaScript bundle impact in Next.js, we highly recommend using Next.js's built-in target component instead of importing React components:
import Script from 'next/script'
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
{children}
<Script
src="https://cdn.tglivechat.com/w.js"
data-id="YOUR_WIDGET_ID"
strategy="afterInteractive"
/>
</body>
</html>
)
}Props / Configuration
All visual settings (colors, theme, auto-open logic, welcome messages) should ideally be configured via your TGLiveChat Dashboard. However, you can use props for dynamic or code-level overrides:
| Prop | Type | Description |
| :--- | :--- | :--- |
| widgetId (required)| string | The unique ID of your TGLiveChat widget. |
| color | string | Override the widget's accent color (e.g., "#FF5500"). |
| title | string | Override the header title. |
| subtitle | string | Override the header subtitle. |
| agentPhoto | string | Override the agent avatar URL shown in the header. |
| privacyUrl | string | Link to your Privacy Policy. Enabled GDPR checkbox. |
| dir | "ltr" | "rtl" | Force text direction. Defaults to auto-detecting HTML dir. |
| autoOpen | boolean | Automatically crack open the chat window on initial load. |
| containerId | string | ID of a DOM element to inject the chat popup into (defaults to document.body). |
Architecture Security
The TGLiveChat widget is isolated completely within a Shadow DOM. This prevents your app's global CSS (like Tailwind resets) from breaking the chat UI, and prevents the widget's CSS from bleeding into your app.