---
schema_version: "1"
id: ef75fa5d6fd642597a1f2400d8600e96675dbc59126536c70b66a7a23fc18007
title: Add Event Listeners to the Embedded Tableau View
collection: tableau
version: next
locale: en-us
portal_url: https://docs.salesforce.com/tableau/next/en-us/api/embedding_api/docs/embedding_api_event.md
canonical_url: https://help.tableau.com/v0.0/api/embedding_api/en-us/docs/embedding_api_event.html
source_site: help.tableau.com
content_type: documentation
content_hash: 1d4c44931e5c2da06646c0291675d66d9aaf893f8e5f8dcd692830168c919975
description: Documentation for the Tableau Embedding API
---
# Add Event Listeners to the Embedded Tableau View

  

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.

* * *

## 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.

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

* * *

**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"
    src="http://my-server/views/my-workbook/my-view"
    onMarkSelectionChanged="handleMarksSelection">
</tableau-viz>

...
```

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

```
  ...

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

...
```

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 = marksSelected.data[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 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 ${event.type}`);
        // call methods to run immediately after loading
    
     });
}
```

  

#### On This Page