Add Tidio to your Next.js app with next/script, without an extra package. This guide uses the App Router and includes a Pages Router alternative. Checked with Next.js 16.4.6 and React 19.3.0.
In this article, you'll learn:
- How to find your Public key
- How to add the widget to Next.js
- How to check the installation
- How to identify logged-in visitors
- How to hide the widget on some pages
- How to troubleshoot the installation
Find your Public key
Log in to your Tidio panel and go to Settings > Developer > Project data. Click the Public key field to select its value, then copy it.
The Public key is part of the script address that every visitor's browser loads, so you can keep it in front-end code. The private key on the same page is different: never put it in your website.
You'll find the same key inside the installation code in Settings > Live Chat > Installation, under Manual install:
<script src="//code.tidio.co/YOUR_PUBLIC_KEY.js" async></script>
Add the widget to Next.js
Add this to .env.local at the project root, replacing the placeholder with your Public key:
NEXT_PUBLIC_TIDIO_KEY=YOUR_PUBLIC_KEY
Restart your development server after changing the key. Set the same variable in your deployment environment before building. Next.js includes public environment variables in the browser bundle at build time, so rebuild to change them.
Add the script once in app/layout.tsx, after your page content. Keep your existing styles, metadata and providers. This is a complete minimal layout:
import Script from 'next/script';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
{children}
<Script
src={`https://code.tidio.co/${process.env.NEXT_PUBLIC_TIDIO_KEY}.js`}
strategy="lazyOnload"
/>
</body>
</html>
);
}
Use lazyOnload because the Next.js Script documentation recommends loading chat support plugins during browser idle time, after other page resources.
Pages Router
If your app uses pages/ instead, add the script in pages/_app.tsx. Use this alternative, not both installations. Keep any existing global CSS imports and providers.
import type { AppProps } from 'next/app';
import Script from 'next/script';
export default function App({ Component, pageProps }: AppProps) {
return (
<>
<Component {...pageProps} />
<Script
src={`https://code.tidio.co/${process.env.NEXT_PUBLIC_TIDIO_KEY}.js`}
strategy="lazyOnload"
/>
</>
);
}
If an AI coding assistant edits this project for you, give it the prompt from Install Tidio with an AI coding agent.
Check the installation
Open your site in a regular browser window. The chat widget appears in the corner of the page and stays there when you move between pages. Headless and automated browsers may not show the widget, so do not rely on them for this check.
Loading a page with the widget is what activates it. After that, Settings > Live Chat > Installation in your Tidio panel says Chat Widget is installed properly.
Identify logged-in visitors
For the App Router, create components/TidioIdentity.tsx. It sets document.tidioIdentify before rendering the script. Pass the visitor from your authenticated session, or null for a signed-out visitor. If your session loads in the browser, wait for it to resolve before mounting this component.
'use client';
import Script from 'next/script';
import { useEffect, useState } from 'react';
type Visitor = { distinct_id: string; email?: string; name?: string };
declare global {
interface Document { tidioIdentify?: Visitor }
interface Window { tidioChatApi?: {
on(event: 'ready', callback: () => void): void;
display(visible: boolean): void;
setVisitorData(data: { email?: string; name?: string }): void;
resetVisitor(): void;
} }
}
export function updateTidioVisitor(data: { email?: string; name?: string }) {
window.tidioChatApi?.setVisitorData(data);
}
export function resetTidioVisitor() {
delete document.tidioIdentify;
window.tidioChatApi?.resetVisitor();
}
export default function TidioIdentity({ visitor }: { visitor: Visitor | null }) {
const [canLoad, setCanLoad] = useState(false);
useEffect(() => {
if (visitor) document.tidioIdentify = visitor;
else delete document.tidioIdentify;
setCanLoad(true);
}, [visitor]);
return canLoad ? <Script src={`https://code.tidio.co/${process.env.NEXT_PUBLIC_TIDIO_KEY}.js`} strategy="lazyOnload" /> : null;
}
Replace the original layout's Script with TidioIdentity, as shown in the combined layout below. Replace its example visitor data with your session data. Do not keep the original script alongside it.
Initial identification merges conversations for the same visitor. For a login after the widget is ready, call updateTidioVisitor({ email: 'contact@mail', name: 'John Doe' }) from your client-side login handler. This updates visitor data but does not merge conversations. After logout, call resetTidioVisitor() before another person uses the browser. It deletes the identification data before resetting the widget. Call these helpers only after the widget's ready event, not during rendering.
Hide the widget on some pages
Create components/TidioVisibility.tsx. It hides the widget on /checkout and shows it on other routes. The ready callback handles the first load, and the effect applies visibility again after client-side navigation. Its cleanup prevents older callbacks from applying a previous route's visibility.
'use client';
import { useEffect } from 'react';
import { usePathname } from 'next/navigation';
type ChatWindow = Window & { tidioChatApi?: {
on(event: 'ready', callback: () => void): void;
display(visible: boolean): void;
} };
export default function TidioVisibility() {
const pathname = usePathname();
useEffect(() => {
let active = true;
const chatWindow = window as ChatWindow;
const apply = () => {
if (active) chatWindow.tidioChatApi?.display(pathname !== '/checkout');
};
if (chatWindow.tidioChatApi) {
chatWindow.tidioChatApi.on('ready', apply);
apply();
} else document.addEventListener('tidioChat-ready', apply);
return () => {
active = false;
document.removeEventListener('tidioChat-ready', apply);
};
}, [pathname]);
return null;
}
This combined app/layout.tsx installs the identified widget and route visibility once. The Suspense boundary also covers routes whose pathname is not known during prerendering. To use visibility without identification, keep the original Script instead of TidioIdentity.
import { Suspense } from 'react';
import TidioIdentity from '@/components/TidioIdentity';
import TidioVisibility from '@/components/TidioVisibility';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
{children}
<TidioIdentity
visitor={{ distinct_id: 'unique_id', email: 'contact@mail', name: 'John Doe' }}
/>
<Suspense fallback={null}>
<TidioVisibility />
</Suspense>
</body>
</html>
);
}
Hiding the widget does not stop Flows from triggering. To load the widget only on a list of addresses instead, see Show the widget only on specific pages.
Troubleshooting
- Check that
NEXT_PUBLIC_TIDIO_KEYcontains your Public key, not the placeholder or private key. Rebuild after changing it. - If you see two widgets or duplicate script requests, remove the extra installation. Keep only one root-level script loader.
- If server rendering reports that
windowordocumentis undefined, move browser access into a client component's effect or event handler. - If your Content Security Policy blocks the script, allow
code.tidio.coinscript-srcand follow the full Tidio security policy. - If an automated test loads the script but shows no widget, check the site in a regular browser window.
