# Tableau Workspace Extensions > Workspace extensions only. Dashboard, viz, and data app guides are out of scope. Use this file for Workspace Extensions. Do not apply Dashboard, Viz, or Data Apps instructions. ## (Desktop Only) Workspace Extensions --- ## Create a "Hello World" Workspace Extension A workspace extension is still just a web page. This walkthrough is the smallest useful one: load the library, initialize, show the active workbook, and update when that workbook (or its active sheet) changes. The type of extension comes from the `.trex` (``), not from a special `initializeAsync()` argument. `` add the authoring toolbar button and the authoring menu item. Both open a side pane. The Hello World manifest is on [Get Started with Workspace Extensions](./trex_workspace_getstarted.md). ```xml ``` ### The web page Same pattern as other Tableau extensions — an HTML page that links the Extensions API library. ```html

Workspace Extension Example

Initializing...
``` ### Initialize Same `initializeAsync()` entry point as dashboard and viz extensions. You do **not** pass `{ context: 'workspace' }`. Optional context-menu callbacks (`{ configure: fn }`) work the same way as for other extensions if your manifest includes ``. ```javascript (async () => { await tableau.extensions.initializeAsync(); document.getElementById('status').textContent = 'Ready!'; })(); ``` ### Read the active workbook After init, use **`tableau.extensions.workspaceContent`**. The active workbook is a **property**, not a getter. There might not be one — that's normal. ```javascript const workspaceContent = tableau.extensions.workspaceContent; const updateWorkbookInfo = () => { const workbook = workspaceContent.workbook; const infoDiv = document.getElementById('workbook-info'); if (workbook) { const sheet = workbook.activeSheet; const sheetLabel = sheet ? ` (${sheet.name})` : ''; infoDiv.textContent = `Current workbook: ${workbook.name}${sheetLabel}`; } else { infoDiv.textContent = 'No workbook open'; } }; updateWorkbookInfo(); ``` When a workbook is open, `workbook` exposes `name`, `sheets`, and `activeSheet`. Each sheet in `sheets` has a `name`, a `sheetType`, an optional `url`, and an optional stable `id`. `activeSheet` is a full sheet: a worksheet, a dashboard, or a story. Filters, parameters, and sheet events are on that object. ### Listen for workbook and sheet changes The extension outlives any one workbook. Listen on `workspaceContent` so your UI stays in sync. Every running workspace extension receives these events. One event covers workbook open, close, and switch: **`tableau.TableauEventType.WorkbookChanged`** (`"workbook-changed"`). `event.workbook` is missing when nothing is open. A second event, **`tableau.TableauEventType.ActiveSheetChanged`** (`"active-sheet-changed"`), fires when the active sheet in that workbook changes. Both events include the workbook. `event.sheetName` is the new active sheet's name. `workspaceContent.workbook` is already updated when your listener runs. ```javascript workspaceContent.addEventListener(tableau.TableauEventType.WorkbookChanged, (event) => { console.log('Workbook changed:', event.workbook ? event.workbook.name : '(none)'); updateWorkbookInfo(); }); workspaceContent.addEventListener(tableau.TableauEventType.ActiveSheetChanged, (event) => { console.log('Active sheet:', event.sheetName); updateWorkbookInfo(); // Read workbook.activeSheet again and re-bind sheet listeners. // The previous Sheet is no longer the active one. }); ``` ### Settings Use the shared **`tableau.extensions.settings`** namespace (not `workspaceContent.settings`). Dashboard and viz settings are saved *with the workbook*. Workspace settings are scoped to the extension, so they survive opening a different workbook. ```javascript tableau.extensions.settings.set('lastUsed', Date.now().toString()); await tableau.extensions.settings.saveAsync(); ``` `tableau.extensions.environment` and `tableau.extensions.ui` are also available. --- ## Workspace Extension Examples Workspace extensions are a good fit when the thing you're building is a *tool*, not a viz and not a dashboard widget. It should still be useful after the user closes the current workbook. The extension shows up from an `` button or an `` item, and it draws in a side pane. Some shapes that fit: * A status panel that shows the active workbook and sheet (or "none") and updates on `WorkbookChanged` / `ActiveSheetChanged`. * A session log that records those events. * A utility that does something useful before any workbook is open — for example, a launcher or template helper. For a manifest you can install, see [Get Started with Workspace Extensions](./trex_workspace_getstarted.md). For the page itself, see [Create a "Hello World" Workspace Extension](./trex_workspace_create.md): init, read `workspaceContent.workbook`, listen for changes. There is not yet a `Samples/Workspace` tree in this repo to clone and run. What *doesn't* fit: anything that belongs inside a specific dashboard or worksheet. Use a [dashboard extension](../dashext/trex_overview.md) or [viz extension](../vizext/trex_viz_overview.md) for those. --- ## Get Started with Workspace Extensions Starting in November 2026 (2026.3.1) you can build **workspace extensions** — web apps that run at the Tableau application level and stay available as you open, close, and switch workbooks. This page gets a workspace extension running on **Tableau Desktop** by installing a manifest. The sample URL is a placeholder until you host the page. :::info **What's in a Tableau extension?** A Tableau extension is a manifest file (`.trex`), a web page (`.html`) that loads a Tableau-provided JavaScript library, and the JavaScript (`.js`) that contains your logic. ::: #### The Hello World manifest [hello-world-extension.trex](pathname:///assets/workspace/hello-world-extension.trex) is a minimal workspace extension. Its `` is a placeholder (`https:///...`), not a page Tableau hosts. Replace that URL with your hosted page, or with `http://localhost` while you develop, before the button can open it. The file adds two ways to open that page. Both use ``: * `` adds a **Hello World** button to the authoring toolbar. The icon is an inline SVG. * `` adds a **Hello World** item to the authoring menu. ```xml en_US A minimal workspace extension for Desktop entry-point testing. 1.1 https:///hello-world-extension/index.html Hello World ``` The name **Hello World** comes from the `name` resource. Identity is the extension `id`, `extension-version`, and that URL together. #### Install the `.trex` A workspace extension is not added to a workbook. Copy `hello-world-extension.trex` into **My Tableau Repository/Extensions/** (on a typical Desktop install, `Documents/My Tableau Repository/Extensions/`) and restart Tableau. Adding the same `id`, `extension-version`, and URL again replaces the installed copy. A different version or URL is a separate extension. The file stays in that folder. It is not saved with the workbook. To remove it, delete the file and restart Tableau. #### Open Hello World In Tableau Desktop, open **Hello World** from the authoring toolbar or from the authoring menu. Each one opens the extension in a side pane. #### Point it at your own page To run your own page, copy the `.trex` and change ``. `http://localhost` is allowed. Host the page the same way as a dashboard extension sample: from the Extensions API repo, run `npm run build` once, then `npm start`. That serves files on port `8765`. See [Get Started with Dashboard Extensions](../dashext/trex_getstarted.md). A bundled extension is a `.tpkg` under **My Tableau Repository/Packages/``/**. Its `.trex` is in `extensions/`, and `` is a path relative to `content/`. Tableau serves those files. The package id and the extension id are not the same thing. There is not yet a `Samples/Workspace` tree in this repo. The page itself is in [Create a "Hello World" Workspace Extension](./trex_workspace_create.md). ### What's next? * Build the page: [Create a "Hello World" Workspace Extension](./trex_workspace_create.md). * Manifest fields: [Tableau Workspace Extension Manifest File](./trex_workspace_manifest.md). * Namespaces: [Tableau Extensions API Basics](../trex_api_about.md). --- ## Tableau Workspace Extension Manifest File The `.trex` file is how Tableau knows your extension exists. A workspace extension uses the same root wrapper as dashboard and viz extensions: ``. Declare `` instead of `` or ``. There is no `` and no ``. Those belong to extensions that live inside a workbook. Desktop opens the extension from ``. One `` is shared by every entry point. Inside ``, the target is ``. ### Sample manifest file This is [hello-world-extension.trex](pathname:///assets/workspace/hello-world-extension.trex). It declares the two entry points Desktop renders, and both open a side pane. ```xml en_US A minimal workspace extension for Desktop entry-point testing. 1.1 https:///hello-world-extension/index.html Hello World ``` Put the `.trex` in **My Tableau Repository/Extensions/**. It is not saved into the workbook. A hosted `` is `https`, or `http://localhost` while you develop. A bundled extension uses a path relative to the package `content/` directory. The package lives under **My Tableau Repository/Packages/``/**, with the `.trex` in `extensions/`. The package id and the extension id are different. A `.twbx` can carry a `Packages/` copy, and that copy is the one used for that workbook. A standalone `.trex` in **Extensions/** does not travel in a `.twb` or `.twbx`. :::note An installed extension is identified by its `id`, `extension-version`, and source URL together. Adding the same combination replaces the installed copy. A different version or a different URL is a separate extension. ::: ### Elements of the manifest file Name of element | Description manifest | The root element that contains the manifest options. manifest-version | The version of the manifest. The version currently supported is 0.1. workspace-extension | The element that contains the workspace extension. Requires id (reverse domain name, for example com.example.extension) and extension-version. Do not include <layout> or <encoding>. Declare <entry-points> for the authoring toolbar button and the authoring menu item. extension-version | The version of the extension. For example, extension-version="0.0.1". Together with id and the source URL, this identifies the installed extension. default-locale | Specifies the default locale for localized text. Both the locale format (en_US) and a language code (en) are accepted. An unsupported or invalid language falls back to English. name | The name of the extension. To localize it, set resource-id and put the strings in resources. Hello World uses this resource for the toolbar and menu labels. description | A short description of the extension. author | Metadata about the author: name, email, organization, and website. name and website are required. website must use HTTPS and is the Get Support link in the About dialog box. source-location | Contains the single url loaded for every entry point. url | A hosted URL (https://example.com/extension, or http://localhost:8765/...), or, inside a package, a path relative to content/. entry-points | Wraps the triggers the extension adds. Each child is one entry point with its own label and target. An extension can declare more than one. All of them load the same source-location. authoring-toolbar | A button on the authoring toolbar. Requires region: primary, insights, or overflow. Children: label, an optional tooltip, an inline SVG icon, and on-click. Opens a side pane. authoring-menu | An item on the authoring menu. Children: label and on-click. Opens a side pane. label | The button or menu text. Use a literal string, or resource-id plus a resources entry, as Hello World does. tooltip | Optional tooltip on a toolbar entry point. on-click | Required inside every entry point. The child element is <side-pane/>. side-pane | Opens the extension in a side pane. icon | The optional icon inside a toolbar entry point, icon is an inline SVG. As a direct child of workspace-extension, the icon image should be a 70×70 PNG, Base64 encoded. Hello World uses only the toolbar SVG. permissions | Optional. The only value is full data. Declare it if the extension calls Worksheet.getUnderlyingDataAsync(), Datasource.getUnderlyingDataAsync(), Datasource.getActiveTablesAsync(), or Datasource.getConnectionSummariesAsync(). context-menu | Optional. Registers a Configure... item. The only allowed child is <configure-context-menu-item />. Map it to a configure function in initializeAsync(). The authoring menu entry point is a separate element. resources | Localized strings for name, description, and entry-point label text. min-api-version | The minimum API version required to run the extension. Hello World uses 1.1. **Constraints** - String-based fields: 1000 characters - URI-based fields: 2084 characters --- ## What is a Tableau Workspace Extension A workspace extension is a web app that lives at the Tableau *application* level, not inside a workbook. Dashboard extensions sit in a dashboard. Viz extensions sit in a worksheet. A workspace extension is neither of those — it's a tool that stays around while you open, close, and switch workbooks. That's the whole idea: these are tools you install, not content you save with a workbook. --- ### Components of a Tableau workspace extension Same three pieces as every other Tableau extension: a manifest file (`.trex`), a web page (`.html`) that loads the Tableau Extensions API library, and the JavaScript that does the work. ### What it looks like in Tableau A workspace extension is not a dashboard zone or a Marks card viz. The manifest declares where it shows up. On Desktop today: 1. You put the `.trex` in **My Tableau Repository/Extensions/**. 2. `` adds a button to the authoring toolbar. `` adds an item to the authoring menu. 3. Choosing either one opens the extension in a **side pane**. The manifest for that button and menu item is [hello-world-extension.trex](./trex_workspace_manifest.md#sample-manifest-file). ### What you can do with one Anything that needs to hang around for a whole Tableau session: * Utilities that don't belong in a single dashboard or worksheet. * Tools that watch workbook and sheet changes and update themselves. * Things that still make sense when no workbook is open at all. When a workbook *is* open, the extension can read it (`name`, `sheets`, `activeSheet`). When it isn't, the extension keeps running — `workspaceContent.workbook` is empty. ### How it differs from dashboard and viz extensions All three types are web apps on the same Extensions API. The difference is *where they live* and *what they're for*. | | Dashboard / viz | Workspace | |---|---|---| | **Scope** | One workbook | The Tableau app | | **Saved with** | The `.twb` / `.twbx` | A `.trex` in My Tableau Repository (not the workbook) | | **UI** | Embedded in a dashboard or worksheet | Authoring toolbar button or authoring menu item, opening a side pane | | **Workbook** | Always has one | Can have none | | **Lifespan** | Comes and goes with the workbook | Stays while the `.trex` is in My Tableau Repository | A few more distinctions: * Dashboard and viz extensions are *content*. They travel with the workbook. Workspace extensions are *tools*. They live as a `.trex` under **My Tableau Repository/Extensions/**, not inside the workbook. * The manifest's `` are what show the side pane. See [the manifest](./trex_workspace_manifest.md). * Listen for `WorkbookChanged` and `ActiveSheetChanged` on `tableau.extensions.workspaceContent`. ```mermaid flowchart LR subgraph app [Tableau Desktop] ext[Workspace extension pane] wbA[Workbook A] wbB[Workbook B] none[No workbook] end ext -.-> wbA ext -.-> wbB ext -.-> none ``` The extension is independent of whichever workbook is open — including none. ### Where it is supported This authoring path is **Tableau Desktop**, starting in November 2026 (2026.3.1). Server still uses the legacy `toolbar` manifest, which this guide does not cover.