Interact with the View

After you initialize the <tableau-viz> or <tableau-authoring-viz> web component and configure it during initial load, you will likely want to be able to interact with the view, to apply and change filters, add or remove event listeners, change parameters, or query data. You can do this with the Embedding API v3 by creating a JavaScript object from the web component. After you have the object, you can use the Embedding API to interact with the view. The following topic will show you how this is done.

In this section

Accessing the Tableau web component

After you add a <tableau-viz> or <tableau-authoring-viz> component in your HTML page, you need to use the document.querySelector() or document.getElementById() method if you want to access the viz for further customization using JavaScript and the Embedding API. The document.querySelector() method is faster and returns the first element that matches the specified selector, in this case the <tableau-viz> component.

const viz = document.querySelector("tableau-viz");

If your web page has multiple embedded views, use document.getElementById(). If you use document.getElementById(), it’s important that you set the id for the web component so that you can access the component later for further interaction. Without the viz object you can’t perform additional actions.

For example, to change the filters applied to a view (identified with the id of tableauViz), you might use the following code snippet.

const viz = document.getElementById('tableauViz');

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.

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.