# Install Tidio on Eleventy

Section: Install Tidio

Description: Add Tidio to your Eleventy layout, identify logged-in visitors, and hide the chat widget on checkout pages.

Verified against Tidio panel 12.331.0

Last updated: 2026-11-18

Source: https://help.tidio.com/articles/install-eleventy/

Add Tidio to your Eleventy site through a shared Nunjucks layout. You do not need a package for Tidio. Checked with Eleventy 3.1.8.

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

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

## Add the widget to Eleventy

Add the script just before ` </body> ` in your shared ` _includes/base.njk ` layout. Replace ` YOUR_PUBLIC_KEY ` with your Public key. Keep your existing head elements and layout content. A minimal layout looks like this:

```
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>{{ title }}</title>
  </head>
  <body>
    {{ content | safe }}
    <script src="https://code.tidio.co/YOUR_PUBLIC_KEY.js" async></script>
  </body>
</html>
```

Set ` layout: base.njk ` in each page's front matter, or use your existing shared layout. For example, ` index.njk ` can start with:

```
---
layout: base.njk
title: Home
---
<h1>Home</h1>
```

Eleventy builds a multi-page site. With ordinary links, each page loads the script once in a new document. Do not add another Tidio script to individual pages that already use this layout.

Eleventy has no convention for public environment variables, so this example puts the Public key directly in the layout.

Run ` npx @11ty/eleventy ` to build the site, then deploy the generated ` _site ` directory. If you changed the output directory in your configuration, deploy that directory instead.

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

On this multi-page site, the next page loads its own widget rather than keeping the previous page's script.

[Video](https://help.tidio.com/article-media/install-eleventy/walkthrough.mp4)

Silent walkthrough. A demo Eleventy site with the Tidio chat widget in the corner. Each page loads the widget, and the Checkout page hides it.

## Identify logged-in visitors

Do not put visitor identity in Eleventy's generated HTML. Everyone who opens a static page receives the same file. Use your existing browser authentication code to get the current visitor instead.

Replace the original Tidio script in ` _includes/base.njk ` with this inline loader. Call ` startTidio(user) ` from your authentication code after the session resolves on each page. Pass the current visitor's ` distinct_id `, ` email ` and ` name `, or ` null ` for a signed-out visitor. Do not pass session tokens.

```
<script>
  function startTidio(user) {
    if (document.getElementById('tidio-script')) return;
    if (user) {
      document.tidioIdentify = {
        distinct_id: user.distinct_id,
        email: user.email,
        name: user.name
      };
    }
    const script = document.createElement('script');
    script.id = 'tidio-script';
    script.src = 'https://code.tidio.co/YOUR_PUBLIC_KEY.js';
    script.async = true;
    document.body.appendChild(script);
  }
</script>
```

The loader sets ` document.tidioIdentify ` before inserting the script. Initial identification can merge conversations for the same visitor. Use this loader instead of the original script, not alongside it.

For a later login on the same page, call ` setVisitorData ` from your login handler after the widget's ready event. Replace the example values with your session data. This updates visitor data but does not merge conversations:

```
window.tidioChatApi.setVisitorData({
  email: 'visitor@example.com',
  name: 'Example visitor'
});
```

After logout, remove the identification data before resetting the widget. Call this from your logout handler after the widget is ready:

```
delete document.tidioIdentify;
window.tidioChatApi?.resetVisitor();
```

## Hide the widget on some pages

Add this inline script in ` _includes/base.njk ` before the Tidio script or identification loader. It hides the widget on both ` /checkout ` and ` /checkout/ `, and shows it elsewhere. Each page runs its own ready callback after a full-page navigation.

```
<script>
  function updateTidioVisibility() {
    const path = window.location.pathname.replace(/\/+$/, '') || '/';
    window.tidioChatApi.display(path !== '/checkout');
  }
  if (window.tidioChatApi) {
    window.tidioChatApi.on('ready', updateTidioVisibility);
  } else {
    document.addEventListener('tidioChat-ready', updateTidioVisibility);
  }
</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](https://help.tidio.com/articles/show-widget-only-on-specific-pages/).

## Troubleshooting

- If a page has no widget, check that its front matter selects the layout containing the script.
- If the widget loads twice, remove the duplicate installation. Use either the original script or the identification loader.
- If a change does not appear on your site, rebuild and deploy the generated files. Check that the script address contains your Public key instead of ` YOUR_PUBLIC_KEY `.
- If checkout still shows the widget, check its actual pathname against the visibility rule.
- If your Content Security Policy blocks Tidio, allow ` code.tidio.co ` in ` script-src ` and check the [full list of required hosts](https://developers.tidio.com/docs/widget-security-policy). Authorize inline scripts with a nonce or hash.
- If an automated browser shows no widget, check the published site in a regular browser window.

## Further reading

- [Install Tidio on your website](https://help.tidio.com/articles/install-website/)
- [Widget SDK](https://help.tidio.com/articles/widget-sdk/)
- [Eleventy layouts](https://www.11ty.dev/docs/layouts/)
- [Eleventy environment variables](https://www.11ty.dev/docs/environment-vars/)
