> ## Documentation Index
> Fetch the complete documentation index at: https://docs.curator.interworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Parameters in Tableau Embedding API v3

> Understand why URL parameters appended to the Tableau Server Dashboard URL do not work in v3, and how Curator handles custom parameters via client-side rendering.

## Overview

When using **Tableau Embedding API v3**, URL parameters appended directly to the **Tableau Server Dashboard URL**
(e.g., `?:render=True`) are **not supported**. This is a known change from the v2 embedding approach and affects
any parameter that was previously passed by appending it to the Tableau Server URL.

If you are seeing unexpected behavior — such as images not rendering or toolbar options being ignored — after
upgrading to Tableau Embedding API v3, this page explains why and how to fix it.

<Warning>
  Do not append custom parameters (e.g., `:render`, `:refresh`, `:linktarget`) directly to the **Tableau Server
  Dashboard URL** field in Curator when using Embedding API v3. These parameters will be silently ignored.
</Warning>

***

## Why URL parameters don't work in v3

In the v2 embedding approach, Tableau dashboards were embedded using a plain `<div>` element and a JavaScript
initializer. URL query parameters could be appended directly to the Tableau Server Dashboard URL to control
rendering behavior.

In v3, Tableau dashboards are embedded using the `<tableau-viz>` web component. The web component does not
read or forward query parameters from the `src` URL in the same way. Instead, configuration options must be
provided as **child `<custom-parameter>` elements** nested inside the `<tableau-viz>` component.

From the
[Tableau Embedding API documentation](https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_parameters.html#apply-custom-parameters-during-customization-using-web-components),
the correct way to pass custom parameters in v3 is:

```html theme={null}
<tableau-viz src="https://your-tableau-server/views/YourDashboard/Sheet">
    <custom-parameter name=":render" value="true"></custom-parameter>
</tableau-viz>
```

***

## How Curator handles this

Curator automatically generates the appropriate `<custom-parameter>` elements when a dashboard is embedded using
Embedding API v3. This is controlled by the dashboard's **Embedded Options** settings in the Curator backend.

The following parameters are handled automatically by Curator:

| Parameter        | Controlled by                                                      |
| ---------------- | ------------------------------------------------------------------ |
| `:render`        | **Render Client-Side** setting in the Advanced tab                 |
| `:refresh`       | **Refresh Data** setting in the Advanced tab                       |
| `:linktarget`    | **Link Target** setting in the Advanced tab                        |
| `:subscriptions` | **Show Toolbar** + **Hide Subscribe** settings in the Advanced tab |
| `:alerts`        | **Show Toolbar** + **Hide Alerts** settings in the Advanced tab    |

When Curator renders a v3 embed, it translates the dashboard's saved settings into `<custom-parameter>` child
elements inside the `<tableau-viz>` component. You do **not** need to manually add parameters to the Tableau
Server Dashboard URL.

***

## Fixing broken parameters: verify client-side rendering is enabled

The most common case where this issue surfaces is with the `:render=True` parameter, which forces Tableau to use
client-side (browser) rendering instead of server-side (image) rendering. If you had appended `?:render=True`
to the Tableau Server Dashboard URL in the Curator backend, it will be ignored in v3.

In Curator, **Render Client-Side** is enabled by default, so most dashboards will already produce the correct
`<custom-parameter>` output without any changes. However, if you have previously set this to a different value
or are seeing unexpected rendering behavior, verify the setting:

1. Navigate to the Curator backend > **Tableau** > **Dashboards**.
2. Select the Dashboard you want to configure.
3. Switch to the **Advanced** tab and open the **Embedded Options** section.
4. Verify that the **Render Client-Side** toggle is enabled.
5. Save the Dashboard if you made any changes.

Curator will then render the correct `<custom-parameter name=":render" value="true">` element inside the
`<tableau-viz>` web component automatically.

***

## Curator URL parameters vs. Tableau Server Dashboard URL parameters

It is important to distinguish between two different types of URL parameters:

**Curator URL query parameters** (e.g., `https://your-curator.com/dashboard?Region=West`) are still fully
supported in v3. Curator picks these up and converts them to filter and parameter values applied via the
Tableau JavaScript API. See [Preloading Filters and Parameters](/embedding_using_analytics/filters_parameters/preloading_filters_and_parameters#preload-behavior)
for details.

**Tableau Server Dashboard URL parameters** (e.g., appending `?:render=True` to the URL in the **Tableau Server
Dashboard URL** field in the Curator backend edit page) are **not supported in v3**. These must be replaced with
the equivalent Curator embedding option settings as described above.

| Parameter type                                        | v3 supported? | How to use it                            |
| ----------------------------------------------------- | ------------- | ---------------------------------------- |
| Curator URL query params (`?Region=West`)             | Yes           | Passed as filters/parameters via the API |
| Tableau Server Dashboard URL params (`?:render=True`) | No            | Use Curator's Embedded Options instead   |

***

## Additional resources

* [Tableau Embedding API v3: Custom Parameters](https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_parameters.html#apply-custom-parameters-during-customization-using-web-components)
* [Tableau Server: Browser Rendering](https://help.tableau.com/current/server/en-us/browser_rendering.htm)
* [Curator: Dashboard Settings](/embedding_using_analytics/tableau_dashboards/dashboard_settings)
* [Curator: Preloading Filters and Parameters](/embedding_using_analytics/filters_parameters/preloading_filters_and_parameters)