Tableau Embedding API v3 Tutorial

This tutorial is a sample web application, created with the Tableau Embedding API v3. It's designed to help you explore and learn about the API using a series of steps that guide you through the basics. To get started, click the button below.

Note This tutorial uses the Tableau Embedding API v3 (tableau.embedding.3.latest.js). The Tableau Embedding API v3 is a replacement for the Tableau JavaScript API v2. Tableau's Embedding API v3 features a redesigned process for embedding to make your life easier, to modernize the experience, and enable new functionalities.

Tip If you are viewing this tutorial on an iPad or tablet, be sure to select website settings for Mobile devices in your browser. If you use Desktop settings, you might be unable to scroll as expected, as taps are considered mouse clicks.

The view will load here after you click Run this code, below.

Show .js file

Create the Viz

As you build your web application the first step is to create, or instantiate the view. You can do this in several ways. The simplest approach is to use the <tableau-viz> web component. You can customize the view by setting attributes on the component in your HTML code. For a more dynamic and customizable solution, you can create the view using JavaScript. However, for the most flexibility and greater ease of use, you can combine these two approaches, using the web component and the Embedding API v3 methods. In this tutorial we show you how to do this.

The basic process is as follows:

  1. Add a <tableau-viz id="tableauViz"></tableau-viz> custom web component in your HTML code.
  2. In your JavaScript code, retrieve the element using viz = document.getElementById("tableauViz"). This returns an instance of the TableauViz class.
  3. Provide configuration options such as viz.hideTabs and viz.hideToolbar.
  4. Set the viz.src property to your workbook URL.

Here's the JavaScript code:

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";
}     

You should now see a view with which you can interact, just like you can with views on Tableau.

In the code above, setting the viz.src property handles loading the view. Adding a FirstInteractive event listener allows you to perform actions once the view has finished loading. In this case, the function caches the workbook and activeSheet variables so they can be used later on. These two variables were declared as global variables in the actual script. Typically you'll want to create the view when the page has finished loading and the browser is ready. If you're using jQuery, this can be done using jQuery's ready handler:

$(initializeViz);