Integrate Custom LWC in Dashboards with the Extensions SDK

Use custom Lightning Web Components (LWC) to facilitate complex tasks in your Tableau Next dashboards. The Dashboard Extensions SDK allows your custom components to interact directly with the data in your dashboards. Because these extensions inherit global dashboard styling and respond to filter updates, they provide a cohesive and native user experience.

This guide covers implementing and integrating custom LWCs into Tableau Next dashboards using the Component Widget framework.

Install VS Code and configure it for Salesforce development. Use these Trailhead modules for installation and configuration:
- Quick Start: Visual Studio Code for Salesforce Development
- Quick Start: Lightning Web Components - Set Up Visual Studio Code
Install the Salesforce CLI - Install Salesforce CLI

To build a custom LWC, follow the steps in Create a Hello World Lightning Web Component.

To make your custom LWC visible in the Tableau Next dashboard extension picker, your LWC must include the analytics__Dashboard target in the component metadata file.

Set the LWC display name and description for display in the extension picker.

Deploy your custom LWC into your org. Use the VS Code palette commands SFDX: Authorize an Org and SFDX: Deploy This Source to Org.

When your custom LWC is deploy to your org, you can add the component to your Tableau Next dashboard.

In Tableau Next, open your dashboard for editing.
Click the Extension icon and select an area of the dashboard.
Click Add Extension.
Select your custom component and click Select.
Set any properties for the component or to replace the existing component with another component on the widget panel.
Set the widget style on the design panel.

Pass dashboard filters, parameters, and state to your custom LWC using the Dashboard Extension SDK. This allows your LWC to interact with the data in your dashboard.

The Dashboard Extension SDK is the integration layer and secure boundary between the Tableau Next dashboard runtime and custom LWC. Extensions receive the SDK via DashboardWidgetComponentProps and use it to read dashboard context, subscribe to runtime events, and publish filters or parameters.

The SDK automatically added to the dashboard for each extension widget. In your component, the SDK is available as the sdk property passed with your widget properties. The constructor registers with the runtime so that when filters or parameters are applied elsewhere on the dashboard, the SDK emits FILTER_CHANGE and PARAMETER_CHANGE to your subscribers.

Retrieve the current dashboard context.

This method optionally takes the parameters:

currentPage - (string) the name of the current dashboard page
currentLayout - (string) the name of the current dashboard layout
dashboardState.filters - (array) a list of the current semantic filters
dashboardState.parameters - (array) a list of the current parameters

Use SDK_EVENTS to subscribe to dashboard runtime events.

Event	Constant	Event Fired When:
Filter change	`SDK_EVENTS.FILTER_CHANGE`	Dashboard filters change
Parameter change	`SDK_EVENTS.PARAMETER_CHANGE`	Dashboard parameters change

on(eventName, handler) subscribes to an event. Returns a unsubscribe function.

off(eventName, handler) removes an event subscription.

FILTER_CHANGE and PARAMETER_CHANGE are fired internally when the runtime invokes the callbacks the SDK registered with the constructor, setApplyFilter and setApplyParameter.

Extension actions are available in sdk.actions.

applyFilter()

Publish a filter to the dashboard. sdk.actions.applyFilter(filter)

filter is an object with:

fieldOrFields - string[] for a single field or string[][] for multiple fields
values - string[] for a single value or string[][] for multiple values; for values for multiple fields, use an array of value tuples
operator - string filter operator; defaults to In
dataSourceName - string the optional data source name; defaults to the value from registerDataSource

applyParameter()

Publish a parameter for the dashboard to use in a query. sdk.actions.applyParameter(parameter)

parameter is an object with:

name - string the parameter name
value - string the parameter value
datasourceName - string the optional data source name; Use dataSourceName or a registered data source.

notifyLifecycleChange()

Notifies when the lifecycle state of the component changes. sdk.actions.notifyLifecycleChange(eventName, details?)

eventName - string event name, valid values are:

LIFE_CYCLE_EVENTS.INIT - component initializing
LIFE_CYCLE_EVENTS.LOADED - component loaded successfully
LIFE_CYCLE_EVENTS.ERROR - component is in an error state
LIFE_CYCLE_EVENTS.NODATA - no data for the component

details - is an object with:

message - string the optional event message
error - string the optional error message

This example shows how to use the Dashboard Extensions SDK in your component JavaScript.