React / Next.js / Vite

Add TGLiveChat to your React app

One npm install. Drop the component anywhere in your tree. Works with React 16.8+, Next.js App Router, Vite, CRA, and React 19.

npm install @tglivechat/widget
Recommended

Option A — npm package

1

Install the package

$ npm install @tglivechat/widget
2

Add your widget ID to the environment

Copy your widget ID from the dashboard and add it to your environment file. Use the prefix your framework requires:

.env.local — Next.js

NEXT_PUBLIC_TGLIVECHAT_WIDGET_ID=your_widget_id

.env — Vite

VITE_TGLIVECHAT_WIDGET_ID=your_widget_id

.env — Create React App

REACT_APP_TGLIVECHAT_WIDGET_ID=your_widget_id
3

React / Vite / CRA — drop the component in your root

Import and render TGLiveChat in App.tsx. No props needed — it reads the env var automatically.

import { TGLiveChat } from '@tglivechat/widget'
export default function App() {
return (
<>
<YourApp />
<TGLiveChat />
</>
)
}
3

Next.js App Router — create a client wrapper

TGLiveChat uses browser APIs so it needs a "use client" boundary:

components/LiveChat.tsx

'use client'
import { TGLiveChat } from '@tglivechat/widget'
export default function LiveChat() {
return <TGLiveChat />
}

app/layout.tsx

import LiveChat from '@/components/LiveChat'
export default function RootLayout({ children }) {
return (
<html><body>
{children}
<LiveChat />
</body></html>
)
}

Component props

PropTypeDescription
widgetIdstring?Your widget ID. Optional if the env var is set.
colorstringAccent hex color override (e.g. "#FF5500").
privacyUrlstringLink to your privacy policy — shows a GDPR consent checkbox.
autoOpenbooleanOpen the chat window automatically on page load.
dir"ltr" | "rtl"Force text direction. Auto-detected by default.
titlestringOverride the header title.
subtitlestringOverride the header subtitle.
agentPhotostringOverride the agent avatar URL.
containerIdstringMount inside a specific element ID instead of body.
serverUrlstringCustom backend URL for self-hosted deployments.
Alternative

Option B — script tag (no npm)

Next.js — via next/script

Use in your root app/layout.tsx. No client wrapper needed.

import Script from 'next/script'
export default function RootLayout({ children }) {
return (
<html><body>
{children}
<Script
src="https://cdn.tglivechat.com/w.js"
data-id="YOUR_WIDGET_ID"
strategy="afterInteractive"
/>
</body></html>
)
}

Vite / CRA — via index.html

Open index.html in the project root and paste before </body>:

...
<script src="https://cdn.tglivechat.com/w.js" data-id="YOUR_WIDGET_ID" async defer></script>
</body>
</html>

Troubleshooting

Widget doesn't appear

Open DevTools Console — a missing ID logs an error telling you exactly which env var to set. Make sure your env var has the right prefix for your framework (NEXT_PUBLIC_, VITE_, or REACT_APP_) and that you restarted the dev server after adding it. If you have a Content Security Policy, add cdn.tglivechat.com to script-src and connect-src.

Next.js: "useState can only be used in a Client Component"

You're importing TGLiveChat directly in a Server Component. Create a wrapper file with "use client" at the top and import TGLiveChat there. Then import the wrapper in your layout.

Widget mounts twice in development

React StrictMode intentionally mounts components twice in development to surface side-effect bugs. The package handles this correctly — the second mount reuses the existing script and calls tglcBoot() directly. You'll see one widget, not two.

Messages not reaching Telegram

Open your dashboard and check that Telegram is connected (green badge). If you're routing to a group, make sure the bot is still an admin with Manage Topics permission.

← Back to all platformsContact support