Add Tidio once in the document layout of a React Router framework app, or an existing Remix v2 app. You do not need a Tidio npm package. Checked with React Router 8.5.2 and 7.18.6 on React 19.3.1 and Vite 8.3.8, plus Remix 2.17.5 on React 18.3.1 and Vite 6.4.6.

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 React Router

These instructions use framework mode. If your app uses BrowserRouter with a Vite HTML entry point, follow Install Tidio on React instead.

Create .env in your project root. Replace the placeholder with your Public key, and provide the same variable when building your deployment:

VITE_TIDIO_KEY=YOUR_PUBLIC_KEY

In app/root.tsx, add the async script inside Layout, after Scripts. This complete minimal root shows its placement. Keep your existing styles, metadata, loaders, and error boundary when adding it to an existing app.

import { Links, Meta, Outlet, Scripts, ScrollRestoration } from "react-router";

export function Layout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <Meta />
        <Links />
      </head>
      <body>
        {children}
        <ScrollRestoration />
        <Scripts />
        <script src={`https://code.tidio.co/${import.meta.env.VITE_TIDIO_KEY}.js`} async />
      </body>
    </html>
  );
}

export default function App() {
  return <Outlet />;
}

The root Layout renders the document and stays mounted during client-side navigation. Vite puts the public key into the bundle through import.meta.env at build time. The same code was checked with React Router 8 and 7.

Existing Remix v2 apps

For a Remix v2 app using Vite, use the same .env and app/root.tsx layout above, but replace the first import with:

import { Links, Meta, Outlet, Scripts, ScrollRestoration } from "@remix-run/react";

Remix's root route and Layout export use the same document structure. This section is for existing Remix v2 projects. create-remix@latest no longer creates an app. It prints a notice that points to React Router.

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 React Router 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

To identify a visitor before the script loads, replace the static Tidio script with a browser effect. Create app/TidioChat.tsx:

import { useEffect } from "react";
export type Visitor = { distinct_id?: string; email?: string; name?: string; phone?: string };
declare global {
  interface Document { tidioIdentify?: Visitor }
  interface Window { tidioChatApi?: {
    on(event: "ready", callback: () => void): void;
    display(visible: boolean): void;
    setVisitorData(visitor: Omit<Visitor, "distinct_id">): void;
    resetVisitor(): void;
  } }
}
export function TidioChat({ visitor }: { visitor?: Visitor }) {
  useEffect(() => {
    if (document.querySelector('script[src^="https://code.tidio.co/"]')) return;
    const key = import.meta.env.VITE_TIDIO_KEY;
    if (!key) throw new Error("Set VITE_TIDIO_KEY before starting the app");
    if (visitor) document.tidioIdentify = visitor;
    const script = document.createElement("script");
    script.src = `https://code.tidio.co/${key}.js`;
    script.async = true;
    document.body.appendChild(script);
  }, [visitor]);
  return null;
}
export function updateVisitor(visitor: Omit<Visitor, "distinct_id">) {
  window.tidioChatApi?.setVisitorData(visitor);
}
export function resetVisitor() {
  delete document.tidioIdentify;
  window.tidioChatApi?.resetVisitor();
}

Import TidioChat from ./TidioChat in app/root.tsx. Remove the Tidio script tag, then render the component in its place. Pass only the authenticated visitor data you want to share with Tidio, using your app's existing authentication result instead of these example values:

<TidioChat visitor={{ distinct_id: "unique_id", email: "contact@example.com", name: "John Doe" }} />

If authentication loads in the browser, wait for it to finish before mounting TidioChat. The effect sets document.tidioIdentify before appending the script, so Tidio can merge conversations for that visitor. The script remains loaded across route changes.

Changing the prop after the script is present does not identify a new visitor. After the widget is ready, import and call updateVisitor from your successful login handler. It calls setVisitorData to update details without merging conversations. On logout, call resetVisitor, which deletes identification data before restarting the widget. Use the ready pattern below before calling these account functions.

Hide the widget on some pages

Create app/TidioVisibility.tsx. It reads the current route and hides the widget on /checkout, then shows it elsewhere:

import { useEffect } from "react";
import { useLocation } from "react-router";
import "./TidioChat";
export function TidioVisibility() {
  const { pathname } = useLocation();
  useEffect(() => {
    let active = true;
    const apply = () => { if (active) window.tidioChatApi?.display(pathname !== "/checkout"); };
    if (window.tidioChatApi) {
      apply();
      window.tidioChatApi.on("ready", apply);
    } else document.addEventListener("tidioChat-ready", apply);
    return () => { active = false; document.removeEventListener("tidioChat-ready", apply); };
  }, [pathname]);
  return null;
}

Import TidioVisibility from ./TidioVisibility in app/root.tsx and render <TidioVisibility /> inside the layout's body. Keep TidioChat.tsx for the shared types even if you use the static script rather than its loader component.

In Remix v2, replace the useLocation import in app/TidioVisibility.tsx with:

import { useLocation } from "@remix-run/react";

The readiness callback handles the initial load, and the effect handles client-side route changes. Hiding the widget does not stop Flows from triggering. See Show the widget only on specific pages.

Troubleshooting

  • If the script fails to load, check that VITE_TIDIO_KEY contains your Public key. Restart the development server after changing it, and rebuild for deployment.
  • If you see two widgets or duplicate script requests, keep only one installation method. Remove any older Tidio script before adding the component.
  • Keep window and document access inside effects or browser event handlers, not in server-rendered component bodies.
  • If your site uses a Content Security Policy, allow code.tidio.co in script-src and follow the full Tidio CSP host list.
  • If an automated test loads the script but shows no widget, check the site in a regular browser window.

Further reading