# Install Tidio on Next.js

Section: Install Tidio

Description: Add the Tidio chat widget to Next.js with App Router or Pages Router, identify visitors, and control visibility on client-side routes.

Verified against Tidio panel 12.331.0

Last updated: 2026-11-18

Source: https://help.tidio.com/articles/install-nextjs/

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](https://help.tidio.com/articles/install-nextjs/#public-key)
- [How to add the widget to Next.js](https://help.tidio.com/articles/install-nextjs/#install)
- [How to check the installation](https://help.tidio.com/articles/install-nextjs/#check)
- [How to identify logged-in visitors](https://help.tidio.com/articles/install-nextjs/#identify-visitors)
- [How to hide the widget on some pages](https://help.tidio.com/articles/install-nextjs/#hide-on-pages)
- [How to troubleshoot the installation](https://help.tidio.com/articles/install-nextjs/#troubleshooting)

## 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](https://help.tidio.com/article-media/install-nextjs/project-data-public-key.png)

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.](https://help.tidio.com/article-media/install-nextjs/installation-manual-install.png)

## 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](https://nextjs.org/docs/app/api-reference/components/script#lazyonload) 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](https://help.tidio.com/articles/install-ai-coding-agents/).

## 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**.

[Video](https://help.tidio.com/article-media/install-nextjs/walkthrough.mp4)

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](https://help.tidio.com/articles/show-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](https://developers.tidio.com/docs/widget-security-policy).
- If an automated test loads the script but shows no widget, check the site in a regular browser window.

## Further reading

- [Install Tidio on a website](https://help.tidio.com/articles/install-website/)
- [Widget SDK](https://help.tidio.com/articles/widget-sdk/)
- [Show the widget only on specific pages](https://help.tidio.com/articles/show-widget-only-on-specific-pages/)
- [Install Tidio with an AI coding agent](https://help.tidio.com/articles/install-ai-coding-agents/)
