Configure Embedding Objects and Components


The Embedding API v3 provides a rich set of properties that you can apply to the embedding view or embedded web authoring view. These properties can control the device layout and dimensions of the view, or whether the buttons and the toolbar are hidden or visible. You can set properties during initialization, or later interactively, by accessing the JavaScript TableauViz or TableauAuthoringViz object.

In this section

How to configure the TableauViz and TableauAuthoringViz objects and components

To configure the embedded viz, you can use a set of HTML attributes on the <tableau-viz> and <tableau-authoring-viz> web components, or as JavaScript (JS) properties on the corresponding TableauViz and TableauAuthoringViz JavaScript objects. For HTML attributes that accept a value, such as width, height, and device, the syntax is <property>="<value>".

For Boolean properties, such as hide-tabs, hide-close-button, or disable-url-actions, you can either include the flag to effectively set it to true, or omit it to effectively set it to false. The values of Boolean properties are ignored. For example, if you were to add hide-tabs="false", this flag actually sets the hide-tabs value to true, because the presence of the attribute sets it to true even if the value is false. Some attributes and properties apply to both embedded views and embedded authoring views.

Example <tableau-viz> component configurations

The following example shows how you can specify options to initialize the viz by setting attributes on the <tableau-viz> element:

<tableau-viz id="tableauViz"
  src="https://my-server/views/my-workbook/my-view"
  device="phone" toolbar="bottom" hide-tabs>
</tableau-viz>

Example <tableau-authoring-viz> component configuration

The following example shows how you can specify options to initialize the viz by setting attributes on the <tableau-authoring-viz> element:

<tableau-authoring-viz id="authoringViz"
  src='https://my-server/views/my-workbook/my-view'
  width="800" height="600">
</tableau-authoring-viz>

Table of properties and values for embedded objects and components

The following table lists the properties you can add to the <tableau-viz> and <tableau-authoring-viz> web components, or as JavaScript (JS) properties on the corresponding TableauViz and TableauAuthoringViz JavaScript objects.

HTML Property JS Property Accepted Values Description Applies to
src Viz.src string Specifies the URL of the view. For security, always use HTTPS when you specify the URL. <tableau-viz>, <tableau-authoring-viz>
hide-tabs Viz.hideTabs boolean Indicates whether the tabs are hidden or shown. <tableau-viz>
toolbar Viz.toolbar “top”, “bottom”, “hidden” Indicates the position of the toolbar or if it should be hidden <tableau-viz>
height Viz.height (e.g. “800px”) Can be any valid CSS size specifier. If not specified, defaults to the published height of the view. See Size of the embedded view. <tableau-viz>, <tableau-authoring-viz>
width Viz.width (e.g. “800px”) Can be any valid CSS size specifier. If not specified, defaults to the published width of the view. See Size of the embedded view. <tableau-viz>, <tableau-authoring-viz>
device Viz.device “default”, “desktop”, “tablet”, or “phone” Specifies a device layout for a dashboard, if it exists. If not specified, defaults to loading a layout based on the smallest dimension of the hosting iframe element. <tableau-viz>
instance-id-to-clone Viz.instanceIdToClone   Specifies the ID of an existing instance to make a copy (clone) of. This is useful if the user wants to continue analysis of an existing visualization without losing the state of the original. If the ID doesn’t refer to an existing visualization, the cloned version is derived from the original visualization. <tableau-viz>
disable-url-actions Viz.disableUrlActions boolean Indicates whether to suppress the execution of URL actions. This option doesn’t prevent the URL action event from being raised. <tableau-viz>
hide-close-button Viz.hideCloseButton boolean Indicates whether the Close button is shown or hidden. If not specified, defaults to false (the button is shown). This property also includes the “File/Close” menu item. <tableau-authoring-viz>
hide-edit-button Viz.hideEditButton boolean Indicates whether the Edit button is shown or hidden. If not specified, defaults to false (the button is shown). <tableau-viz>
hide-edit-in-desktop-button Viz.hideEditInDesktopButton boolean Indicates whether the Edit in Desktop button is shown or hidden. If not specified, defaults to false (the button is shown). <tableau-viz>, <tableau-authoring-viz>
iframe attributes     See iframe attributes <tableau-viz>, <tableau-authoring-viz>
suppress-default-edit-behavior Viz.suppressDefaultEditBehavior boolean Indicates whether the default edit behavior should be suppressed. If not specified, defaults to false (the default edit behavior is preserved). When set to true, this property suppresses what is normally done when the Close button, Edit button, or Edit in Desktop buttons are clicked. <tableau-viz>, <tableau-authoring-viz>
token Viz.token JSON Web Token Holds the credentials and permissions. Only used for connected apps or external authorization services (EAS). See Authentication and Embedded Views. Not used for passwords or personal access tokens. <tableau-viz>, <tableau-authoring-viz>, <tableau-pulse>

Note: When adding properties to the <tableau-viz> or <tableau-authoring-viz> components, use the HTML Property name. Use the JS Property names for the TableauViz and TableauAuthoringViz objects.

Filter element for the <tableau-viz> web component

In addition to the attributes shown in the table for the web components, you can also apply a <viz-filter> element to the <tableau-viz> web component to filter the view during initialization. The <viz-filter> element has two attributes: the field and its value.

<viz-filter field="name" value="value"></viz-filter>

For more information about applying filters, see Filter during initialization.

Parameter element for the <tableau-viz> web component

In addition to the attributes shown in the table for the <tableau-viz> web component, you can also apply a <viz-parameter> element to the web component during initialization. The <viz-parameter> element has two attributes: the name and its value.


<viz-parameter name="parameter-name" value="parameter-value"></viz-parameter>

The parameter settings take effect at startup. Also, the Embedding API v3 library supports the methods Workbook.getParametersAsync() and Workbook.changeParameterValueAsync(). For more information, see Use Parameters in Embedded Views.

Custom parameter element for the <tableau-viz> and <tableau-authoring-viz> web components

In addition to the attributes shown in the table for the <tableau-viz> and <tableau-authoring-viz> web components, you can also apply a <custom-parameter> element to the web component during initialization.

The <custom-parameter> element allows you to pass parameters to the viz that aren’t supported by the Embedding API, but are supported in Tableau. The <custom-parameter> has two attributes: the name and its value. The parameter settings take effect at startup. The custom parameters can be used to add URL parameters, as listed under Embed Code Parameters for Views for prior versions of embedding. For example, you could use custom parameters to suppress tooltips (:tooltip), or to hide the Share (:showShareOptions) or Data Details (:dataDetails) buttons in the toolbar. Some of these URL parameters might not work, or might not be supported in the future.

<custom-parameter name=":showShareOptions" value="false"></custom-parameter>

For more information, see About custom parameters.

Note: The attributes you place on the web component or viz object on the client are made available to the browser in order to render the embedded visualization. These attributes don't affect security. Tableau secures content by way of authentication and user permissions. If a user can't be authenticated and doesn't have the correct permissions the content is inaccessible behind a login screen.

Add iframe attributes

The Tableau Embedding API provides some attributes that you can apply to the iframe element. You can use these attributes to customize the border that surrounds the Tableau view. You can also specify when the content of the iframe is loaded, to improve page load times and responsiveness.

HTML Property JS Property Accepted Values Description Applies to
iframe-attribute-class Viz.iframeAttributeClass string The value of the ‘class’ attribute of the embedded iframe providing access to any custom selectors defined in the <iframe-style> child tag. See iframe-attr-class. <tableau-viz>, <tableau-authoring-viz>
iframe-attr-loading Viz.iframeAttributeLoading string Specifies the embedding loading attribute of the <iframe>. Options include eager (default), which loads the iframe on page load; and lazy, which defers loading the iframe until it becomes close to the visual viewport. See iframe-attr-loading. <tableau-viz>, <tableau-authoring-viz>
iframe-attr-style Viz.iframeAttributeStyle string iframe-attr-style component attribute, which allows for specifying inline styles on the embedded <iframe>. <tableau-viz>, <tableau-authoring-viz>

Example of iframe attributes

The following example shows how you might configure a <tableau-viz> web component to use the iframe attributes.

This example uses the iframe-attr-loading="lazy" option, which can potentially help with the page loading time. With the “lazy” setting, the iframe containing the Tableau viz isn’t loaded until it’s close to being scrolled into the viewport. This setting might be helpful if you have a complex web application that contains embedded content that might not be initially visible in the browser window.

The example also adds formatting to the iframe that contains the embedded content. The <iframe-style> defines a .red-border class. The red-border class is then applied to the HTML <tableau-viz> web component (iframe-attr-class="red-border).


    <tableau-viz id="tableauViz" src="https://public.tableau.com/views/DeveloperSuperstore/Overview"
      iframe-attr-loading="lazy" iframe-attr-class="red-border">
      <viz-filter field="YEAR(Order Date)" value="2022"></viz-filter>
      <iframe-style>
        .red-border { border: 5px solid red !important; }
      </iframe-style>

    </tableau-viz>

Sizing the embedded view

When you create the Tableau view for embedding you must consider the size of the view and how it fits into your web application. The dimensions you choose for your viz are one of the factors you must plan for. Another consideration is the layout of your web application and where you want to position the embedded viz. You also must think about how your users will be viewing your application and what you want that experience to be like.

For information about how to go about laying out your dashboard in Tableau, see Size and Lay Out Your Dashboard. Depending upon the size of the browser window, for example, the device layout of your embedded view might automatically switch to Tablet or Phone, preview those layouts and configure them accordingly. For more information, see Create Dashboard Layouts for Different Device Types. Also check out Optimize Workbook Performance for advice on how to improve your design and the performance of your embedded view.

For example, if you’re creating a dashboard that you intend to embed, you might choose fixed dimensions for the default size. In addition, when you place objects and layouts in your dashboard you might set them as tiled rather than floating. That way, when users resize their browser windows, the dashboard doesn’t rearrange itself in ways that you didn’t intend, and layouts don’t pop up and appear in other places.

When you’re building your web application, experiment with the web layout. Try setting the dimensions of your viz using the height and width attributes. Ensure that the values for the container or <div> can show your viz the way you want. Use CSS attributes to create responsive layouts (width: calc(100vw - 64px) that are scaled to the dimensions of the browser. Set the default size of the Tableau view as Automatic, so that it’s automatically resized to fit any screen it is displayed on.

How the height and width of the embedded view is determined

The height and width of the embedded view is determined in the following order:

Resize the view following a window resize event

To make your web application more responsive whenever the browser window is resized, or whenever there’s a screen orientation change, use the resize method on the Tableau Viz and AuthoringViz objects to readjust the dimensions of the embedded view.

First, set up an event listener for the window resize event and then set the TableauViz or TableauAuthoringViz resize() method as the event handler. Then test your code to see if the embedded viz is resized and displayed how you want after changing the size of the browser window.


  <script type="module">
    import { TableauEventType } from 'https://public.tableau.com/javascripts/api/tableau.embedding.3.latest.min.js';
    const tableauViz = document.getElementById('tableauViz');
    window.addEventListener('resize', () => tableauViz.resize());
  </script>

Example viz using iframe attributes and resize

The following example code uses the windows attributes to set a border on the iframe that contains the embedded viz. The example also sets up an event listener to resize the viz anytime the browser window changes.


<!DOCTYPE html>
<html>
  <script type="module" src="https://public.tableau.com/javascripts/api/tableau.embedding.3.latest.min.js"></script>
  <style>
    html,
    body {
      margin: 2px;
    }

    #main {
      width: calc(100vw - 364px);
      height: calc(100vh - 464px);
    }

  </style>
</head>
<body>
  <div id="main">
    <tableau-viz id="tableauViz" src="https://public.tableau.com/views/DeveloperSuperstore/Overview"
      iframe-attr-loading="lazy" iframe-attr-class="fun red-border">
      <viz-filter field="YEAR(Order Date)" value="2022"></viz-filter>
      <iframe-style>
        .red-border { border: 5px solid red !important; }
        .fun { box-shadow: 0px 0px 37px 0px #000000; transform: perspective(250px) rotateY(2deg) scale(0.75); }
      </iframe-style>

    </tableau-viz>
  </div>
  <script type="module">
    import { TableauEventType } from 'https://public.tableau.com/javascripts/api/tableau.embedding.3.latest.min.js';
    const tableauViz = document.getElementById('tableauViz');
    window.addEventListener('resize', () => tableauViz.resize());
  </script>
</body>
</html>

Here’s what that example code looks like. Resize the browser window to see how the view is resized to fit the display.

.red-border { border: 5px solid red !important; } .fun { box-shadow: 0px 0px 37px 0px #000000; transform: perspective(250px) rotateY(2deg) scale(0.75); }