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
- How to add the widget to TanStack Start
- 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 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.
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
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 for other visibility options.
Troubleshooting
- Check that
VITE_TIDIO_KEYcontains 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
windowanddocumentaccess 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.coinscript-srcand follow the Tidio CSP host list. 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.
