Tableau Embedding API

https://help.tableau.com/current/api/embedding_api/en-us/
Admin
Tableau Embedding API v3 enables developers to integrate Tableau visualizations into web...
Tokens:164,667
Snippets:1,896
Trust Score:10
Update:2 months ago
Show doc for...
Tokens:
Raw
### OnFirstInteractive Property Example

Source: https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html

Example of how to use the `onFirstInteractive` property.

```APIDOC
## Property: onFirstInteractive
### `Optional`onFirstInteractive
onFirstInteractive?: string
An event raised when the Viz object first becomes interactive. This is only raised once.
```html
<tableau-viz id="tableauViz" "onFirstInteractive"="onFirstInteractiveHandler" />  
<tableau-authoring-viz id="tableauViz" onFirstInteractive="onFirstInteractiveHandler" />
```
```

--------------------------------

### Full Example: Embedding Viz and Getting Sheet Info

Source: https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_react.html

An example demonstrating how to embed a Tableau viz using `useTableauVizRef` and access its properties like active sheet name and type via a button click.

```javascript
import React from 'react';
import { Api, TableauViz, useTableauVizRef  } from '@tableau/embedding-api-react'

export default function MyViz() {
  const vizRef = useTableauVizRef();

  const getActiveSheetInfo = () => {
    const viz = vizRef.current;
    if (!viz) {
      throw new Error("TableauViz ref not assigned yet.");
    }
    const activeSheet = viz.workbook.activeSheet;
    const sheetName = activeSheet.name;
    const sheetType = activeSheet.sheetType;
    alert(`Active Sheet: ${sheetName}\nSheet Type: ${sheetType}`);
  };

  return (
    <>
      <div>
        <p>
          Click the <b>Get Sheet Info</b> button to get the name and type of the
          active sheet.
        </p>
        <p>
          <Button onClick={getActiveSheetInfo}>Get Sheet Info</Button>
        </p>
      </div>
      <div style={{ display: "flex", gap: "10px" }}>
        <TableauViz
          ref={vizRef}
          src="https://public.tableau.com/views/RegionalSampleWorkbook/Storms"
          hide-tabs
          toolbar="bottom"
        />
      </div>
    </>
  );
}
```

--------------------------------

### IframeAttributeLoading Property Example

Source: https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html

Example of how to use the `iframeAttributeLoading` property.

```APIDOC
## Property: iframeAttributeLoading
### `Optional`iframeAttributeLoading
iframeAttributeLoading?: string
The value of the 'loading' attribute of the embedded iframe. See: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#loading
```html
<tableau-viz id="tableauViz" iframe-attr-loading="lazy" />  
<tableau-authoring-viz id="tableauViz" iframe-attr-loading="lazy" />  
<tableau-pulse id="tableauPulse" iframe-attr-loading="lazy" />
```
```

--------------------------------

### IframeAuth Property Example

Source: https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html

Example of how to use the `iframeAuth` property.

```APIDOC
## Property: iframeAuth
### `Optional`iframeAuth
iframeAuth?: boolean
Indicates whether to use the old auth mechanism for authentication which happens inside the iframe. If specified, VizLoadErrorEvents triggered due to auth failures will not be thrown.
```html
<tableau-viz id="tableauViz" iframe-auth />  
<tableau-authoring-viz id="tableauViz" iframe-auth />  
<tableau-ask-data id="tableauAskData" iframe-auth />
```
```

--------------------------------

### Debug Property Example

Source: https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html

Example of how to use the `debug` property.

```APIDOC
## Property: debug
### `Optional`debug
debug?: boolean
Indicates whether the non-minified version of JavaScript is loaded. If specified (or set to true), the non-minified version is used for both the local component and the Tableau Server visualization (if enabled). If not specified (or set to false), the minified version of the JavaScript files are loaded.
```html
<tableau-viz id="tableauViz" debug />  
<tableau-authoring-viz id="tableauViz" debug />  
<tableau-ask-data id="tableauAskData" debug />
```
```

--------------------------------

### IframeAttributeStyle Property Example

Source: https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html

Example of how to use the `iframeAttributeStyle` property.

```APIDOC
## Property: iframeAttributeStyle
### `Optional`iframeAttributeStyle
iframeAttributeStyle?: string
The value of the 'style' attribute of the embedded iframe.
```html
<tableau-viz id="tableauViz" iframe-attr-style="border: 1px solid red" />  
<tableau-authoring-viz id="tableauViz" iframe-attr-style="border: 1px solid red" />  
<tableau-pulse id="tableauPulse" iframe-attr-style="border: 1px solid red" />
```
```

--------------------------------

### Install the Embedding API v3 library

Source: https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_get.html

Use these commands to install the latest or a specific version of the Tableau Embedding API library into your project.

```bash
npm i @tableau/embedding-api
```

```bash
npm i @tableau/embedding-api@3.12.1
```

--------------------------------

### Interacting with the Viz Object

Source: https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_interact.html

Shows how to use the `viz` object obtained from the web component to interact with the embedded Tableau view. This includes examples of getting the active sheet and applying filters asynchronously.

```APIDOC
## Add JavaScript code that interacts with the viz object

After you have the `viz` object, you can begin to interact with the view. Using the Embedding API, you can query for elements and data in the view, or apply or remove filters, get summary or underlying data from worksheets, or add take action based upon users actions with the view.

For example, if you have the `viz` object, you can get the currently active sheet in the workbook. Using the sheet object, you can apply filters.

```javascript
let sheet = viz.workbook.activeSheet;
sheet.applyFilterAsync("Container", "Boxes", FilterUpdateType.Replace);
```

Note: In the example, the view will not be _interactive_ immediately after you initialize the `viz` object. If you plan on filtering or doing some interaction immediately after initialization, you should use the `"firstinteractive"` (`TableauEventType.FirstInteractive`) event listener to wait for the `viz` object to be ready. For more information about using events, see Add Event Listeners.
```

--------------------------------

### IframeAttributeClass Property Example

Source: https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html

Example of how to use the `iframeAttributeClass` property.

```APIDOC
## Property: iframeAttributeClass
### `Optional`iframeAttributeClass
iframeAttributeClass?: string
The value of the 'class' attribute of the embedded iframe providing access to any custom selectors defined in the `<iframe-style>` child tag.
```html
<tableau-viz id="tableauViz" iframe-attr-class="red-border">  
  <iframe-style>  
    .red-border {  
      border: 1px solid red;  
    }  
  </iframe-style>  
</tableau-viz>
```
```

--------------------------------

### HideCloseButton Property Example

Source: https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html

Example of how to use the `hideCloseButton` property.

```APIDOC
## Property: hideCloseButton
### `Optional`hideCloseButton
hideCloseButton?: boolean
Indicates whether the Close button is hidden or visible. If not set, defaults to false, meaning that the Close button is visible.
```html
<tableau-authoring-viz id="tableauViz" hide-close-button />
```
```

--------------------------------

### Install Tableau React npm Package

Source: https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_react.html

Use this command to install the Tableau Embedding API React library. Ensure your version is compatible with your Tableau instance.

```bash
npm i @tableau/embedding-api-react
```

--------------------------------

### OnEditInDesktopButtonClicked Property Example

Source: https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html

Example of how to use the `onEditInDesktopButtonClicked` property.

```APIDOC
## Property: onEditInDesktopButtonClicked
### `Optional`onEditInDesktopButtonClicked
onEditInDesktopButtonClicked?: string
An event raised when the user clicks on the Edit In Desktop Button. You can use this event type with TableauViz objects.
```html
<tableau-viz id="tableauViz" onEditInDesktopButtonClicked="onEditInDesktopButtonClickedHandler" />  
<tableau-authoring-viz id="tableauViz" onEditInDesktopButtonClicked="onEditInDesktopButtonClickedHandler" />
```
```

--------------------------------

### HideEditInDesktopButton Property Example

Source: https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html

Example of how to use the `hideEditInDesktopButton` property.

```APIDOC
## Property: hideEditInDesktopButton
### `Optional`hideEditInDesktopButton
hideEditInDesktopButton?: boolean
Indicates whether the Edit in Desktop button is hidden or visible. If not specified, defaults to false, meaning that the Edit in Desktop button is visible.
```html
<tableau-viz id="tableauViz" hide-edit-in-desktop-button>  
<tableau-authoring-viz id="tableauViz" hide-edit-in-desktop-button>
```
```

--------------------------------

### revertAllAsync

Source: https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizActions.html

Restores the workbook to its starting state.

```APIDOC
## revertAllAsync()

### Description
Equivalent to clicking on the Revert All toolbar button, which restores the workbook to its starting state.

### Returns
- **Promise<void>**
```

--------------------------------

### Get and change parameters from a workbook

Source: https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_parameters.html

Shows how to retrieve all parameters from a workbook using `getParametersAsync()` and how to change a specific parameter's value using `Parameter.changeValueAsync()`.

```APIDOC
## Get and change parameters from a workbook

### Description
You can use the `Workbook.getParametersAsync()` method to access all the parameters available in a workbook. The method returns an array of parameter objects.

For example, the following code snippet assumes that you have already created a `Viz` object and have used `tableauViz` as the identifier. The example uses the `Workbook.getParametersAsync()` method to access the parameters. The snippet then prints the names of all the parameters and their current values in the debugging tools console.

### Code Example
```javascript
async function getParameterNames() {
  let viz = document.getElementById("tableauViz");
  const parameters = await viz.workbook.getParametersAsync();
  parameters.forEach( (p) => {
    console.log(p.name, p.currentValue.value);
  });
};
```

You could also use the `getParametersAsync()` method to get a specific parameter object, and then use that object and the `Parameter.changeValueAsync()` method to assign the parameter a new value.

### Code Example
```javascript
async function setParamFunc() {

let viz = document.getElementById("tableauViz");
try {
      const parameters = await viz.workbook.getParametersAsync();
      const baseSalary = parameters.find( (p) => p.name == "Base Salary");
      newVal = await baseSalary.changeValueAsync("75000");
      console.log(newVal);
} catch (error) {
      console.log (error);
  };

  }
```
```

--------------------------------

### Initialize v3 API using Web Component (HTML)

Source: https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_migration_guide.html

v3 simplifies initialization by using the <tableau-viz> web component directly in HTML. Specify the src URL and an id.

```html
<tableau-viz id="tableauViz" 
      src='http://my-server/views/my-workbook/my-view'>
</tableau-viz>
```

--------------------------------

### Get Filters in a Worksheet

Source: https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_filter.html

Retrieves all filters applied to a specific worksheet. The example shows how to get the list of filters and log them to the console.

```APIDOC
## Get Filters in a Worksheet

### Description
Retrieves the collection of filters used in a worksheet. The example logs the entire list of filters to the console.

### Method
`worksheet.getFiltersAsync()`

### Parameters
None

### Response
- Returns a Promise that resolves to an array of filter objects.

### Request Example
```javascript
  const sheetFilters = await worksheet.getFiltersAsync();
  console.log(sheetFilters);
```
```

--------------------------------

### Initialize v2 API (HTML Placeholder)

Source: https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_migration_guide.html

In v2, a placeholder div was required in HTML to contain the viz.

```html
<div id='tableauViz'></div>
```

--------------------------------

### Creating and Configuring a Viz Object

Source: https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_about.html

This example demonstrates how to create a TableauViz object, set its source and toolbar properties, append it to the DOM, and access its workbook and activeSheet to apply a filter.

```APIDOC
## Creating and Configuring a Viz Object

### Description
This example demonstrates how to create a TableauViz object, set its source and toolbar properties, append it to the DOM, and access its workbook and activeSheet to apply a filter.

### Method
JavaScript (ES6 Module)

### Endpoint
N/A (Client-side JavaScript)

### Parameters
N/A

### Request Example
```javascript
import {
  TableauViz,
  FilterUpdateType
} from 'https://public.tableau.com/javascripts/api/tableau.embedding.3.latest.min.js';

const viz = new TableauViz();
viz.src = 'https://my-server/views/my-workbook/my-view';
viz.toolbar = 'hidden';

document.getElementById('tableauViz').appendChild(viz);

let sheet = viz.workbook.activeSheet;
sheet.applyFilterAsync("Container", ["Boxes"], FilterUpdateType.Replace);
```

### Response
N/A (Client-side interaction)
```

--------------------------------

### Get Logical Table Names

Source: https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/DataSource.html

Use getLogicalTablesAsync to retrieve all logical tables used in a data source. This example iterates through the tables and logs their captions.

```javascript
dataSource.getLogicalTablesAsync().then(function (logicalTables) {
  // Loop through each table that was used in creating this data source
  logicalTables.forEach(function (table) {
     console.log(table.caption);
  });
});
```

--------------------------------

### Apply Filter to Active Sheet in Workbook

Source: https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_interact.html

After obtaining the `viz` object, you can interact with the workbook. This example shows how to get the active sheet and apply a filter to it asynchronously.

```javascript
let sheet = viz.workbook.activeSheet;
sheet.applyFilterAsync("Container", "Boxes", FilterUpdateType.Replace);
```

--------------------------------

### Initializing with JavaScript

Source: https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_web_authoring.html

Configure and initialize an embedded view using JavaScript by creating a `TableauAuthoringViz` object.

```APIDOC
## Initializing with JavaScript

### Description
Configure and initialize an embedded view using JavaScript by creating a `TableauAuthoringViz` object. This method offers more control over the embedding process.

### HTML Setup
First, create a `<div>` in your HTML to contain the embedded view:
```html
<div id="tableauAuthoringViz"></div>
```

### JavaScript Initialization
Import the necessary objects from the Embedding API library and create a new `TableauAuthoringViz` instance. Remember to append the viz to the DOM to render it.

```javascript
import {
  TableauAuthoringViz,
  TableauEventType,
} from 'https://my-server/javascripts/api/tableau.embedding.3.latest.min.js';

const viz = new TableauAuthoringViz();

viz.src = 'https://my-server/authoring/my-workbook/my-view';
viz.hideCloseButton = true;
viz.addEventListener(TableauEventType.WorkbookPublished, handlePublished);

document.getElementById('tableauAuthoringViz').appendChild(viz);

// Ensure you have a handlePublished function defined to handle the event
function handlePublished() {
  console.log('Workbook published!');
}
```

### Importing JavaScript Files
If your JavaScript code is in a separate file, ensure it's imported with `type="module"`:
```html
<script type="module" src="./myEmbeddedCode.js"></script>
```
```

--------------------------------

### Configure package.json dependencies

Source: https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_get.html

Specify the library version in your package.json file. The tilde prefix allows for automatic updates to patched minor versions.

```json
"dependencies": {
    "@tableau/embedding-api": "~3.12.1"
  }
```

--------------------------------

### Get Underlying Data from a DataSource

Source: https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/DataSource.html

Retrieves all rows and columns from the underlying data of a specific data source. This example demonstrates how to find a data source by name and then extract unique values for a given field.

```javascript
const dataSources = await worksheet.getDataSourcesAsync();  
const dataSource = dataSources.find(datasource => datasource.name === "Sample - Superstore");  
const dataTable = await dataSource.getUnderlyingDataAsync();  
let field = dataTable.columns.find(column => column.fieldName === "Sub-Category");  
let list = [];  
for (let row of dataTable.data) {  
    list.push(row[field.index].value);  
}  
let values = list.filter((el, i, arr) => arr.indexOf(el) === i);  
console.log(values);
```

--------------------------------

### Declarative Event Handling with Web Components

Source: https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_event.html

Starting from Embedding API v3.3, you can declaratively handle events by specifying the event type attribute directly in the web component. This example shows how to handle the `onMarkSelectionChanged` event for a `<tableau-viz>` component.

```APIDOC
## Declarative Event Handling

### Description
Handle events directly within the web component using attributes.

### Example
```html
<tableau-viz id="tableauViz"
    src="http://my-server/views/my-workbook/my-view"
    onMarkSelectionChanged="handleMarksSelection">
</tableau-viz>
```

### Note
The `handleMarksSelection` function must be defined in your JavaScript code.
```

--------------------------------

### Simplified Configuration with Web Component Attributes

Source: https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_migration_guide.html

Configure viz initialization options directly as properties of the <tableau-viz> web component using HTML attributes, simplifying the process compared to v2's options object.

```html
<tableau-viz id="tableauViz" 
    src="http://my-server/views/my-workbook/my-view" 
    device="phone" toolbar="bottom" hide-tabs>
</tableau-viz>
```

--------------------------------

### Initialize Tableau Web Authoring View with JavaScript

Source: https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_web_authoring.html

Initialize a web authoring view using the `TableauAuthoringViz` object. Import the necessary components, create an instance, configure properties like `src` and `hideCloseButton`, add event listeners, and append it to the DOM.

```javascript
import {
  TableauAuthoringViz,
  TableauEventType,
} from 'https://my-server/javascripts/api/tableau.embedding.3.latest.min.js';

const viz = new TableauAuthoringViz();

viz.src = 'https://my-server/authoring/my-workbook/my-view';
viz.hideCloseButton = true;
viz.addEventListener(TableauEventType.WorkbookPublished, handlePublished);

document.getElementById('tableauViz').appendChild(viz);
```

--------------------------------

### Initialize v2 API (JavaScript)

Source: https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_migration_guide.html

v2 initialization involved creating a new tableau.Viz object, referencing the placeholder div and the viz URL.

```javascript
let placeholderDiv = document.getElementById("tableauViz");
let src = "http://my-server/views/my-workbook/my-view";
let options = {}
let viz = new tableau.Viz(placeholderDiv, url, options);
```

--------------------------------

### Set parameters during initialization using JavaScript

Source: https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_parameters.html

Demonstrates how to set parameters when initializing an embedded Tableau view using JavaScript by creating and appending `viz-parameter` elements.

```APIDOC
## Set parameters during initialization using JavaScript

### Description
If you are using JavaScript to initialize your embedding view, you can add parameters by creating a `viz-parameter` child node. You add the `vizParameter` node to the `viz` object before adding the `viz` object to the HTML page.

The following example shows the syntax you would use to create a parameter element that you can add to the `viz` object.

### Code Example
```javascript
const vizParameter = document.createElement("viz-parameter");
vizParameter.setAttribute("name", "parameter-name");
vizParameter.setAttribute("value", "parameter-value");
viz.appendChild(vizParameter);
```

The following example sets the Base Salary parameter to 75,000. To do this, you create the `vizParameter` element and then add attributes for `name` and a `value`, in this case, `Base Salary` and `75000` respectively. You then can append the `vizParameter` to the `viz`. You should add the `viz-parameter` child node before setting the `viz.src` URL.

### Code Example
```javascript
import {
  TableauViz,
  TableauEventType
} from "https://public.tableau.com/javascripts/api/tableau.embedding.3.latest.js";
      
const viz = new TableauViz();

const vizParameter = document.createElement("viz-parameter");
vizParameter.setAttribute("name", "Base Salary");
vizParameter.setAttribute("value", "75000");
viz.appendChild(vizParameter);

viz.src = "https://public.tableau.com/views/Superstore_800_600/CommissionModel";
viz.toolbar = "hidden";

document.getElementById("tableauViz").appendChild(viz);
```
```

--------------------------------

### launchAnalyticsAssistantAsync

Source: https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/AuthoringViz.html

Launches the Analytics Assistant side pane.

```APIDOC
## launchAnalyticsAssistantAsync()

### Description
Launches the Analytics Assistant side pane. It is recommended to check availability using `isAnalyticsAssistantAvailableAsync()` first.

### Returns
- **Promise<void>**
```

--------------------------------

### Initialize Tableau Viz with Event Listener

Source: https://help.tableau.com/current/api/embedding_api/en-us/tutorial/tutorial.htm

Creates a Tableau visualization instance, sets its dimensions and display options, and configures an event listener for when the viz becomes interactive. The workbook and active sheet are cached upon interaction.

```javascript
function initializeViz() {
  viz = document.getElementById("viz");
  viz.width = 1200;
  viz.height = 800;
  viz.hideTabs = true;
  viz.hideToolbar = true;

  const onFirstInteractive = () => {
    workbook = viz.getWorkbook();
    activeSheet = workbook.getActiveSheet();
  };

  viz.addEventListener(TableauEventType.FirstInteractive, onFirstInteractive);
  viz.src = "https://public.tableau.com/views/WorldIndicators_17297174004850/GDPpercapita";
}
```

--------------------------------

### Install Specific Version of Tableau React Package

Source: https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_react.html

To install a specific version of the Tableau Embedding API React library, append the desired version number to the installation command. Always verify compatibility with your Tableau host version.

```bash
npm i @tableau/embedding-api-react@3.12.1
```

--------------------------------

### Syntax for Creating Custom Parameters in JavaScript

Source: https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_parameters.html

Demonstrates how to programmatically create a custom parameter element in JavaScript before initializing the viz. The 'name' and 'value' attributes are set using setAttribute.

```javascript
const customParameter = document.createElement("custom-parameter");
customParameter.setAttribute("name", "parameter-name");
customParameter.setAttribute("value", "parameter-value");
viz.appendChild(customParameter);
```

--------------------------------

### Apply Filters During Initialization with Web Components

Source: https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_filter.html

Use `<viz-filter>` elements within the `<tableau-viz>` component to apply filters when the visualization loads. This method is only supported for `<tableau-viz>` components, not `<tableau-authoring-viz>`.

```html
<viz-filter field="name" value="value"> </viz-filter>
```

```html
<script type="module" src="https://public.tableau.com/javascripts/api/tableau.embedding.3.latest.min.js"></script>


<tableau-viz id="tableauViz"       
  src='https://public.tableau.com/views/Superstore_24/Overview'      
  toolbar="bottom" hide-tabs>
  <viz-filter field="Category" value="Technology"> </viz-filter>    
  <viz-filter field="State" value="California,Oregon,Washington"> </viz-filter>
</tableau-viz>
```

--------------------------------

### Clone an existing visualization instance

Source: https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizSettings.html

Use the `instance-id-to-clone` attribute to create a copy of an existing visualization. If the specified ID does not exist, the clone is based on the default visualization.

```html
<tableau-viz id="tableauViz"  instance-id-to-clone="id1" />
```

--------------------------------

### Get Filters on Worksheet

Source: https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/Worksheet.html

Gets the list of filters applied to a worksheet. Hierarchical filters are not currently supported. Ensure this is called within an async function.

```javascript
let filters = await worksheet.getFiltersAsync();
```

--------------------------------

### Initialize Tableau Viz with Filters and Parameters (Embedding API v3)

Source: https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_migration_guide.html

Use `<viz-filter>`, `<viz-parameter>`, and `<viz-range-filter>` elements as children of `<tableau-viz>` to configure initial filtering and parameters. This replaces URL parameters used in older versions.

```html
<tableau-viz id="tableauViz" 
    src="http://my-server/views/my-workbook/my-view" 
    device="phone" toolbar="bottom" hide-tabs>
    <viz-filter field="country" value="USA" />
    <viz-filter field="state" value="California,Texas,Washington"></viz-filter>
    <viz-parameter name="currency" value="dollars" />
    <viz-range-filter field="profit" min="0" max="10000"></viz-range-filter>
    <viz-relative-date-filter field="Date" anchor-date="March 17, 2001"
        period-type = "Year" range-type = "LastN" range-n = "2"></viz-relative-date-filter>
</tableau-viz>
```

--------------------------------

### Get Time Dimension from Pulse Metric - JavaScript

Source: https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/PulseActions.html

Gets the current time dimension applied to the Pulse metric. This method returns a Promise that resolves with the PulseTimeDimension object.

```javascript
pulse.getTimeDimensionAsync();
```

--------------------------------

### Apply Custom Parameters using JavaScript

Source: https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_parameters.html

Example of initializing a Tableau viz with JavaScript and adding a custom parameter to hide the Share button. Custom parameters must be added before the 'src' URL is assigned, and names require a colon prefix.

```javascript
import {
  TableauViz
} from "https://public.tableau.com/javascripts/api/tableau.embedding.3.latest.js";
     
// create viz object
const viz = new TableauViz();

// add custom parameter
const customParameter = document.createElement("custom-parameter");
customParameter.setAttribute("name", ":showShareOptions");
customParameter.setAttribute("value", "false");
viz.appendChild(customParameter);
 
// set src URL
viz.src="https://public.tableau.com/views/Superstore_800_600/Overview";
    
// add viz to HTML page
document.getElementById("tableauViz").appendChild(viz);
```

--------------------------------

### Declarative Event Handling for Web Authoring

Source: https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_event.html

This example demonstrates how to declaratively handle events for a web authoring component using the `<tableau-authoring-viz>` web component, specifically for the `onWorkbookPublished` event.

```APIDOC
## Declarative Event Handling for Authoring

### Description
Handle authoring-specific events directly within the web component.

### Example
```html
<tableau-authoring-viz id="tableauAuthoringViz"
    src="http://my-server/views/my-workbook/my-view"
    onWorkbookPublished="handleWorkbookPublish">
</tableau-authoring-viz>
```

### Note
The `handleWorkbookPublish` function must be defined in your JavaScript code.
```

--------------------------------

### Get Filters from Pulse Metric - JavaScript

Source: https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/PulseActions.html

Gets a list of filters currently applied to the Pulse metric. This method returns a Promise that resolves with an array of PulseFilter objects.

```javascript
pulse.getFiltersAsync();
```

--------------------------------

### Get Summary Data (Deprecated)

Source: https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/Worksheet.html

Gets the summary data table for a worksheet. This method is deprecated and may fail with worksheets containing many rows. Use getSummaryDataReaderAsync instead. Ensure this is called within an async function.

```javascript
let vizActiveSheet = viz.workbook.activeSheet;
if (vizActiveSheet.sheetType === "worksheet") {
  const dataTableReader = await vizActiveSheet.getSummaryDataReaderAsync();
  const dataTable = await dataTableReader.getAllPagesAsync();
  await dataTableReader.releaseAsync();
  // ... process data table ...
}
```

--------------------------------

### Retrieve Selected Data from Logical Table

Source: https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_data.html

This example demonstrates how to use `getLogicalTableDataReaderAsync` and `getAllPagesAsync` to retrieve up to 150,000 rows of native data from a specific logical table. It also shows how to release resources after data retrieval.

```APIDOC
## getLogicalTableDataReaderAsync and getAllPagesAsync

### Description
Retrieves selected data from a logical table within a data source. This method prepares rows to be read as pages and allows for specifying options like requesting only native data values for performance.

### Method Signature
`getLogicalTableDataReaderAsync(logicalTableId: string, maxRowsPerPage: number, options?: GetUnderlyingDataOptions): Promise<DataTableReader>`
`getAllPagesAsync(maxRows: number): Promise<DataTable>`
`releaseAsync(): Promise<void>`

### Parameters
#### `getLogicalTableDataReaderAsync` Parameters
- **logicalTableId** (string) - Required - The ID of the logical table to read data from.
- **maxRowsPerPage** (number) - Required - The maximum number of rows to prepare per page.
- **options** (GetUnderlyingDataOptions) - Optional - Options to configure data retrieval, such as `includeDataValuesOption`.
  - **includeDataValuesOption** (tableau.IncludeDataValuesOption) - Optional - Specifies the type of data values to include. Use `tableau.IncludeDataValuesOption.OnlyNativeValues` for improved performance when the data source has many columns.

#### `getAllPagesAsync` Parameters
- **maxRows** (number) - Required - The maximum number of rows to retrieve across all pages.

#### `releaseAsync` Parameters
None

### Request Example
```javascript
const dataSources = await worksheet.getDataSourcesAsync();
const dataSource = dataSources.find(datasource => datasource.name === "Sample - Superstore");
const logicalTables = await dataSource.getLogicalTablesAsync()
const dataTableReader = await dataSource.getLogicalTableDataReaderAsync(logicalTables[0].id, 10000,
    { includeDataValuesOption: tableau.IncludeDataValuesOption.OnlyNativeValues });
const dataTable = await dataTableReader.getAllPagesAsync(150000);
console.log(dataTable);
// release resources
await dataTableReader.releaseAsync();
```

### Response
#### `getLogicalTableDataReaderAsync` Success Response
- **DataTableReader** - An object that allows reading data in pages.

#### `getAllPagesAsync` Success Response
- **DataTable** - An object containing the retrieved data.

#### `releaseAsync` Success Response
- **void** - Indicates that resources have been successfully released.
```

--------------------------------

### getFiltersAsync

Source: https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/PulseActions.html

Gets a list of filters for the Pulse metric.

```APIDOC
## getFiltersAsync

### Description
Gets a list of filters for the Pulse metric.

### Method
getFiltersAsync

### Returns
Promise<PulseFilter[]> - The list of filters.
```

--------------------------------

### id

Source: https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/DataSource.html

Gets the unique string identifier for this data source.

```APIDOC
## id

### Description
Unique string representing this data source.

### Property
`id: string`
```

--------------------------------

### Initialize and Embed Tableau View with JavaScript

Source: https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_basic.html

Instantiate `TableauViz`, configure its properties (like `src` and `toolbar`), add event listeners, and append it to a DOM element. Note that instantiation alone does not render the view; it must be added to the DOM.

```javascript
import {
  TableauViz,
  TableauEventType,
} from 'https://my-server/javascripts/api/tableau.embedding.3.latest.min.js';

const viz = new TableauViz();

viz.src = 'https://my-server/views/my-workbook/my-view';
viz.toolbar = 'hidden';
viz.addEventListener(TableauEventType.MarkSelectionChanged, handleMarkSelection);

document.getElementById('tableauViz').appendChild(viz);

/*  Methods */

function handleMarkSelection() {
  alert('Mark(s) selected!');
  // code to handle the mark selection goes here
}
```

--------------------------------

### Export Workbook as PDF with Options

Source: https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_export.html

Export the entire workbook as a PDF, including all published sheets, using specified export options. This example demonstrates how to retrieve sheet names and apply custom PDF settings.

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>PDF Export</title>

<script type="module">
import { TableauViz, TableauEventType, PrintScaling, PrintPageSize, PrintOrientation  } from "https://public.tableau.com/javascripts/api/tableau.embedding.3.latest.min.js"

    const tableauViz = document.querySelector('tableau-viz');
    tableauViz.addEventListener(TableauEventType.FirstInteractive, (e) => {

        document.getElementById('export-pdf').onclick = async () => {
          const publishedSheetsInfo = tableauViz.workbook.publishedSheetsInfo;
          const selectedWorkbookSheetsForExport = Array.from(publishedSheetsInfo, (publishedSheetInfo) => publishedSheetInfo.name);
          const exportPDFOptions = {
            scaling: PrintScaling.Automatic,
            pageSize: PrintPageSize.Letter,
            orientation: PrintOrientation.Portrait,
          };
          tableauViz.exportPDFAsync(selectedWorkbookSheetsForExport, exportPDFOptions).then(() => {
            console.log(`Workbook: ${selectedWorkbookSheetsForExport.toString()}`);
            console.log('Options:', exportPDFOptions);
          });
        };
    });
</script>
<body>
    <div>
  <tableau-viz id="tableauViz"       
  src='https://public.tableau.com/views/Superstore_embedded_800x800/Overview'></tableau-viz>
     <button id="export-pdf">Export PDF</button>
    </div>
</body>
</html>

```

--------------------------------

### fields

Source: https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/DataSource.html

Gets an array of fields associated with this data source.

```APIDOC
## fields

### Description
An array of fields associated with this data source.

### Property
`fields: Field[]`
```

--------------------------------

### Configure package.json for ES Module

Source: https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_react.html

When using the library as an ES module, specify `"type": "module"` in your `package.json` file. This example also shows dependency versions.

```json
{
  "name": "tableau-viz-demo",
  "version": "0.1.0",
  "private": true,
  "type": "module",
  "dependencies": {
    "@tableau/embedding-api-react": "~3.12.1",
    "etc. ....": "this example is not complete"
    }
}
```

--------------------------------

### Embed Empty Workbook with Dynamic GUID

Source: https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_new_workbook.html

This JavaScript code demonstrates how to create and embed a new, empty Tableau workbook. It dynamically generates a unique GUID for the workbook URL and appends it to the `src` attribute of the `tableau-authoring-viz` web component. Replace `YOUR-SITE` with your actual site name.

```javascript
<!DOCTYPE html>
<html>
<head>
  <title>Simple Empty Workbook</title>
  <script type="module" >

  import {
    TableauAuthoringViz,
    TableauEventType,
  } from 'https://10ax.online.tableau.com/javascripts/api/tableau.embedding.3.latest.min.js';

    const viz = new TableauAuthoringViz();   // create the authoring viz object

    // construct unique GUID for URL
    const guid = crypto.randomUUID();
    console.log(`The UUID is: ${guid}`);
    let url=`https://10ax.online.tableau.com/t/YOUR-SITE/newWorkbook/${guid}`;
    console.log(url);

    viz.src = url;
    viz.height = "600";
    viz.width = "800";

    // add viz to HTML code
    document.getElementById('new-workbook').appendChild(viz);


  </script>
</head>
<body>
  <h2>This is an empty workbook</h2>
    <div id="new-workbook"></div>
</body>
</html>
```

--------------------------------

### getTimeDimensionAsync

Source: https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/PulseActions.html

Gets the current time dimension applied to the Pulse metric.

```APIDOC
## getTimeDimensionAsync

### Description
Gets the current time dimension applied to the Pulse metric.

### Method
getTimeDimensionAsync

### Returns
Promise<PulseTimeDimension> - The current time dimension.
```

--------------------------------

### Enable touch optimization

Source: https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/AuthoringViz.html

Enables touch-optimized controls for the visualization component.

```html
<tableau-viz id="tableauViz" touch-optimize />  
<tableau-authoring-viz id="tableauViz" touch-optimize />
```

--------------------------------

### Launch Analytics Assistant

Source: https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/AuthoringViz.html

Check availability before launching the Analytics Assistant side pane.

```javascript
const isAnalyticsAssistantAvailable = await viz.isAnalyticsAssistantAvailableAsync();  
if (isAnalyticsAssistantAvailable) {  
  await viz.launchAnalyticsAssistantAsync();  
}
```

--------------------------------

### name

Source: https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/DataSource.html

Gets the user-friendly name of the data source as displayed in the UI.

```APIDOC
## name

### Description
The user friendly name of the data source as seen in the UI.

### Property
`name: string`
```

--------------------------------

### Extracting Filter Domains

Source: https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_pulse_filter.html

This example demonstrates how to retrieve all filters and then extract field values from the domains of categorical filters using `getFiltersAsync` and `getDomainAsync`. It includes examples for retrieving all domain values, relevant domain values, and field values containing specific strings, utilizing pagination for large datasets.

```APIDOC
## Example using `getFiltersAsync` and `getDomainAsync`
The following code example shows how you might extract the field values from the domains of two categorical filters.
The code shows an event handler for a ‘`getFilters`’ button click event.
It performs the following steps:
  1. Retrieves all filters using `tableauPulse.getFiltersAsync()`.
  2. For the first filter, uses `filters[0].getDomainAsync()` and:
     * Retrieves all the available field values and logs the results.
     * Retrieves only the relevant field values and logs the results.
  3. For the second filter, uses `filters[1].getDomainAsync()` and:
     * Retrieves only the relevant domain values and logs the results.
     * Retrieves only the relevant field values that include the string ‘`foo`’ and logs the results.


The event handler uses pagination to retrieve all domain values in chunks (pages) until all values are retrieved. The initial page size is 100 and the page size adjusted based upon the total values available.
```javascript

// assumes a Pulse object has been created
// assumes there is a 'button' with the id 'getFilters' 

getFilters.onclick = async () => {
  const filters = await tableauPulse.getFiltersAsync();
  console.log('filters', filters);


  let domain = [];
  let page = undefined;
  let pageSize = 100;
  do {
    page = await filters[0].getDomainAsync('', pageSize, page?.nextPageToken, FilterDomainType.Database);
    domain = domain.concat(page.values);
    console.log(`Retrieved ${domain.length} of ${page.totalAvailable} field values`);
    pageSize = page.totalAvailable - domain.length;
  } while (page.nextPageToken);

  console.log('domain (database)', domain);

  domain = [];
  page = undefined;
  pageSize = 100;
  do {
    page = await filters[0].getDomainAsync('', pageSize, page?.nextPageToken, FilterDomainType.Relevant);
    domain = domain.concat(page.values);
    console.log(`Retrieved ${domain.length} of ${page.totalAvailable} field values`);
    pageSize = page.totalAvailable - domain.length;
  } while (page.nextPageToken);

  console.log('domain (relevant)', domain);


  domain = [];
  page = undefined;
  pageSize = 100;
  do {
    page = await filters[1].getDomainAsync('', pageSize, page?.nextPageToken, FilterDomainType.Relevant);
    domain = domain.concat(page.values);
    console.log(`Retrieved ${domain.length} of ${page.totalAvailable} field values`);
    pageSize = page.totalAvailable - domain.length;
  } while (page.nextPageToken);

  console.log('domain (relevant)', domain);

  domain = [];
  page = undefined;
  pageSize = 100;
  do {
    page = await filters[1].getDomainAsync('foo', pageSize, page?.nextPageToken, FilterDomainType.Relevant);
    domain = domain.concat(page.values);
    console.log(`Retrieved ${domain.length} of ${page.totalAvailable} field values`);
    pageSize = page.totalAvailable - domain.length;
  } while (page.nextPageToken);

  console.log('domain (foo)', domain);
};



Copy
```
```

--------------------------------

### jQuery Ready Handler for Initialization

Source: https://help.tableau.com/current/api/embedding_api/en-us/tutorial/tutorial.htm

A common pattern using jQuery to ensure that the viz initialization function is called only after the DOM is fully loaded and ready.

```javascript
$(initializeViz);
```

--------------------------------

### Handling UrlActionEvent

Source: https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/UrlActionEvent.html

Example of how to listen for and handle the TableauEventType.UrlAction event using an event listener.

```APIDOC
```javascript
function urlActionEventHandler(event) {
    console.log('URL: ' + event.detail.url);
    console.log('Target: ' + event.detail.target);
}

let viz = document.getElementById('tableauViz');
viz.addEventListener(TableauEventType.UrlAction, urlActionEventHandler);
```
```

--------------------------------

### Get filters

Source: https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_filter.html

Retrieve the collection of filters applied to a workbook or worksheet using `getFiltersAsync`.

```APIDOC
## Get filters

You can use the `getFiltersAsync` methods to retrieve the collection of filters in a workbook. The `dashboard.getFiltersAsync` method returns the list of filters used on the dashboard. The `worksheet.getFiltersAsync` method returns the list of filters in a worksheet. From the filters returned, you can use the filter properties to determine the filter types and their applied values.
```

--------------------------------

### Using the `<tableau-authoring-viz>` Web Component

Source: https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_web_authoring.html

Embed a web authoring view by using the `<tableau-authoring-viz>` web component. This is the simplest method for embedding and initializing the Embedding API.

```APIDOC
## Using the `<tableau-authoring-viz>` Web Component

### Description
Embed a web authoring view by using the `<tableau-authoring-viz>` web component. This is the simplest method for embedding and initializing the Embedding API.

### HTML Structure
```html
<tableau-authoring-viz id="tableauAuthoringViz"
  src='https://my-server/views/my-workbook/my-view'>
</tableau-authoring-viz>
```

### Attributes
- **id** (string) - Required - Identifies the instance of the web component. Used for programmatic access.
- **src** (string) - Required - The URL of the view on Tableau Server. Must use HTTPS.
```

--------------------------------

### getSummaryColumnsInfoAsync

Source: https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/Worksheet.html

Gets information about the columns that are returned by getSummaryDataAsync or getSummaryDataReaderAsync. Columns are sorted as they appear in the view.

```APIDOC
## getSummaryColumnsInfoAsync

### Description
Gets the columns that are returned with `getSummaryDataAsync` or `getSummaryDataReaderAsync`. The columns are sorted in the order that they appear in the view or in the View Data window. Note that `getSummaryDataReaderAsync` returns the summary data sorted with the columns in alphabetical (ascending) order. You can use method to determine the view order.

### Method
GET

### Endpoint
/api/v1/worksheets/{worksheetId}/summary/columns

### Returns
Promise<Column[]>
The array of columns that describe the data in the worksheet.
```

--------------------------------

### Initialize TableauViz Object (JavaScript)

Source: https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_migration_guide.html

Use this method to initialize the v3 API with more flexibility, similar to v2. You need to reference an HTML element to append the embedded viz. Creating the object does not render the view; it must be added to the DOM.

```html
<div id="tableauViz"></div>
```

```javascript
const viz = new TableauViz();

viz.src = 'https://my-server/views/my-workbook/my-view';
viz.toolbar = 'hidden';

document.getElementById('tableauViz').appendChild(viz);
```

--------------------------------

### VizSettings Properties

Source: https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizSettings.html

This section details the optional properties available for configuring VizSettings.

```APIDOC
## Properties

### `Optional`debug
debug?: boolean
Indicates whether the non-minified version of JavaScript is loaded. If specified (or set to true), the non-minified version is used for both the local component and the Tableau Server visualization (if enabled). If not specified (or set to false), the minified version of the JavaScript files are loaded.
```html
<tableau-viz id="tableauViz" debug />  
<tableau-authoring-viz id="tableauViz" debug />  
<tableau-ask-data id="tableauAskData" debug />
```

### `Optional`device
device?: DeviceType
Specifies a device layout for a dashboard, if it exists. Values can be default, desktop, tablet, or phone. If not specified, defaults to loading a layout based on the smallest dimension of the hosting iframe element.
```html
<tableau-viz id="tableauViz"  device="desktop" />
```

### `Optional`disableUrlActionsPopups
disableUrlActionsPopups?: boolean
Indicates whether to suppress the execution of URL actions. This option does not prevent the URL action event from being raised. You can use this option to change what happens when a URL action occurs. If set to true and you create an event listener for the URL_ACTION event, you can use an event listener handler to customize the actions.
```html
<tableau-viz id="tableauViz" disable-url-actions />
```

### `Optional`hideEditButton
hideEditButton?: boolean
Indicates whether the Edit button is hidden or visible. If not set, defaults to false, meaning that the Edit button is visible.
```html
<tableau-viz id="tableauViz" hide-edit-button>
```

### `Optional`hideEditInDesktopButton
hideEditInDesktopButton?: boolean
Indicates whether the Edit in Desktop button is hidden or visible. If not specified, defaults to false, meaning that the Edit in Desktop button is visible.
```html
<tableau-viz id="tableauViz" hide-edit-in-desktop-button>  
<tableau-authoring-viz id="tableauViz" hide-edit-in-desktop-button>
```

### `Optional`hideTabs
hideTabs?: boolean
Indicates whether tabs are hidden or shown.
```html
<tableau-viz id="tableauViz"  hide-tabs />
```

### `Optional`iframeAttributeClass
iframeAttributeClass?: string
The value of the 'class' attribute of the embedded iframe providing access to any custom selectors defined in the `<iframe-style>` child tag.
```html
<tableau-viz id="tableauViz" iframe-attr-class="red-border">  
  <iframe-style>  
    .red-border {  
      border: 1px solid red;  
    }  
  </iframe-style>  
</tableau-viz>
```

### `Optional`iframeAttributeLoading
iframeAttributeLoading?: string
The value of the 'loading' attribute of the embedded iframe. See: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#loading
```html
<tableau-viz id="tableauViz" iframe-attr-loading="lazy" />  
<tableau-authoring-viz id="tableauViz" iframe-attr-loading="lazy" />  
<tableau-pulse id="tableauPulse" iframe-attr-loading="lazy" />
```
```
Tokens:
Raw