Filter the View


You can apply filters to display a subset of the data available for a view. You can either apply filters before a visualization has been loaded (at initialization) or after (interactively).

In this section

Filtering during initialization using web components

You can apply filters on the viz by adding <viz-filter> elements to your <tableau-viz> web component. This is only supported in <tableau-viz> web components. You can’t apply filters to <tableau-authoring-viz> components.

The <viz-filter> element has two attributes: the field and its value.

<viz-filter field="name" value="value"> </viz-filter>

The filter can contain multiple values, and you can add multiple <viz-filter> elements to the <tableau-viz> component. Note that when a filter contains multiple values, the values should be comma-delimited (,) without spaces. When you specify fields in a filter, you should use the caption as shown in the Tableau viz (user interface), not the database field name. The field names are case-sensitive. In some cases, Tableau Desktop renames fields after they’ve been dragged to a shelf. For example the Date field might be renamed to YEAR(Date) after being dragged to the rows shelf. In this case, you should use YEAR(Date) as the name of the field. The exception is hierarchical filters, which use the full hierarchical name (for example, [Product].[All Product].[Espresso]). Captions can use the optional [] delimiters around names.

Here’s example code that adds two filters to a <tableau-viz> web component.


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


<tableau-viz id="tableauViz"       
  src='https://public.tableau.com/views/Superstore_24/Overview'      
  toolbar="bottom" hide-tabs>
  <viz-filter field="Category" value="Technology"> </viz-filter>    
  <viz-filter field="State" value="California,Oregon,Washington"> </viz-filter>
</tableau-viz>

To see what it looks like when you embed this code in a page, see Example of filtering.

Filtering during initialization using JavaScript

If you prefer to use JavaScript to embed your views, you can still apply filters during initialization by using the addFilter() method. To do this you add the filters on the TableauViz object before you render the view. For example, the following snippet applies two filters (Central, West) to the view and then renders the view by appending it to the HTML element that has the identifier, tableauViz .


let url = 'https://public.tableau.com/views/Superstore_24/Overview';

// create the viz object

const viz = new TableauViz();

viz.src = url;

// configure the viz...
// apply filters

viz.addFilter('Region', 'Central,West'); 

// render the view by appending it to "tableauViz"
document.getElementById('tableauViz').appendChild(viz);

To apply filters after you have initialized and rendered the view, use the applyFilterAsync or applyRangeFilterAsync methods, see Apply filters interactively (after initialization). If you use the addFilter() method after initialization, the view is re-rendered.

As an alternative to using the applyFilter() method, you could create a filter element and append that to the TableauViz object directly before initialization. For example, the following snippet shows how you might apply a filter on the Region field so that it only shows the West.


// assumes a viz object has been created

const filter = document.createElement("viz-filter");
filter.setAttribute("field", "Region");
filter.setAttribute("value", "West");
viz.appendChild(filter);

// render the view by appending it to "tableauViz"
document.getElementById('tableauViz').appendChild(viz);

Apply filters interactively (after initialization)

You can use the applyFilterAsync() and applyRangeFilterAsync functions to apply filters after your visualization has loaded. To do this, you first need to create a JavaScript object from the web component <tableau-viz>. After you have the viz object, you can use the Embedding API methods to interact with the view.

Apply categorical filters

Use the applyFilterAsync() method to filter the view based on a list of categorical filter values. For example, the following code shows how you might filter a single value. In this case, the field is State and the value is Washington. Note that the applyFilterAsync method requires an array of values, so you must include the brackets ([ ]) even if you are filtering on a single value.

When you call the applyFilterAsync() method, you also need to specify what action you want to take. You can either add a new filter, replace, or remove existing filters, or apply all filters. To specify the action, use the FilterUpdateType enumerations (FilterUpdateType.Replace, FilterUpdateType.Add, FilterUpdateType.Remove, FilterUpdateType.All ).

Note if you are embedding a view from Tableau 2021.4, you need to use the string literal values ("replace", "add", "all", "remove"), instead of the FilterUpdateType enumerations (for example, FilterUpdateType.Replace).


// assumes a <tableau-viz> was created with the id='tableauViz'

let viz = document.getElementById('tableauViz');
let sheet = viz.workbook.activeSheet;
const saleMap = sheet.worksheets.find(ws => ws.name =="SaleMap");
saleMap.applyFilterAsync("State", ["Washington"], FilterUpdateType.Replace);

To filter using multiple values, separate the filter values with commas (,).

 
saleMap.applyFilterAsync("State", ["Washington","Oregon"], FilterUpdateType.Replace);

To add additional filters, use the action FilterUpdateType.Add.

 
saleMap.applyFilterAsync("State", ["Ohio"], FilterUpdateType.Add);

To remove filters, use the action FilterUpdateType.Remove.

... 
saleMap.applyFilterAsync("State", ["Oregon"], FilterUpdateType.Remove);

Apply range filters

You can filter on ranges using the applyRangeFilterAsync method. For example, to set a range on a date field, use the RangeFilterOptions properties, min and max to set the range. Note that the dates must be in UTC format.


    saleMap.applyRangeFilterAsync("Order Date", {
         min: new Date(Date.UTC(2018, 3, 1)),
         max: new Date(Date.UTC(2020, 08, 30))
    });

Filtering Example

The following example shows what it looks like when you filter the view during initialization, using the web component. The buttons show what happens when you apply filters interactively after the initial load. This example adds two filters to a <tableau-viz> web component when the embedded viz if first loaded.


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


<tableau-viz id="tableauViz"       
  src='https://https://public.tableau.com/views/Superstore_embedded_800x800/Overview'      
  toolbar="bottom" hide-tabs>
  <viz-filter field="Category" value="Technology"> </viz-filter>    
  <viz-filter field="State" value="California,Oregon,Washington"> </viz-filter>
</tableau-viz>

The Oregon and Washington Only button, runs the following code when the button is clicked:


function filterState() {
    let viz = document.getElementById("tableauViz");
    console.log( viz);
    let sheet = viz.workbook.activeSheet;;
    const saleMap = sheet.worksheets.find((ws) => ws.name == "SaleMap");
    saleMap.applyFilterAsync("State", ["Washington", "Oregon"], FilterUpdateType.Replace);
};

The Clear Filter button, calls the clearFilterAsync() method:


function clearState() {
    let viz = document.getElementById("tableauViz");
    console.log( viz);
    let sheet = viz.workbook.activeSheet;
    const saleMap = sheet.worksheets.find((ws) => ws.name == "SaleMap");
    saleMap.clearFilterAsync("State");

The Undo button calls the undoAsync() method on the viz object and reverts the previous action.


function unDo() {
    let viz = document.getElementById("tableauViz");
    viz.undoAsync();
};