Viz Extensions

Viz Extensions are web applications that extend Tableau’s native visual capabilities. They show up as a mark type on a worksheet (via the Marks card), letting you build custom viz types that users can access through Tableau.

How they work

• Added to a worksheet: You add a Viz Extension from the Marks card (not as a dashboard object).
• Similar to dashboard extensions: Like dashboard extensions, a Viz Extension is a web application, but you add it to a worksheet while building the viz.
• Packaged as a .trex: A manifest file points Tableau to the extension’s web app (its URL).
• What’s inside: A Viz Extension typically includes a .trexmanifest plus a web page (.html) and JavaScript logic.
• Distribution: You can choose an extension from Tableau Exchange while authoring, or load a local .trex file you already downloaded.

Requirements

Tableau supports extensions on Tableau Desktop, Tableau Server, and Tableau Cloud.

• Tableau: Tableau Desktop, Tableau Server, or Tableau Cloud with extensions enabled.
• JavaScript enabled (Desktop): Viz Extensions interact with data using the Tableau Extensions API library (JavaScript).
• Network access: The extension loads from its hosting URL (especially for network-enabled extensions).
• Permissions: Your admin may need to allow extensions and allowlist the extension host.

Add a Viz Extension to a worksheet

There are two ways to add a Viz Extension to your worksheet via the Marks card:

• Add it as a local file (a downloaded .trex).
• Add it from Tableau Exchange while authoring.

Add from Tableau Exchange

If you haven't already downloaded an extension, you can browse and add one directly while authoring.

1. Open a workbook and connect to your data source.
2. In a worksheet, on the Marks card, expand the Mark type dropdown menu.
3. Under Viz Extensions, select Add Extension.
4. In the dialog box, select the Viz Extension you'd like to load onto your worksheet.
5. If prompted, allow or deny the Viz Extension access to data in the workbook.
6. Select Open.

The Viz Extension loads in the view, and the mark type changes to the name of the Viz Extension.

Add a local .trex

If you already downloaded a Viz Extension from Tableau Exchange, it's typically saved as a .trex file on your computer.

1. Open a workbook and connect to your data source.
2. In a worksheet, on the Marks card, expand the Mark type dropdown menu.
3. Under Viz Extensions, select Add Extension.
4. In the dialog box, select Access Local Viz Extensions.
5. Navigate to and open the saved .trex file.
6. If prompted, allow or deny the Viz Extension access to data in the workbook.

The Viz Extension loads in the view, and the mark type changes to the name of the Viz Extension.

Encode your data

Once the Viz Extension loads, the Mark type changes to the extension’s name. Build the viz by dragging fields to the Marks card encoding boxes.

• The Mark encoding boxes and formatting options are determined by the developer.
• Check the extension description on Tableau Exchange for encoding instructions.

Allow/deny & data access

By default, network-enabled extensions must request permission to run. The permission dialog provides information about the server the extension is hosted from and the data access level the extension requires.

• Extensions typically access visible data in a view.
• An extension may request deeper workbook access as Full Data Access, which can include access to full underlying data, table and field names from data sources, and information about data source connections.
• If you select Deny, the extension will not load onto your worksheet.
• To reset permissions after denying, add the same Viz Extension into the workbook again to reload the permission prompt.

Server / Cloud settings

On Tableau Server/Cloud, extensions can be restricted by admin policy. If you can't add a Viz Extension, ask your Tableau admin to allow extensions to run on the site and add Network-enabled extensions to an allow list (safe list).

Publish & share

• Desktop → Server/Cloud: make sure the extension is allowed in the target site (and the host is allowlisted if needed).
• Viewers: may see a prompt to allow the extension, depending on site policy.
• Data permissions: to let an extension interact with visible (summary) data in a published workbook/view, ensure users have permission to Download Summary Data. This permission doesn't download your data; it enables the extension to interact with the data in the view.
• Workbook vs view: depending on whether sheets are shown as tabs when publishing, you set Download Summary Data at the workbook or view level.
• Tableau Public: to grant visible-data access, open Settings and select Allow Access.

Permissions & trust

Tableau may prompt you to allow a Viz Extension to run. Review the host information and the requested data access level before allowing.

• Two standards: Tableau supports Tableau Trusted Extensions and Network-enabled extensions.
• Tableau Trusted Extensions: hosted on Tableau infrastructure, managed and governed by Tableau, and reviewed before deployment/updates.
• Tableau Trusted Extensions include Sandboxed extensions, Tableau-built extensions, and Tableau Trusted partner-built extensions (Opt In).
• Network-enabled extensions: not managed by Tableau, can be hosted inside or outside your network, and have full access to the web. Evaluate them before adopting at scale.
• If you deny the prompt, the extension won't load; re-adding it will show the prompt again.

Security best practices (deployment)

These best practices are intended for deployments that use extensions across Tableau Desktop and Tableau Server/Cloud, with appropriate considerations for data security.

Risk considerations

Because extensions are web applications, a Network-enabled extension can be vulnerable to common web security risks.

• SQL injection
• Cross-site scripting (XSS)
• Sensitive data exposure

When evaluating extensions, consider how they manage authentication, data access, user input, and how they mitigate security risks.

Mitigations in Tableau

• HTTPS required: All extensions must use the HTTP Secure (HTTPS) protocol.
• User prompts (default): By default, users viewing a dashboard with a Network-enabled extension are prompted to allow the extension to run.
• Safe list required (Server/Cloud): To run on Tableau Server or Tableau Cloud, the URL of the Network-enabled extension must be added to a safe list (managed by the server administrator on Server and by the site administrator on Cloud).
• Prompt control: On Server/Cloud, admins can control whether the prompt appears for each Network-enabled extension.

Safe list checklist

• Does the extension come from a source that you know and trust?
• Check the URL: does it look suspicious or contain dubious domain names?
• Does the extension require access to full (underlying) data or summary data?
• Test the extensions before allowing broad use.

User prompts behavior

When you add a Network-enabled extension to the safe list, you can configure whether users see prompts by default when they are adding the extension to a dashboard or when interacting with a view that has the extension. The prompt tells users details about the extension and whether it has access to full data.

Trusted extension types

• Sandboxed extensions: run in a protected environment designed to eliminate the risk of data exfiltration. The sandbox host is blocked from any other web resource. They can query workbook data via the Extensions API, but can't send that data outside the sandbox. Sandboxed extensions are enabled by default and enabled for Tableau Public.
• Tableau-built extensions: built and maintained by Tableau as platform features, hosted by Tableau, and undergo Salesforce SDLC standards. Designed to pass JavaScript to the client computer. Enabled by default and enabled for Tableau Public.
• Tableau Trusted partner-built extensions (Opt In): developed by third-party partners, reviewed and hosted by Tableau, and tested (including network communication testing and automated vulnerability scans) before production deployment. Requires administrators to enable them.

Server/Cloud policy controls

• Restrict and curate which extensions users can access.
• Network-enabled extensions aren't allowed unless added to the safe list.
• On Tableau Server, you can block specific extensions by adding their URL to the blocked list.
• Extensions can be turned off for a site; on Tableau Server, server-wide settings can override site settings.

Desktop policy options

Tableau Desktop can be deployed to allow unrestricted access to extensions or to restrict which types of extensions can run.

By default, Tableau Desktop users have unrestricted access to Tableau Trusted extensions and Network-enabled extensions.

• DISABLEEXTENSIONS (turn off all extensions)
• DISABLENETWORKEXTENSIONS (turn off Network-enabled extensions)
• DISABLESANDBOXEXTENSIONS (turn off Sandboxed extensions)
• DISABLETABTRUSTEDEXTENSIONS (turn off Tableau-built extensions)
• DISABLE3PTRUSTEDEXTENSIONS (turn off Tableau Trusted Partner-built extensions)

Run the Viz Extension samples (developer workflow)

To use the Viz Extension samples from the Tableau Extensions API repository, you need to start a local web server to host the HTML pages.

1. Navigate to the extensions-api-main or extensions-api directory.
2. Run npm run build to install and build the package.
3. Run npm start to start the local web server (port 8765).
4. Verify the server by opening http://localhost:8765/assets/flex.png (you should see Flex, the T-Rex).

Using samples on Server/Cloud

If you use Tableau Cloud or Tableau Server to view the samples, add the sample URL pattern to the allow list (safe list). Tableau’s guide suggests the following URL and wildcard: http://localhost:.*/Samples/.*.

Example: Connected Scatterplot sample

1. In a worksheet, on the Marks card, expand the Mark type dropdown menu and select Viz Extensions → Add Extension.
2. Select Access Local Extensions.
3. Navigate to Samples/Viz/ConnectedScatterplot and open connectedScatterplot.trex.
4. If prompted, click OK to allow the Viz Extension to run in the workbook. The guide notes this sample is a network-enabled extension and is not hosted on the Tableau Sandbox.
5. Configure encodings: drag Profit to X, Sales to Y, Order Dateto Text, then change YEAR(Order Date) to Month.

What's next (API guide)

• Start developing by modifying an existing Viz Extension sample (copy a sample folder, rename it, and update the .trex URL to the new path).
• Keeping your extensions in the Samples folder lets you host them with the same local server and can avoid allow list changes if you configured the site to allow http://localhost:.*/Samples/.*.
• Create a "Hello World" Viz Extension
• Extensions API reference

Troubleshooting

• Can't add a Viz Extension: confirm extensions are enabled by your admin (Server/Cloud) and JavaScript is enabled (Desktop).
• Blocked by policy: ask your admin to allowlist the domain / enable extensions.
• Need help with a third-party extension: use the Developer Websitelink on the extension's Tableau Exchange description page to contact the developer.
• Extensions API questions: developers can ask in the Tableau DataDev Slack or submit an issue on GitHub.

Sources

The information on this page is a summarized synthesis based on the following official Tableau documentation:

• Tableau Help: Add Viz Extensions to Your Worksheet
• Tableau Extensions API: Get Started with Viz Extensions
• Tableau Server Help: Extension Security – Best Practices for Deployment