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:

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 Project data page with the Public key field, masked private key and Visit widget SDK documentation button visible

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>
Settings > Live Chat > Installation with Manual install selected, the code snippet visible, and the Copy to clipboard button.

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.

Silent walkthrough. A demo Next.js site with the Tidio chat widget in the corner. The widget stays when the visitor returns to the home page and is hidden on the Checkout page.

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_KEY contains 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 window or document is undefined, move browser access into a client component's effect or event handler.
  • If your Content Security Policy blocks the script, allow code.tidio.co in script-src and 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.

Further reading