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
  • Example <tableau-viz> component configurations
  • Example <tableau-authoring-viz> component configuration
• Table of properties and values for embedded objects and components
  • Filter element for the <tableau-viz> web component
  • Parameter element for the <tableau-viz> web component
  • Custom parameter element for the <tableau-viz> and <tableau-authoring-viz> web components
  • Add iframe attributes
• Sizing the embedded view
  • How the height and width of the embedded view is determined
  • Resize the view following a window resize event

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.

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> 
Copy

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>

Copy

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>
Copy

For more information, see About custom parameters.

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.

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>

Copy

Sizing the embedded view

When you create the Tableau view or Pulse metric 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:

• By the height and width attributes set on the <tableau-viz> or <tableau-authoring-viz> components, or corresponding properties on the TableauViz and TableauAuthoringViz objects.

• If not specified, the size (width and height) of the view is based upon the content area specified by the enclosing HTML element (for example <div>or <body>).

• If the size of the content area specified by the HTML element is invalid (for example, height=0), the default size of the view is 800 (width) by 600 (height) pixels.

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>

Copy

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>

Copy

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