---
schema_version: "1"
id: 942ef49948de14ab5eb1e7dc8672c7003b23cf9d6ba005308b60d17be0a5fc10
title: Use Parameters in Embedded Views
collection: tableau
version: current
locale: en-us
portal_url: https://docs.salesforce.com/tableau/current/en-us/api/embedding_api/docs/embedding_api_parameters.md
canonical_url: https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_parameters.html
source_site: help.tableau.com
content_type: documentation
content_hash: dc93a1061da2bce655febad22af963a6fcf81a858bc50a13aa8cbcd58a2aca4a
description: Documentation for the Tableau Embedding API
---
# Use Parameters in Embedded Views

  

You can use parameters to add interactivity and flexibility to a view. A parameter is a Tableau workbook variable that can replace a constant value in a calculation, filter, or reference line. You can either apply parameters before a visualization has been loaded (at initialization) or after it has been rendered (interactively). The Embedding API provides methods for getting the parameters in a workbook and for changing parameter values. You can also set up event handlers to take action whenever a parameter change occurs (`TableauEventType.ParameterChanged`). You can set parameter values using the `<tableau-viz>` web components or using the `TableauViz` JavaScript object. The Tableau parameters (`VizParameter` attribute or `<viz-parameter>` element) can be set when you are embedding a view in viewing mode, but not when embedding a view in web authoring mode.

In addition to the parameters found in a Tableau workbook, you can add some custom parameters that get passed to the view. These custom parameters (`CustomParameter` or `<custom-parameter>`) provide attributes that are not officially supported by Embedding API, but are supported by Tableau Server and Tableau Cloud. Only a specific set of custom parameters can be used. For more information, see [About custom parameters](#about-custom-parameters).

* * *

## About changing parameter values

When you set parameter values, either during initialization or after the view has loaded, the value you specify for a parameter must fall within the allowable values defined for the parameter. If the new value is out of range, the updated value will be set to either the `minValue` or the `maxValue` of the allowable range. If a step size is also specified and the new value does not fall on the step intervals, the updated value will be set to the closest, lower step, or closest, earlier date. If the domain restriction is type `ParameterValueType.List`, and there are aliases defined for the list, the aliased value should be specified. For more information about parameter values, see [Create Parameters](https://help.tableau.com/current/pro/desktop/en-us/parameters_create.htm) in Tableau Help.

You can use the Embedding API to query a parameter object to find out the `name`, the `allowableValues`, the `currentValue`, and the `dataType` for the parameter. You can also use the `changeValueAsync` method to change a parameter value. See [Get and change parameters from the workbook](#get-and-change-parameters-from-a-workbook).

* * *

### Set parameters during initialization using web components

You can initialize the view with parameters settings the same way you can initialize the view by adding filter elements to the `<tableau-viz>` web component. To specify a parameter, you add a `<viz-parameter>` element and provide a `name` and `value` pair.

```

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

```

For example, the following shows how you might set a parameter using the `<tableau-viz>` web component. The parameter value is applied when the view is first rendered. In this example, the Base Salary is set to 75,000.

```
<tableau-viz id="tableauViz"       
  src='https://https://public.tableau.com/views/Superstore_embedded_800x800/CommissionModel'      
  toolbar="bottom" hide-tabs>
  <viz-parameter name="Base Salary" value="75000"></viz-parameter>
</tableau-viz>

```

* * *

### Set parameters during initialization using JavaScript

If you are using JavaScript to initialize your embedding view, you can add parameters by creating a `viz-parameter` child node. You add the `vizParameter` node to the `viz` object before adding the `viz` object to the HTML page.

The following example shows the syntax you would use to create a parameter element that you can add to the `viz` object.

```

const vizParameter = document.createElement("viz-parameter");
vizParameter.setAttribute("name", "parameter-name");
vizParameter.setAttribute("value", "parameter-value");
viz.appendChild(vizParameter);


```

The following example sets the Base Salary parameter to 75,000. To do this, you create the `vizParameter` element and then add attributes for `name` and a `value`, in this case, `Base Salary` and `75000` respectively. You then can append the `vizParameter` to the `viz`. You should add the `viz-parameter` child node before setting the `viz.src` URL.

```

import {
  TableauViz,
  TableauEventType
} from "https://public.tableau.com/javascripts/api/tableau.embedding.3.latest.js";
      
const viz = new TableauViz();

const vizParameter = document.createElement("viz-parameter");
vizParameter.setAttribute("name", "Base Salary");
vizParameter.setAttribute("value", "75000");
viz.appendChild(vizParameter);

viz.src = "https://public.tableau.com/views/Superstore_800_600/CommissionModel";
viz.toolbar = "hidden";

document.getElementById("tableauViz").appendChild(viz);

```

* * *

### Change parameters interactively (after initialization)

You can change the value of a parameter after the embedded view has loaded by using the workbook method [`changeParameterValueAsync()`](/current/api/embedding_api/en-us/reference/interfaces/workbook.html#changeparametervalueasync). To use this method, you must first access the embedded `viz` object. As described in [Interact with the View](/current/api/embedding_api/en-us/docs/embedding_api_interact.html), you can get the `viz` object using the `document.getElementbyId()` method.

The [`Workbook.changeParameterValueAsync()`](/current/api/embedding_api/en-us/reference/interfaces/Workbook.html#changeparametervalueasync) method takes two arguments, the name of the parameter and the new value. Note that the new value must match the allowable values for the parameter.

For example, the following code example is a standalone web page that embeds a Tableau view. The example uses an input form that allows a users to change the `Base Salary` parameter values in increments of 1000. The minimum value (`0`) and the step interval match the allowable values for the `Base Salary` parameter.

```

<!DOCTYPE html>
<html>
  <head>
    <title>Change Parameters</title>

  <script type="module" src="https://public.tableau.com/javascripts/api/tableau.embedding.3.latest.js"></script>
  
<script>

  async function setVizParam() {
    let viz = document.getElementById("tableauViz");
    try {
        let newBase = document.getElementById("newSalary").value;
        await viz.workbook.changeParameterValueAsync("Base Salary", newBase); 

    } catch (error) {
        console.log (error);
    };
}

  </script>
  </head>
  <body>
    <h1>Embedding API v3 Demo - Change Parameters</h1>
    <form id="resizeForm">
        <input type="number" min="0" step="1000" id="newSalary" placeholder="Base Salary">
        <button type="button" onClick="setVizParam();">Change Parameter</button>
    </form>
    <div id="main" >
      <tableau-viz
        id="tableauViz"
        src="https://public.tableau.com/views/Superstore_800_600/CommissionModel"
        toolbar="hidden" hide-tabs>
    </tableau-viz>
    </div>
  
  </body>
</html>

```

Here’s what that code looks like when it is embedded in a web page.

### Embedding API v3 Demo - Change Parameters

 Change Parameter

* * *

### Get and change parameters from a workbook

You can use the [`Workbook.getParametersAsync()`](/current/api/embedding_api/en-us/reference/interfaces/Workbook.html#getparametersasync) method to access all the parameters available in a workbook. The method returns an array of parameter objects.

For example, the following code snippet assumes that you have already created a `Viz` object and have used `tableauViz` as the identifier. The example uses the `Workbook.getParametersAsync()` method to access the parameters. The snippet then prints the names of all the parameters and their current values in the debugging tools console.

```

async function getParameterNames() {
  let viz = document.getElementById("tableauViz");
  const parameters = await viz.workbook.getParametersAsync();
  parameters.forEach( (p) => {
    console.log(p.name, p.currentValue.value);
  });
};

```

You could also use the `getParametersAsync()` method to get a specific parameter object, and then use that object and the [`Parameter.changeValueAsync()`](/current/api/embedding_api/en-us/reference/interfaces/Parameter.html#changevalueasync) method to assign the parameter a new value.

```

async function setParamFunc() {

let viz = document.getElementById("tableauViz");
try {
      const parameters = await viz.workbook.getParametersAsync();
      const baseSalary = parameters.find( (p) => p.name == "Base Salary");
      newVal = await baseSalary.changeValueAsync("75000");
      console.log(newVal);
} catch (error) {
      console.log (error);
  };

  }
```

* * *

## About custom parameters

Using the Embedding API, you can add custom parameters. These are not like the parameters in a Tableau workbook. These custom parameters (`CustomParameter` or `<custom-parameter>`) provide attributes that are not officially supported by Embedding API, but are supported by Tableau Server and Tableau Cloud. Specifically, you can use some of the [URL parameters for iframe tags](https://help.tableau.com/current/pro/desktop/en-us/embed_list.htm#URL_params) for views that you might have used with previous versions of the embedding JavaScript API. Note that the parameters listed in the URL parameters for iframe tags might not work or might not be supported in the future. Custom parameters can be used when you are embedding a viz in viewing mode and in web authoring mode.

### Apply custom parameters during initialization using web components

Setting custom parameters is relatively easy when you use the Tableau viz web components. Just add the `<custom-parameter>` element to the web component. The element takes two attributes, the name of the parameter and its value. Note that when you specify the name of the parameter, you must use the URL parameter name as listed in the [URL parameters for iframe tags](https://help.tableau.com/current/pro/desktop/en-us/embed_list.htm#URL_params). These names take a colon prefix (`:`), for example `:tooltip`. Note that the URL parameters listed in the [URL parameters for iframe tags](https://help.tableau.com/current/pro/desktop/en-us/embed_list.htm#URL_params) were used with previous versions of the embedding JavaScript API, and might not work or might not be supported in the future.

**Syntax for custom parameters:**

```

<tableau-viz id="tableauViz">
<custom-parameter name="parameter-name" value="parameter-value"></custom-parameter>
</tableau-viz>


```

**Example of setting custom parameters using a web component:**

The following example shows a Tableau web component that uses custom parameters to prevent tooltips from appearing in the view and to hide the Data Details button in the toolbar.

```
<tableau-viz
  id="tableauViz"
  src="https://public.tableau.com/views/Superstore_800_600/Overview">
  <viz-filter field="State/Province" value="California,Utah,Oregon,Washington">
  </viz-filter>
  <custom-parameter name=":tooltip" value="no"></custom-parameter>
  <custom-parameter name=":dataDetails" value="no"></custom-parameter> 
</tableau-viz>
```

### Apply custom parameters during initialization using JavaScript

If you are using JavaScript to initialize your embedding view, you can add custom parameters by creating a `custom-parameter` child node. You should add the custom parameter child node before you add the `src` URL. The following example shows the syntax you would use to create a custom parameter element that you can add to the `viz` object.

```

const customParameter = document.createElement("custom-parameter");
customParameter.setAttribute("name", "parameter-name");
customParameter.setAttribute("value", "parameter-value");
viz.appendChild(customParameter);


```

The following example sets a custom URL parameter that hides the Share button on the toolbar. This might be something you’d do if you wanted to keep users from using the links provided by the Share button. You add the custom parameters before assigning the `src` URL to the viz. Note that you must use the URL parameter name as listed in the [URL parameters for iframe tags](https://help.tableau.com/current/pro/desktop/en-us/embed_list.htm#URL_params). These names have a colon (`:`) prefix.

```

import {
  TableauViz
} from "https://public.tableau.com/javascripts/api/tableau.embedding.3.latest.js";
     
// create viz object
const viz = new TableauViz();

// add custom parameter
const customParameter = document.createElement("custom-parameter");
customParameter.setAttribute("name", ":showShareOptions");
customParameter.setAttribute("value", "false");
viz.appendChild(customParameter);
 
// set src URL
viz.src="https://public.tableau.com/views/Superstore_800_600/Overview";
    
// add viz to HTML page
document.getElementById("tableauViz").appendChild(viz);
    
```

  

#### On This Page