---
schema_version: "1"
id: 0af30563c7b52458eece30c350a38d77f809abc7b15e1bd026371e38c2b46d21
title: Embed Custom Views
collection: tableau
version: current
locale: en-us
portal_url: https://docs.salesforce.com/tableau/current/en-us/api/embedding_api/docs/embedding_api_custom_views.md
canonical_url: https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_custom_views.html
source_site: help.tableau.com
content_type: documentation
content_hash: 745d72d675cb9b9571c20611aa4910f182784aaf920558a1b5b5d52c39929c45
description: Documentation for the Tableau Embedding API
---
# Embed Custom Views

  

The easiest way to embed a custom view of a dashboard or worksheet in a web application is by specifying the custom view in the source URL. You can use the custom view URL in the `src` attribute of the `<tableau-viz>` web component or in the `TableauViz` JavaScript object. You can also use the methods and properties in the Embedding API v3 to programmatically get, show, and save custom views, or to set a custom view as the default.

The `src` URL follows the Tableau pattern:

- If the URL specifically refers to a custom view, that view is displayed.
- If the URL does not refer to a custom view, the default custom view is displayed.
- If no default custom view has been defined, the original view is displayed.

This topic describes how you can use the Embedding API v3 methods to get, create, and manage custom views if you want to do more than use the `src` URL to embed a custom view.

* * *

## Get all the custom views in a workbook

You can get the names of all the custom views in a workbook by calling the `getCustomViewsAsync` method. This method returns the collection of `CustomView` objects associated with the workbook. The following code example shows how you might log the names of the custom views and how you can use the properties of the view to check to see if it was set as the default view.

```
const customViews =  await viz.workbook.getCustomViewsAsync();

customViews.forEach((view) => {
    console.log (`   '${view.name}' ${view.default ? '(default)' : ''}`);
    });
```

## Get the currently active custom view

You can find out if there is a currently active view by checking the workbook property `activeCustomView`. The following example shows how you can get the name of the view from the property, if there is an active custom view.

```

const active = viz.workbook.activeCustomView;
if (active) {
  console.log ("Name of the active custom view: "  + active.name);
} else {
  console.log ("No active custom view.");
}

```

## Show a custom view

You can programmatically set the embedded view to a specific custom view using the `Workbook.showCustomViewAsync()` method.  
The method takes one argument, the name of the custom view (`customViewName`). The method sets the view as the active custom view.

```
await viz.workbook.showCustomViewAsync("West");
 // do something 
```

If you want to reset the active custom view to the original view, pass in a null value for the `customViewName` parameter.

```
await workbook.showCustomViewAsync();
 // do something });
```

## Save a custom view

You can modify a view by setting filters, parameters, and then save that state as a new custom view. After you modify the state of the view, use the `Workbook.saveCustomViewAsync()` method to save a new custom view. For example, the follow code snippet applies a filter to the view and then saves that view as a custom view.

```
async function someFunction() {
   await viz.workbook.activeSheet.applyFilterAsync("Region", ["South"], "replace");
   await viz.workbook.saveCustomViewAsync("South Only");
};
```

You can also save the active custom view by calling the `saveAsync()` method on the `CustomView` object that is returned by the workbook `activeCustomView` property.

```
async function someFunction()  {
    const active = viz.workbook.activeCustomView;
    // make some changes to the active custom view
    await active.saveAsync();
    console.log(`Saved the active custom view: '${active.name}' again` )
};
```

## Set the custom view as the default view

You can use the `setActiveCustomViewAsDefaultAsync()` method to make the active custom view the default view. If there is no active custom view, the default view is the original view.

```
async function someFunction()  {
    const active = viz.workbook.activeCustomView;
    await viz.workbook.setActiveCustomViewAsDefaultAsync();
    console.log(`Set active custom view: '${active.name}' as the default`);
};
```

## Remove a custom view

You can remove a custom view by calling the workbook `removeCustomViewAsync` method.

```
async function someFunction() {
    await viz.workbook.removeCustomViewAsync("SomeCustomView");
    console.log("Removed custom view: 'SomeCustomView'");
};
```

## Custom view events

If you want to take action whenever a custom view change occurs, you can add event listeners to detect when a custom view has been loaded (`CustomViewLoaded`), removed (`CustomViewRemoved`), saved (`CustomViewSaved`), or set as the default (`CustomViewSetDefault`). You can use this information about custom views to update your web application. For information about using event listeners, see [Add Event Listeners](/current/api/embedding_api/en-us/docs/embedding_api_event.html).

  

#### On This Page