Tableau has two things called extensions. They have similar names, live in different parts of the product, use different manifests and different APIs, and are not convertible into one another. Choosing wrong does not cost you an afternoon: it costs you the build. This page gets you to the right choice before you write any code.
#The two of them
A dashboard extension is an object you drag onto a dashboard. It sits in the layout like a container or an image, can read every worksheet on the dashboard, can apply filters and change parameters, and has worked nearly everywhere since 2018. Its manifest root is <dashboard-extension>.
A viz extension is a mark type on a worksheet's Marks card. It renders as the viz, filling the whole pane. It sees only the fields you declare as encodings, travels with the sheet everywhere it is used, and needs Tableau 2024.2 or later. Its manifest root is <worksheet-extension>.
The clearest way to hold them apart: a dashboard extension is a widget that reads the dashboard. A viz extension is a chart type that replaces the mark. One looks at your work, the other is the work.
#Ninety seconds to a decision
| What you want | The answer |
|---|---|
| A KPI card showing total sales and last month's change | Either, but a dashboard extension is easier |
| A chart Tableau cannot draw (chord, radial bar, beeswarm) | Viz extension |
| Read several worksheets and summarize across them | Dashboard extension: a viz extension cannot see other sheets |
| Apply filters to the rest of the dashboard | Dashboard extension |
| Users drag fields onto it like a normal chart | Viz extension: that is the Marks card, and the whole point |
| Must work in Tableau 2023 or an older Server | Dashboard extension: viz extensions need 2024.2+ |
The one that surprises people is the third. A viz extension is scoped to its own worksheet by design and has no route to the rest of the dashboard. If your feature is fundamentally about relating sheets to each other, no amount of clever code makes a viz extension the right shape.
#What differs once you are building
| Dashboard extension | Viz extension | |
|---|---|---|
| Manifest root | <dashboard-extension> |
<worksheet-extension> plus <encoding> blocks |
| API entry point | extensions.dashboardContent |
extensions.worksheetContent |
| How you get data | getSummaryDataAsync() on any worksheet |
getVisualSpecificationAsync() for encodings, then a data reader |
| Minimum API | 1.4 |
1.11 (Tableau 2024.2+) |
| Where it renders | A fixed-size object you position | The entire worksheet pane, whatever size it is |
| Configuration UI | Right-click, Configure works reliably | Needs a button inside the viz: the Marks-card menu will not fire the dialog |
| Layout burden | Low: you control the box | High: must look right from a tiny tile to a full sheet, no scrollbars |
The bottom two rows hold the real cost difference, and neither is obvious from the docs. A viz extension renders into whatever pane it is given, so a card laid out in fixed pixels looks lost on a full sheet and clipped on a small one. Size everything fluidly against the smaller pane dimension and shed detail only near the limits, and know that before you write the CSS.
#You cannot port one to the other
Different manifest root, different API surface, different data model, different layout assumptions. Roughly the rendering code survives a switch, everything that touches Tableau does not. Make this decision deliberately at the start.
Some things legitimately want to exist twice: a KPI card is the usual example. Build the dashboard version first. It is the more forgiving API, runs on more Tableau versions, and the rendering code carries over. Then decide whether the viz version earns its second build.
#FAQ
#Can I convert a dashboard extension into a viz extension?
No. The manifest root, API surface, data model, and layout assumptions all differ. Only the rendering code carries over. Treat it as a fresh build that reuses your drawing logic, not a conversion.
#Which one reads other worksheets on the dashboard?
The dashboard extension. It can read every worksheet on the dashboard, apply filters, and change parameters. A viz extension only sees the fields dropped on its own Marks card encodings and cannot reach other sheets.
#What Tableau version do I need for each?
A dashboard extension runs against min-api-version 1.4 and works nearly everywhere. A viz extension needs 1.11 and Tableau 2024.2 or later, because the worksheet extension API arrived then.
#Which is easier for a KPI card?
The dashboard extension. It has the more forgiving API and runs on more Tableau versions. See viz extension encodings if you decide the card should also travel with a worksheet as a custom mark.