Interacting with the viz: filters, parameters, and events

One of the main advantages of the Tableau Embed API is the ability to control the viz from your page. You can apply filters, modify dashboard parameters, and listen to user actions to drive a cohesive experience.

Applying filters programmatically

After the viz has loaded, you can access the workbook and apply filters to specific fields. This is useful when you have UI controls that filter data across multiple components on the page.

// Example: apply a filter to a worksheet or dashboard
viz.getWorkbook().then(function (workbook) {
  var activeSheet = workbook.getActiveSheet();
  // If the active sheet is a worksheet, apply the filter directly
  if (activeSheet.getSheetType && activeSheet.getSheetType() === tableau.SheetType.Worksheet) {
    activeSheet.applyFilterAsync("Category", "Furniture", tableau.FilterUpdateType.REPLACE);
  }
});

Working with parameters (where supported)

Parameters allow you to customize a viz without changing the underlying workbook. You can set a parameter value through code to tailor visuals to the user’s context.

viz.getWorkbook().then(function (workbook) {
  var activeSheet = workbook.getActiveSheet();
  // If the sheet supports parameters, set a parameter value
  activeSheet.setParameterAsync("DateRange", "Last 30 Days");
});

Listening to events

Event handling helps keep your page synchronized with the viz. For example, you can respond when the viz finishes loading or when a filter is changed by the user.

viz.addEventListener(tableau.TableauEventName.MARKS_SELECTION, function (event) {
  return event.getMarksAsync().then(function (marks) {
    // Process selected marks or update UI accordingly
    console.log("Marks selected:", marks.length);
  });
});

Design and responsiveness: making the embed fit your layout

Modern web design often demands fluid layouts. The Tableau Embed API supports responsive height and width so your viz scales with the browser. A common pattern is to place the viz inside a flexible container and listen for resize events to adjust the container height dynamically. If you hide the Tableau chrome (tabs or toolbar), be sure your page still provides a clear navigation path for users to explore the data.

Practical tips for responsive embeds

• Set the container to width: 100% and manage height with CSS or JavaScript to fit the viewport.
• Use the onFirstInteractive callback to recalculate layout after the viz renders.
• Consider a dedicated API approach for mobile devices to avoid oversized toolbars and controls.

Security considerations and best practices

The Tableau Embed API respects the same security model as other Tableau integrations. When embedding content, pay attention to authentication, permissions, and data permissions. If you’re embedding sensitive data, use trusted authentication or other secure methods provided by Tableau Server or Tableau Online. Always follow your organization’s security policies and avoid exposing sensitive credentials in client-side code. The Tableau Embed API itself does not bypass server-side access controls; it renders what the current user is allowed to see.

Common use cases and advanced scenarios

• Bringing a live dashboard into a product page to augment decision-making with real data insights.
• Creating a dashboard gallery where each card loads a different viz using the Tableau Embed API, with a shared set of controls to filter across all cards.
• Building a guided analytics workflow that updates parameters or filters based on user input elsewhere in the UI.
• Embedding multiple vizs on a single page and coordinating filters so a change in one viz reflects across others.

Performance and reliability considerations

Performance hinges on the network, the size of the viz, and how aggressively you update filters or parameters. Some best practices include lazy loading less critical vizs, debouncing rapid filter changes, and loading assets asynchronously. If you expect high concurrent usage, consider server-side caching strategies and CDN delivery for static resources. The Tableau Embed API is designed to be efficient, but thoughtful orchestration on the client side can reduce unnecessary re-renders and improve perceived performance.

Bringing it all together: a practical workflow

To deploy a robust Tableau Embed API integration, follow this pragmatic workflow:

1. Publish a workbook or dashboard on Tableau Server or Tableau Online with the appropriate permissions for your audience.
2. Choose a URL that points to the specific view you want to embed and plan how filters and parameters will be exposed to the page.
3. Include the Tableau JavaScript API on your page and create a Viz instance in a well-defined container.
4. Implement UI controls that drive the viz via programmatic filters and parameters, ensuring the controls reflect the current state of the visualization.
5. Attach event listeners to respond to user actions and to coordinate with other UI elements on your page.
6. Test across devices, monitor performance, and adjust sizing behavior to maintain a clean, accessible experience.

Conclusion

The Tableau Embed API unlocks powerful opportunities to weave data visuals into your web experiences. By embedding Vizs with thoughtful controls, you can deliver interactive analytics that feel native to your site, without compromising security or performance. As you design solutions around the Tableau Embed API, keep the user at the center: simple controls, responsive layouts, and clear data storytelling. With a clear plan and careful implementation, Tableau Embed API can be a cornerstone of your data-enabled web strategy.