# Install Tidio on TanStack Start

Section: Install Tidio

Description: Add the Tidio widget to TanStack Start or a Vite TanStack Router app, 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-tanstack-start/

Add Tidio once in your TanStack Start root route, without an npm package. This guide also covers client-only TanStack Router apps on Vite. Checked with TanStack Start 1.169.5, TanStack Router 1.170.46, React 19.3.1, and Vite 8.3.8.

**In this article, you'll learn:**

- [How to find your Public key](https://help.tidio.com/articles/install-tanstack-start/#public-key)
- [How to add the widget to TanStack Start](https://help.tidio.com/articles/install-tanstack-start/#install)
- [How to check the installation](https://help.tidio.com/articles/install-tanstack-start/#check)
- [How to identify logged-in visitors](https://help.tidio.com/articles/install-tanstack-start/#identify-visitors)
- [How to hide the widget on some pages](https://help.tidio.com/articles/install-tanstack-start/#hide-on-pages)
- [How to troubleshoot the installation](https://help.tidio.com/articles/install-tanstack-start/#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-tanstack-start/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-tanstack-start/installation-manual-install.png)

## Add the widget to TanStack Start

Add your Public key to ` .env ` in the project root. Replace ` YOUR_PUBLIC_KEY ` with your key. Vite exposes variables prefixed with ` VITE_ ` to the browser. Restart development after changing this file, and rebuild your production deployment.

```
VITE_TIDIO_KEY=YOUR_PUBLIC_KEY
```

In ` src/routes/__root.tsx `, declare the script in the root route's ` scripts ` option. Keep ` HeadContent ` in the head and ` Scripts ` at the end of the body. This minimal root file shows the complete installation. Merge these changes into your existing root without removing its metadata, styles, or providers.

```
import { HeadContent, Scripts, createRootRoute } from '@tanstack/react-router'

export const Route = createRootRoute({
  head: () => ({ meta: [{ charSet: 'utf-8' }, { title: 'My app' }] }),
  scripts: () => [{
    src: `https://code.tidio.co/${import.meta.env.VITE_TIDIO_KEY}.js`,
    async: true,
  }],
  shellComponent: RootDocument,
})

function RootDocument({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head><HeadContent /></head>
      <body>{children}<Scripts /></body>
    </html>
  )
}
```

### Client-only TanStack Router on Vite

Use the same ` .env ` value. Add this line to ` index.html ` just before ` </body> `, after the existing module script. Vite replaces ` %VITE_TIDIO_KEY% ` during the build. Do not also add the Start root-route script.

```
<script src="https://code.tidio.co/%VITE_TIDIO_KEY%.js" async></script>
```

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-tanstack-start/walkthrough.mp4)

Silent walkthrough. A demo TanStack Start 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

Set ` document.tidioIdentify ` before creating the Tidio script. React can move an async script into the head, so placing an identification script beside the basic installation does not guarantee ordering.

For Start, remove the root route's ` scripts ` option from the installation above. Add ` ScriptOnce ` to the imports from ` @tanstack/react-router `, then replace the root document's head with this code. It sets identification and creates the external script in one ordered operation.

The visitor values below demonstrate an already authenticated session. Replace them with the current visitor's data from your authentication flow, available when the root renders. Do not send these example values for every visitor. If authentication finishes after the widget loads, use the update function below instead.

```
<head><HeadContent /><ScriptOnce children={`document.tidioIdentify = ${JSON.stringify({
        distinct_id: 'unique_id', email: 'contact@mail', name: 'John Doe',
      }).replace(/</g, '\\u003c')};
const script = document.createElement('script');
script.src = ${JSON.stringify(`https://code.tidio.co/${import.meta.env.VITE_TIDIO_KEY}.js`)};
script.async = true;
document.head.appendChild(script);`} /></head>
```

Tidio uses ` distinct_id ` to merge conversations for the same visitor. Create ` src/tidio.ts ` for the browser-side API types and login/logout handlers:

```
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(visitor: Visitor): void
    resetVisitor(): void
  } }
}
export function updateTidioVisitor(visitor: Visitor) {
  window.tidioChatApi?.setVisitorData(visitor)
}
export function resetTidioVisitor() {
  delete document.tidioIdentify
  window.tidioChatApi?.resetVisitor()
}
```

After a later login, call ` updateTidioVisitor({ email, name }) ` from your browser-side authentication handler once the widget has loaded. This updates visitor data but does not merge conversations. On logout, call ` resetTidioVisitor() `. It deletes identification before resetting, because the restart reads that data again. Do not call these functions during server rendering.

## Hide the widget on some pages

Create ` src/TidioVisibility.tsx `. It uses the API types in ` src/tidio.ts ` above. Change ` /checkout ` to the path you want to hide. The immediate call covers a widget that has already loaded, and the ready callback covers one that is still loading.

```
import { useEffect } from 'react'
import { useLocation } from '@tanstack/react-router'
import './tidio'

export function TidioVisibility() {
  const pathname = useLocation({ select: location => location.pathname })
  useEffect(() => {
    let active = true
    const apply = () => {
      if (active) window.tidioChatApi?.display(pathname !== '/checkout')
    }
    if (window.tidioChatApi) {
      window.tidioChatApi.on('ready', apply)
      apply()
    } else {
      document.addEventListener('tidioChat-ready', apply)
    }
    return () => {
      active = false
      document.removeEventListener('tidioChat-ready', apply)
    }
  }, [pathname])
  return null
}
```

Import ` TidioVisibility ` from ` ../TidioVisibility ` in ` src/routes/__root.tsx ` and render ` <TidioVisibility /> ` after ` {children} `, before ` <Scripts /> `. It stays mounted while the location hook tracks navigation.

Hiding the widget does not stop Flows from triggering. See [Show the widget only on specific pages](https://help.tidio.com/articles/show-widget-only-on-specific-pages/) for other visibility options.

## Troubleshooting

- Check that ` VITE_TIDIO_KEY ` contains your Public key, not the placeholder, then rebuild.
- If you see two widgets or duplicate script requests, remove extra installations from nested routes, components, or HTML. Use only one loading approach.
- Keep direct ` window ` and ` document ` access in effects, browser event handlers, or the inline script string, not server-rendered component code.
- If your Content Security Policy blocks the widget, allow ` code.tidio.co ` in ` script-src ` and follow the [Tidio CSP host list](https://developers.tidio.com/docs/widget-security-policy). The identification example also needs your policy to permit its inline script.
- Check the deployed site in a regular browser. Headless browsers may load the API without showing the widget.

## Further reading

- [Install Tidio on your website](https://help.tidio.com/articles/install-website/)
- [Widget SDK](https://help.tidio.com/articles/widget-sdk/)
- [Install Tidio with an AI coding agent](https://help.tidio.com/articles/install-ai-coding-agents/)
- [TanStack document head management](https://tanstack.com/router/latest/docs/framework/react/guide/document-head-management)
