How to use Tableau extensions (and get them working)

You found an extension you want to use. Maybe one of mine, maybe someone else’s. This page covers everything between “I want this” and “it runs in my dashboard”: how to add it in Tableau Desktop, what your admin needs to do on Tableau Server or Tableau Cloud, and what to check when it doesn’t work.

Bookmark it, or better: send the admin section straight to your admin. That’s what it’s for.

Two kinds of extensions

Tableau has two flavours, and they live in different places:

Dashboard extensions are objects you drag onto a dashboard, like a container or a text box. They add functionality: filters, exports, animations, write-back, you name it. Latch is a dashboard extension: it replaces the UI of a parameter.

Viz extensions are new chart types. They live on the worksheet, in the Marks card, next to Bar, Line and Circle. My extension Tally is a viz extension: you pick it as a mark type and your KPI starts counting.

The distinction matters for where you click, not for security. Admins manage both from the same settings page.

Adding an extension in Tableau Desktop

Dashboard extension:

1. Open a dashboard sheet.
2. Drag the Extension object from the Objects panel onto the dashboard.
3. In the dialog, either search the built-in Exchange listing, or click Access Local Extensions and select a .trex file you downloaded.
4. If Tableau asks whether the extension may access data in the workbook: this is normal. Allow it and configure the extension.

Viz extension:

1. On a worksheet, open the mark type dropdown on the Marks card.
2. Choose Add Extension.
3. Pick one from the Exchange, or load a local .trex file.
4. The extension replaces the standard mark rendering with its own.

[For each of your extensions, link the .trex download right here, or link back to the extensions overview page.]

What exactly is a .trex file?

The .trex file is not the extension. It’s the address label.

It’s a small XML manifest, a plain text file you can open in any editor, that tells Tableau everything it needs to know before loading the extension: the URL where the extension actually lives (the source-location), whether it’s a dashboard extension or a viz extension, who made it, a support website, the icon Tableau shows in the dialog, the minimum Extensions API version it needs, and crucially, what access it declares. An extension that needs underlying row-level data has to say so here, in the full-data permission, before Tableau will even consider granting it.

The extension itself is a web application: HTML and JavaScript, hosted on a web server, in my case on my own infrastructure at extensions.byantichaos.com. When you add the .trex, Tableau fetches that web page and runs it inside the dashboard zone or the worksheet. That’s also why the file is a few kilobytes: you’re not downloading software, you’re downloading a pointer.

Three practical consequences:

• You can audit it in thirty seconds. Open the .trex, read the URL, check the declared permissions. If a vendor’s manifest points somewhere unexpected or asks for full data without a good reason, that’s your cue to ask questions. I encourage you to read mine.
• The URL in the manifest is the URL your admin allowlists. They have to match exactly, including the casing in the path. This is the single most common reason an extension “works on Desktop but not on Server”.
• The extension can be updated without you touching anything. Because the .trex only points to the hosted app, bug fixes and new features land the moment I deploy them. No new file to distribute, no reinstall.

Publishing to Tableau Server or Tableau Cloud

Here’s where many people struggle – and it is intentional.
(more details on this in the Allowlist a Tableau Extension tutorial)

Extensions are web applications, so Tableau is (rightly) careful about which ones are allowed to run. On Desktop, it is up to you. On Server and Cloud, your admin decides.

The short version: an administrator must allow extensions to run on the site and add network-enabled extensions to a safe list. My extensions are network-enabled: they’re hosted on my own infrastructure at extensions.byantichaos.com, which means they need one allowlist entry before they run on your site. It takes about a minute. The next section is written for the person with the admin rights.

For your Tableau admin

Hi. Someone on your site wants to use an extension and sent you this page. Here’s what it involves, and what it doesn’t.

What an extension is: a web application that runs in the user’s browser, inside the dashboard. In many cases the extension doesn’t access the underlying data at all, and all the JavaScript runs in the browser on the user’s computer, so no data leaves that machine even though the extension is hosted outside your domain. All extensions are required to use HTTPS.

Step 1: check extensions are enabled on the site. Go to Settings > Extensions. Make sure extensions are allowed to run on this site. On Tableau Server there’s also a server-wide setting under Manage All Sites > Settings > Extensions; if the server has a single site, the global controls appear on the site’s settings page.

Step 2: add the extension to the safe list. On the same page,under Enable Specific Extensions, add the URL of the extension. For my extensions, the URLs are:

[Since Tableau 2024.2 a wildcard entry is supported, e.g. https://extensions.byantichaos.com/.* to cover the whole suite in one entry.

Not sure of an extension’s URL? For dashboard extensions you can find it in the extension’s context menu: from the More Options menu, click About, and the dialog lists the name, author and URL of the extension. Or open the .trex file and look at the source-location element.

Step 3: choose the data access and prompt settings. Each allowlist entry has two switches:

• Full data access. This means access to underlying row-level data instead of only the aggregated summary data in the view. Only grant it if the extension declares it needs it. [State per extension whether it needs full data or summary only. If your extensions run on summary data, say so loudly here: it makes the approval conversation much easier.]
• User prompts. You can control whether users see a prompt asking them to allow the extension access to data; when you hide the prompt, the extension runs immediately. For a vetted extension on the allowlist, hiding the prompt gives users a smoother experience.

Step 4: check workbook permissions. The extension needs access to the visible (summary) data, so the workbook or view must allow the Download Summary Data permission for the users viewing it.
If the extension loads but shows nothing, this is a likely suspect.

What you’re agreeing to when you allowlist one of my extensions: the extension is loaded from my servers, runs in the viewer’s browser, and processes the data Tableau hands it right there. Nothing is sent back to me. You can verify that claim in your browser’s network tab, and I’d genuinely rather you did than took my word for it. [Add your standard beacon disclosure here if applicable, same wording as the extensions page, so the two pages never contradict each other.]

Good to know

Extensions don’t render in exports.On Server and Cloud, extension objects appear blank in prints, PDFs and images of dashboards, including the images in subscription emails. Design accordingly: put the extension next to the numbers, not instead of them, if people rely on PDF exports.

Tableau Public is different. Only a curated set of extensions approved by Tableau runs on Tableau Public.

If an extension freezes, select it and choose Reload from the drop-down menu in the upper-right corner; if that doesn’t fix it, remove it from the dashboard and add it again.

Checklist

1. “Extension blocked” or it won’t load on Server/Cloud → it’s not on the site’s safe list, or the allowlisted URL doesn’t exactly match the URL in the .trex. Exact means exact, including upper and lower case in the path.
2. Extension loads but stays empty → check the Download Summary Data permission on the workbook, and check whether the extension needs full data access that wasn’t granted.
3. It worked on Desktop but not after publishing → that’s the allowlist. Desktop asks you; Server and Cloud ask your admin. Send them the section above.
4. Blank box in a PDF or subscription email → not a bug, see above. Extensions render live, in browsers.
5. Someone clicked Deny on the data prompt → reload the extension to get the prompt again, or have the admin hide prompts for allowlisted extensions.

Questions, or an extension that misbehaves?

Contact me. I maintain and host these myself (on reliable infrastructure), so you’re mailing the person who wrote the code, not a support queue.
If your Tableau admin or security team has questions I haven’t answered here, I’m happy to get on a call: I’ve been through this review many times.