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:

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

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

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_KEY or undefined. Set PUBLIC_TIDIO_KEY before building if you use the environment option.
  • If you see duplicate requests, use either the root script or the Tidio loader, not both. Remove any installation in a route component or tag manager.
  • Keep window and document access inside browser tasks or event handlers. Do not move it into server rendering.
  • If your Content Security Policy blocks Tidio, allow code.tidio.co in script-src and 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.

Further reading