---
schema_version: "1"
id: 9030223494b5124d9748c5e1a3139225933eb77ea409720ba8a1fdf6106bbf40
title: Tableau JavaScript API Concepts--Initializing the API
collection: tableau
version: next
locale: en-us
portal_url: https://docs.salesforce.com/tableau/next/en-us/api/js_api/JavaScriptAPI/js_api_concepts_initializing.md
canonical_url: https://help.tableau.com/v0.0/api/js_api/en-us/JavaScriptAPI/js_api_concepts_initializing.htm
source_site: help.tableau.com
content_type: documentation
content_hash: c909d3d4dc7c8e8f565da8492c86ed67f98ded548fab650806dafdca1da56e16
description: Important changes for the Tableau JavaScript API
---
[Skip to main content](#main-content)

# Initialize the API

**Important changes for the Tableau JavaScript API**

As of February 2024, the Tableau JavaScript API is deprecated. Use the Embedding API v3 instead for embedding interactive views into web pages and applications. For guidance on embedding Tableau views, see the [Tableau Embedding API v3 Help](https://help.tableau.com/current/api/embedding_api/en-us/index.html).

The Tableau JavaScript API uses an object model. The entry point into the object model is to instantiate a new `Viz` object as follows:

```
var viz = new tableau.Viz( /* params omitted */ );
```

For most Tableau objects you can navigate back to the object's parent by means of parent properties.

## Create a Viz Object

There is only one entry point into the API: instantiating a new `Viz` object, which creates the HTML necessary to embed a Tableau visualization. To instantiate a new `Viz` object, call the `Viz` constructor and pass a reference to the div container on the HTML page, the URL of the visualization on Tableau Server, and a set of options.

```
var placeholderDiv = document.getElementById("tableauViz");
var url = "http://my-server/views/my-workbook/my-view";
var options = {
   hideTabs: true,
   width: "800px",
   height: "700px",
   onFirstInteractive: function() {
     // The viz is now ready and can be safely used.
   }
};
var viz = new tableau.Viz(placeholderDiv, url, options);
```

## Get the visualization URL

Not sure where to get the visualization URL? Navigate to your visualization on Tableau Server and then edit the URL from this:

http://my-server/#/views/my-workbook/my-view

To this:

http://my-server/views/my-workbook/my-view

If you do not remove the `#` symbol from the URL, you might see the following browser error:  
Refused to display `'http://my-server/#/views/my-workbook/my-view'` in a frame because it set 'X-Frame-Options' to 'SAMEORIGIN'.

## Specify Options

When you initialize a `Viz` object, you can pass options that specify how the view is initially rendered. The following list describes some of the some of the types of options that you can specify:

- Set a width and height for the visualization.
- Show or hide the toolbar and tabs.
- Apply filters.
- Call a callback function when the visualization becomes interactive or when the width and height are known.

For a full reference of the options that you can specify, see the [VizCreateOptions](https://help.tableau.com/v0.0/api/js_api/en-us/JavaScriptAPI/js_api_ref.htm#vizcreateoptions_record) record of the `Viz` constructor.

## Copy (Clone) an Existing Instance

When you initialize a `Viz` object, you can specify that the new instance should be copied (cloned) from an existing instance. This is useful if a user is working with a visualization but wants to try some new options or filters without affecting the state of the original visualization.

To clone an instance, you specify the `instanceIdToClone` option in the [VizCreateOptions](https://help.tableau.com/v0.0/api/js_api/en-us/JavaScriptAPI/js_api_ref.htm#vizcreateoptions_record) record for the `Viz` constructor. The cloned instance is assigned a new ID. The following example shows how you can use this option.

```
function clone(instanceId) {
    var url = "http://MY-SERVER/views/clone/demo";
    var newVizElement = $('<div class="viz-container"><button>Clone</button></div>')
               .appendTo('.content');

    var viz = new tableau.Viz(newVizElement[0], url, {
      instanceIdToClone: instanceId,
      usePublishedSize: true,
      hideToolbar: true
    });

    newVizElement.find('button').click(function() { clone(viz.getInstanceId())});
  }
  $(function() {
    clone(0);
  });
```

## Get Notification When the Viz Object is Ready

One of the options you can pass when you instantiate a `Viz` object is the `onFirstInteractive` parameter. This parameter references a callback function that's invoked when the `Viz` object has finished instantiating. This is an asynchronous callback, so your code can continue to run while the `Viz` object is instantiating.

The state of the `Viz` object is not valid until after the `onFirstInteractive` function is called. If you want to perform operations on the `Viz` object that require it to be fully initialized (for example, counting the number of sheets in the workbook), run your code after the `onFirstInteractive` callback has been invoked, like this:

```
var viz;
var options = {
  hideTabs: true,
  onFirstInteractive: function () {
    var sheetCount = viz.getWorkbook().getPublishedSheetsInfo().length;
};
viz = new tableau.Viz(div, url, options); 
```

Some operations that you might do with the `Viz` object do not require it to be completely initialized, such as adding event listeners to a `Viz` object. In those cases, you don't need to wait until the `onFirstInteractive` callback in order to run code to add the listeners. The following example shows code that adds a listener for the event that occurs when marks are selected. Notice that the code can run right after the `Viz` object initialization code, and doesn't need to be in the `onFirstInteractive` function.

```
var viz = new tableau.Viz(...);
viz.addEventListener(tableau.TableauEventName.MARKS_SELECTION, function (e) {
  // do something with the marks
});
```