Add Event Listeners

You can use event listeners to create actions based on events that happen with the view. The event listener registers a callback handler, that handler method gets called when an event occurs.

The viz object acts as the central event hub. This way you only have to go to one place for all events. It also means that events can be raised on an object that might not have been created yet. For example, the MarkSelectionChanged event can be raised for a particular sheet even though the sheet object hasn’t been created yet. Each event contains an anonymous object with information relating to that event, such as the sheet the event occurred on.

Listening to an event is done by calling viz.addEventListener(type, callback) and passing in a callback function. Here’s an example of listening to an event, where the name of the custom function is handleFirstInteractive(). You would define this function in your JavaScript code:

      const tableauViz = document.getElementById('tableauViz');
      tableauViz.addEventListener(TableauEventType.FirstInteractive, handleFirstInteractive);

There is an even easier way to add an event listener by adding an attribute to the <tableau-viz> or <tableau-authoring-viz> web component. Both of these methods are described in the following section.

In this section

Supported events

The Embedding API supports the following event types (TableauEventType). The type of event you can listen for depends upon whether you’re embedding a view (using a <tableau-viz> web component or TableauViz object, for example) or embedding web authoring (using a<tableau-authoring-viz> web component or TableauAuthoringViz object). Some events are available when you’re embedding a view in viewing mode. Others apply only for embedded web authoring. And some apply to both viewing and authoring.

TableauEventType String literal Web Attribute Description Component
CustomMarkContextMenuEvent "custommarkcontextmenu" onCustomMarkContextMenuEvent Raised when a custom mark context menu is clicked. See Add a Custom Context Menu Viewing
CustomViewLoaded "customviewloaded" onCustomViewLoaded Raised when a custom view has finished loading. This event is raised after the callback function for FirstInteractive (if any) has been called. Viewing
CustomViewRemoved "customviewremoved" onCustomViewRemoved Raised when a custom view has been removed. Viewing
CustomViewSaved "customviewsaved" onCustomViewSaved Raised when a custom view has been saved (newly created or updated). Viewing
CustomViewSetDefault "customviewremoved" onCustomViewSetDefault Raised when a custom view has been set as the default view for a workbook. Viewing
EditButtonClicked "editbuttonclicked" onEditButtonClicked Raised when the user clicks the Edit button. Viewing
EditInDesktopButtonClicked "editindesktopbuttonclicked" onEditInDesktopButtonClicked Raised when the user clicks the Edit In Desktop button. Authoring, Viewing
FilterChanged "filterchanged" onFilterChanged Raised when any filter has a changed state. Viewing
FirstInteractive "firstinteractive" onFirstInteractive Raised when the viz first becomes interactive after loading. Authoring, Viewing
FirstVizSizeKnown "firstvizsizeknown" onFirstVizSizeKnown Raised when the size of the viz object is known. You can use this event to perform tasks such as resizing the elements surrounding the viz object after the object’s size has been established. Authoring, Viewing
MarkSelectionChanged "markselectionchanged" onMarkSelectionChanged Raised when the selected marks in a viz have changed. Viewing
ToolbarStateChanged "toolbarstatechanged" onToolbarStateChanged Raised when a toolbar button or control becomes available or becomes unavailable. Viewing
TabSwitched "tabswitched" onTabSwitched Raised after a tab switch occurs (the active sheet has changed). Guarantees the viz object will be interactive after this. Viewing
ParameterChanged "parameterchanged" onParameterChanged A parameter has had its value modified. You can use this event type with Parameter objects. Viewing
UrlAction "urlaction" onUrlAction Raised when Raised when a URL action occurs. See the UrlActionEvent class. Viewing
WorkbookPublished "workbookpublished" onWorkbookPublished Raised when the workbook has been published. Authoring
WorkbookPublishedAs "workbookpublishedas" onWorkbookPublishedAs Raised when “publish as” is successful. Authoring
WorkbookReadyToClose "workbookreadytoclose" onWorkbookReadyToClose Raised when the workbook is ready to close. Authoring

Note Use the TableauEventType enum (for example, TableauEventType.MarkSelectionChanged) when you add or remove the event listener using the Tableau Embedding API and the addEventListener and removeEventLister methods.

Using simplified event handling

Starting in Embedding API v3 (version 3.3), you can link your custom event handler to an event declaratively in the <tableau-viz> or <tableau-authoring-viz> web component by specifying the event type attribute.

The following example calls a JavaScript function to handle the onMarkSelectionChanged event. When a onMarkSelectionChanged event occurs, the handleMarksSelection() event handler is called. You define the event handler in your JavaScript code.


<tableau-viz id="tableauViz"


The following example shows a web authoring component that adds an event listener to handle a published event.


<tableau-authoring-viz id="tableauAuthoringViz"


Before v3.3, you could only configure an event listener in JavaScript using the addEventListener method. The event type attribute makes it easy to add custom event handlers.

Add an event listener using the addEventListener() method

  1. Get the viz object.

  2. Add the event listener by calling addEventListener and specifying the type of event and the callback method to call. The name of the event must be one of the supported types defined in the TableauEventType enumeration. The callback method must handle the event object raised.

     async function getSelectedMarks(event) {
         const marksSelected = await event.detail.getMarksAsync();
         const numMarks =[0].data.length;
         console.log(`${numMarks} marks Selected`);
     let viz = document.getElementById('tableauViz');
     viz.addEventListener(TableauEventType.MarkSelectionChanged, getSelectedMarks);

Remove an event listener

  1. Get the viz object.
  2. Remove the event listener from the specified event using the
  3. Remove the event listener by using the removeEventListener method and specifying the name of your event handler. For example, to remove the event handler for the TableauEventType.MarkSelectionChanged event called, getSelectedMarks you might use something like the following:

     let viz = document.getElementById('tableauViz');
     viz.removeEventListener(TableauEventType.MarkSelectionChanged, getSelectedMarks);

Add an event listener after the viz is first loaded

In some cases you might want to take actions right after the view is first loaded. For example, you might want to set the filtering or perform some other customization for the person who is viewing the embedded viz. You can do this by adding an event listener on TableauEventType.FirstInteractive event type. In addition, you can wrap the call in a window.onload event handler, so that your FirstInteractive event is called after all the dependent resources have been loaded.

window.onload = function () {
   let viz = document.getElementById('tableauViz');

    viz.addEventListener(TableauEventType.FirstInteractive, async (event) => {
        console.log(`Event type is ${eventType}`);
        // call methods to run immediately after loading