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 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. Note that the values of Boolean properties are ignored. For example, if you were to add hide-tabs="false", this 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 embedding 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, alway use HTTPS when you specify the URL. <tableau-viz>, <tableau-authoring-viz>
hide-tabs Viz.hideTabs boolean Indicates whether 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 does not 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 does not 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>
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 start up. Additionally, 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. You can also use custom parameters when you are embedding Ask Data.

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 start up. 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. Note that 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 do not 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.

Size of the embedded view

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