Add Tidio to your Qwik City app with one script in the root component. You do not need a package for Tidio. Checked with Qwik 1.20.4 and Qwik City 1.20.4.
In this article, you'll learn:
- How to find your Public key
- How to add the widget to Qwik
- 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 Qwik
In src/root.tsx, add this script at the end of <body>, after <RouterOutlet />. Keep your existing head, styles and QwikCityProvider. Replace YOUR_PUBLIC_KEY with your Public key:
<script src="https://code.tidio.co/YOUR_PUBLIC_KEY.js" async />
Keep this script in the root, not in individual route components. Use Qwik City's Link component for client-side navigation.
Use a public environment variable instead
Set PUBLIC_TIDIO_KEY=YOUR_PUBLIC_KEY in your build environment. Replace the script above with this version:
<script src={`https://code.tidio.co/${import.meta.env.PUBLIC_TIDIO_KEY}.js`} async />
Qwik exposes variables prefixed with PUBLIC_ to the browser at build time. Rebuild after changing the key. Never use this prefix for a private key.
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
Use this alternative when you need visitor identification or route visibility. Remove the script from src/root.tsx first. Set PUBLIC_TIDIO_KEY as above and create src/components/tidio.tsx:
import { component$, useSignal, useVisibleTask$ } from '@builder.io/qwik';
import { useLocation } from '@builder.io/qwik-city';
type Visitor = { distinct_id?: string; email?: string; name?: string };
declare global {
interface Document { tidioIdentify?: Visitor }
interface Window {
tidioChatApi?: {
on(event: string, callback: () => void): void;
display(visible: boolean): void;
setVisitorData(data: { email?: string; name?: string }): void;
resetVisitor(): void;
};
}
}
export const Tidio = component$<{ user: Visitor | null }>(({ user }) => {
const location = useLocation();
const ready = useSignal(false);
useVisibleTask$(({ cleanup }) => {
const onReady = () => { ready.value = true; };
if (window.tidioChatApi) window.tidioChatApi.on('ready', onReady);
else document.addEventListener('tidioChat-ready', onReady);
if (!document.querySelector('script[src*="code.tidio.co"]')) {
if (user) document.tidioIdentify = user;
const script = document.createElement('script');
script.src = `https://code.tidio.co/${import.meta.env.PUBLIC_TIDIO_KEY}.js`;
script.async = true;
document.body.appendChild(script);
}
cleanup(() => document.removeEventListener('tidioChat-ready', onReady));
}, { strategy: 'document-ready' });
useVisibleTask$(({ track }) => {
const pathname = track(() => location.url.pathname);
const isReady = track(() => ready.value);
if (isReady) window.tidioChatApi?.display(!/^\/checkout\/?$/.test(pathname));
}, { strategy: 'document-ready' });
return null;
});
Import Tidio into src/root.tsx. In place of the original script, render <Tidio user={user} /> inside <body>, after <RouterOutlet />. Pass your authenticated visitor's stable ID and contact fields, or null when signed out. If your session loads in the browser, wait for it to resolve before mounting Tidio. Do not pass session tokens.
The first task sets document.tidioIdentify before it inserts the script. Initial identification can merge conversations for the same visitor. The document-ready strategy runs the browser task even though the component renders no visible element.
For a later login, call window.tidioChatApi?.setVisitorData({ email, name }) from your login handler after the widget's ready event. Supply the new visitor's contact fields. This updates visitor data but does not merge conversations. Changing the component's user prop alone does not update the running widget.
After logout, run these lines from your browser logout handler before another person uses the browser:
delete document.tidioIdentify;
window.tidioChatApi?.resetVisitor();
Hide the widget on some pages
The second task in Tidio tracks useLocation().url.pathname and the ready signal. It hides the widget on /checkout, including a trailing slash, and shows it elsewhere. It runs again after client-side navigation. The first task registers the ready listener before loading Tidio, so it also handles a fast script response.
For visibility without identification, use the same component with <Tidio user={null} />. Remove the original script from the root. The component now owns the only Tidio script.
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 the script address contains your Public key, not
YOUR_PUBLIC_KEYorundefined. SetPUBLIC_TIDIO_KEYbefore building if you use the environment option. - If you see duplicate requests, use either the root script or the
Tidioloader, not both. Remove any installation in a route component or tag manager. - Keep
windowanddocumentaccess inside browser tasks or event handlers. Do not move it into server rendering. - If your Content Security Policy blocks Tidio, allow
code.tidio.coinscript-srcand check the full list of required hosts. - Qwik's lint rule warns about
useVisibleTask$. These tasks need browser access to load the widget and apply route visibility. Do not move them to server execution to remove the warning.
