If youâre developing a React application, you can use the Tableau Embedding API React components to embed Tableau vizzes and Pulse metrics as components in your application. The Tableau Embedding API React components are available as a package on npm. This topic walks through installation and provides some tips about using the Tableau React package.
In this section
Be sure you have installed:
React environment. Set up a React project or use an existing React application.
If you want to jump right in and get started:
The Tableau Embedding API React Component is available from Node Package Manager (npm). The Tableau Embedding API React library includes the Embedding API v3 npm package (@tableau/embedding-api). The major and minor versions of both packages are kept in sync (although their patch versions might differ).
Always use a version of the library that is compatible with the version of Tableau that hosts the view or metric. See Versions of the Tableau Embedding API for reference.
To install the Tableau Embedding API React library in the node_modules folder of the current directory:
npm i @tableau/embedding-api-react
To install a specific version of the library, append @<version> to the command. For example, to install the 3.12.1 library, use the command:
npm i @tableau/embedding-api-react@3.12.1
You can verify the installation by checking files in the node_modules folder (there should be a @tableau folder that contains the embedding-api and embedding-api-react packages).
If a package.json file exists in the directory where you ran the npm command to install the package, and specifies the version of the library to use, the latest version of the library that satisfies the semantic versioning is installed. If no package.json exists, or no dependency for the library is specified, npm installs the latest version of the library.
The following entry in the package.json file specifies the 3.12.1 library. The tilde (~) in front of the version number indicates that updates to the latest patched minor versions of that library can be used (that is, 3.12.*). Be sure the version you use matches the version of the library used by the Tableau instance hosting the viz or metric. If you must lock it to a specific version or minor version, omit the tilde (~) or wildcard (*).
"dependencies": {
"@tableau/embedding-api-react": "~3.12.1"
}
In your JavaScript or TypeScript code, import the Api and TableauViz or TableauPulse objects, and any other classes and objects you need from the Embedding API v3 library. Be sure to include Api as itâs a re-export of the Tableau Embedding API from @tableau/embedding-api in its entirety.
To simplify your code and improve load times, import just the classes you need, for example TableauViz or TableauPulse to create the JavaScript object. If youâre planning on making your embedded viz interactive, by calling Embedding API methods or setting up event listeners, you might also need to import predefined refs from the @tableau/embedding-api-react library, such as useTableauVizRef or usePulseRef, so that you can reference the DOM without re-rendering. See Use React refs to reference Tableau web components.
If youâre planning to configure event listeners to provide custom actions based on events, import the hooks for events, such as useTableauVizFirstInteractiveCallback or useTableauPulseFirstInteractiveCallback to set an event listener. See Use the Tableau React hooks to add event listeners.
import { Api, TableauViz } from '@tableau/embedding-api-react';
If you import the library, which is an ES module, be sure to specify "type": "module" in your package.json file.
{
"name": "tableau-viz-demo",
"version": "0.1.0",
"private": true,
"type": "module",
"dependencies": {
"@tableau/embedding-api-react": "~3.12.1",
"etc. ....": "this example is not complete",
}
}
The Tableau React package provides the <TableauViz>, <TableauAuthoringViz>, and <TableauPulse> components that correspond to their respective Tableau web components in the Embedding API library (<tableau-viz>, <tableau-authoring-viz>, <tableau-pulse>). Like the web components, the React components support the same web component attributes. In React, these attributes are referred to as props.
For the list of props to use with the <TableauViz> and <TableauAuthoringViz> React components, see the HTML properties in the Table of properties and values for embedded objects and components.
For the list of props to use with the <TableauPulse> component, see the HTML properties in the table to Configure TableauPulse objects and components.
TableauViz example
Hereâs an example of a simple embedded viz using the TableauViz React component. The my-viz.tsx file exports a function component called MyViz(), which contains the TableauViz component. To embed the viz, include the exported function in your React application. Following the convention for naming for React function components, the export starts with an initial cap (MyViz). In this example, the TableauViz component has three props: the URL to the viz (src), a prop to hide the toolbar (toolbar="hidden"), and a prop to hide the tabs in the viz (hideTabs).
import { Api, TableauViz } from '@tableau/embedding-api-react';
export default function MyViz() {
return (
<TableauViz
src="https://public.tableau.com/views/RegionalSampleWorkbook/Storms"
toolbar="hidden"
hideTabs
/>
);
}
Hereâs an example of a default root component (App) that imports the component function (MyViz), which includes the <TableauViz> component.
import React from 'react';
import MyViz from './my-viz';
export default function App() {
return (
<div className="App">
<header className="App-header">
<h1>Tableau Visualization Demo</h1>
</header>
<main>
<MyViz />
</main>
</div>
);
}
The Tableau Embedding API React package provides refs for the Tableau embedded components (<TableauViz>, <TableauAuthoringViz>, <TableauPulse>). You can use these refs (or hooks) to access the components after the React DOM is initially rendered.
<TableauViz> useTableauVizRef <TableauAuthoringViz> useTableauAuthoringVizRef <TableauPulse> useTableauPulseRef Import the ref for the Tableau component
To use a ref for a <TableauViz> component, you first import the useTableauVizRef hook and then assign to a const in your export function. A similar process is used for the TableauAuthoringViz and TableauPulse components, where you use the refs, useTableauAuthoringVizRef or useTableauPulseRef, respectively.
import { Api, TableauViz, useTableauVizRef } from '@tableau/embedding-api-react';
export default function MyViz() {
const vizRef = useTableauVizRef();
/* .... */
}
You can then use vizRef to access the component in functions you create that interact with the viz.
const viz = vizRef.current;
/* use `viz` to access the TableauViz object */
/* for example,
/* const activeSheet = viz.workbook.activeSheet; */
In the Tableau viz component, assign vizRef to the ref attribute. Be sure to include the curly braces ({}) as it designates vizRef as a variable. When you add the ref attribute, code that references vizRef acts on the <TableauViz> object in the DOM.
A similar process is used for the TableauAuthoringViz and TableauPulse components, where you use the const created with useTableauAuthoringVizRef or useTableauPulseRef and assign that const to the ref attribute in the component.
/* .... */
return (
<TableauViz
ref={vizRef}
src="https://public.tableau.com/views/RegionalSampleWorkbook/Storms"
toolbar="bottom"
hideTabs
/>
);
/* .... */
useTableauVizRef
The following example shows how you might embed a Tableau viz in a simple React application. The example shows how you can use the hook to access the embedded viz after the viz has rendered.
The page has a button that, once clicked, accesses the viz and prints the name and type of viz. The example makes use of the useTableauVizRef hook to reference the DOM.
import React from 'react';
import { Api, TableauViz, useTableauVizRef } from '@tableau/embedding-api-react'
export default function MyViz() {
const vizRef = useTableauVizRef();
const getActiveSheetInfo = () => {
const viz = vizRef.current;
if (!viz) {
throw new Error("TableauViz ref not assigned yet.");
}
const activeSheet = viz.workbook.activeSheet;
const sheetName = activeSheet.name;
const sheetType = activeSheet.sheetType;
alert(`Active Sheet: ${sheetName}\nSheet Type: ${sheetType}`);
};
return (
<>
<div>
<p>
Click the <b>Get Sheet Info</b> button to get the name and type of the
active sheet.
</p>
<p>
<Button onClick={getActiveSheetInfo}>Get Sheet Info</Button>
</p>
</div>
<div style={{ display: "flex", gap: "10px" }}>
<TableauViz
ref={vizRef}
src="https://public.tableau.com/views/RegionalSampleWorkbook/Storms"
hide-tabs
toolbar="bottom"
/>
</div>
</>
);
}
Using the Tableau React package, you can add event listeners to embedded Tableau components in a React application. You can create event handlers to add interactivity with the embedded components using Tableau-specific React hooks and the web component attributes.
Add the web attribute for the eventThe React Tableau components support the same web attributes for events as their non-React counterparts do. For example, you can add an onFirstInteractive attribute to the <TableauViz>, <TableauAuthoringViz>, or <TableauPulse> component, and assign it to an inline or to a stand-alone function, which fires when the first interactive event occurs (that is, when the component has been rendered).
For the list of supported event web attributes, see TableauViz event hooks, TableauAuthoringViz event hooks, and Pulse event hooks.
When you specify the event attribute, be sure to use braces ({ }) around the name of the function youâve assigned to handle the event, so that the function is interpreted as a variable and not a string value. In this code snippet, the event handler myFirstInteractiveFunc() is assigned to the OnFirstInteractive attribute.
/* .... onFirstInteractive attribute */
return (
<TableauViz
src="https://public.tableau.com/views/RegionalSampleWorkbook/Storms"
onFirstInteractive={myFirstInteractiveFunc}
/>
);
/* .... */
The Tableau Embedding API React package provides hooks for the event listeners. You can use these hooks to access the Tableau components after the React DOM is initially rendered. For example, the hook for a Tableau viz first interactive event is useTableauVizFirstInteractiveCallback. If you arenât in-lining the event handler (defining the event handler in the web component), you must use these hooks to access the components when you define your event handler.
/* ... defining a first interactive event handler */
const myFirstInteractiveFunc = useTableauVizFirstInteractiveCallback((event) => {
const { target: viz } = event;
/* access the viz from the event payload */
}, []);
/* .... */
These hooks follow Reactâs custom hook naming convention (starting with âuseâ) and are designed to handle various events and interactions with Tableau visualizations. Each hook takes a callback function and a dependency array as parameters ([]), following the standard React pattern (based on the React useCallback hook). You assign these hooks to the corresponding event web attributes for the Tableau component.
For the list of supported event web attributes and their hooks, see TableauViz event hooks, TableauAuthoringViz event hooks, and Pulse event hooks.
Example using an event hookHereâs an example that uses one of the event hooks. In this case, the example uses the useTableauVizFirstInteractiveCallback hook and creates a callback function that fires when the viz loads and becomes interactive. The function extracts a reference to the viz from the event payload and uses that to get the name of the currently active sheet in the workbook.
In addition to the callback function, you must specify a dependency array. For the event hooks, specify an empty array ([]), so the same callback function instance is returned every time React renders the component. That is, only one event handler for that event is created and cached. React calls this memoization, where caching function code can lead to improved performance. If you omit the dependency array, a new callback function (event handler) is cached every time the component is rendered. For the Tableau event hooks, you donât need to specify any dependencies in the array, but you need to include the array in your event handler code ([]) for the callback.
In this example, the event handler is assigned to the onFirstInteractive attribute of the <TableauViz> web component. Be sure to import the event hooks you need from the Embedding API React package. Use a naming convention for your event handler that best suits your application. In this example, the event handler has the same name as the event web attribute (onFirstInteractive), which is one way to make your code more understandable.
import React from 'react';
import { Api, TableauViz,
useTableauVizFirstInteractiveCallback } from '@tableau/embedding-api-react';
export default function MyViz() {
const onFirstInteractive = useTableauVizFirstInteractiveCallback((event) => {
const { target: viz } = event;
console.log('---onFirstInteractive---');
console.log('Viz Embedding Successful!');
console.log(`Name of active sheet: ${viz.workbook.activeSheet.name}`);
}, []);
return (
<TableauViz
src="https://public.tableau.com/views/RegionalSampleWorkbook/Storms"
toolbar="hidden"
onFirstInteractive={onFirstInteractive}
/>
);
}
Another approach for adding an event listener is to define the event handler inline as part of the web component. In this case, you donât need to import the event hook (useTableauVizFirstInteractiveCallback). Placing the event handler inline makes sense if you have a simple use case. In most instances, and for improved readability, use the event hooks and create separate event handlers.
export default function MyComponent() {
return (
<TableauViz
src="https://public.tableau.com/views/RegionalSampleWorkbook/Storms"
toolbar="hidden"
onFirstInteractive={ (event) => {
const { target: viz } = event;
console.log('---onFirstInteractive---');
console.log('Viz Embedding Successful!');
console.log(`Name of active sheet: ${viz.workbook.activeSheet.name}`);
}}
/>
);
}
The table shows the React hook to import and the web attribute to associate your event handler function. For a complete list of events, see Supported Events for the list of web attributes that map to TableauViz and TableauAuthoringViz components.
useTableauVizCustomMarkContextMenuCallback onCustomMarkContextMenuEvent Handles custom mark context menus useTableauVizCustomViewCallback onCustomViewLoaded, onCustomViewRemoved, onCustomViewSaved, onCustomViewSetDefault Handles custom view events useTableauVizFirstInteractiveCallback onFirstInteractive Handles when visualization becomes interactive useTableauVizFirstVizSizeKnownCallback onFirstVizSizeKnown Handles when visualization size is first known useTableauVizFilterChangedCallback onFilterChanged Handles filter changes in visualization useTableauVizMarksSelectedCallback onMarkSelectionChanged Handles mark selection events useTableauVizParameterChangedCallback onParameterChanged Handles parameter changes useTableauVizTabSwitchedCallback onTabSwitched Handles tab switching events useTableauVizToolbarStateChangedCallback onToolbarStateChanged Handles toolbar state changes useTableauVizUrlActionCallback onUrlAction Handles URL action events useTableauSummaryDataChangedCallback onSummaryDataChanged Handles changes in summary data useTableauVizEditButtonClickedCallback onEditButtonClicked Handles edit button clicks useTableauVizEditInDesktopButtonClickedCallback onEditInDesktopButtonClicked Handles âEdit in Desktopâ button clicks Tableau authoring event hooks Hook Web attribute Purpose useTableauAuthoringVizEditButtonClickedCallback onEditButtonClicked Handles edit button clicks useTableauAuthoringVizEditInDesktopButtonClickedCallback onEditInDesktopButtonClicked Handles âEdit in Desktopâ button clicks useTableauAuthoringVizFirstInteractiveCallback onFirstInteractive Handles first interactive state in authoring mode useTableauAuthoringVizWorkbookPublishedCallback onWorkbookPublished Handles workbook publication events useTableauAuthoringVizWorkbookReadyToCloseCallback onWorkbookReadyToClose Handles workbook ready-to-close state Pulse event hooks
For the list of web attributes that map to TableauPulse components, see Supported Events
useTableauPulseErrorCallback onPulseError Handles Pulse-related errors useTableauPulseFiltersChangedCallback onPulseFiltersChanged Handles filter changes in Pulse useTableauPulseFirstInteractiveCallback onFirstInteractive Handles first interactive state in Pulse useTableauPulseFirstMetricSizeKnownCallback onFirstPulseMetricSizeKnown Handles when the Pulse metric size is known useTableauPulseInsightDiscoveredCallback onPulseInsightDiscovered Handles discovery of insights useTableauPulseTimeDimensionChangedCallback onPulseTimeDimensionChanged Handles time dimension changes useTableauPulseUrlChangedCallback onPulseUrlChanged Handles URL changes Whatâs Next
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4