--- schema_version: "1" id: 086522087a47b5c0e66dc5cb9f89835d0c3c8fcbaef51a180665611b92427635 title: Using Tableau Embedding API React Components collection: tableau version: current locale: en-us portal_url: https://docs.salesforce.com/tableau/current/en-us/api/embedding_api/docs/embedding_api_react.md canonical_url: https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_react.html source_site: help.tableau.com content_type: documentation content_hash: bf988c8841d595e20ff92563004d7e0de61b386b2c343b9aef88acfc26350829 description: Documentation for the Tableau Embedding API --- # Using Tableau Embedding API React Components 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. * * * ## Prerequisites Be sure you have installed: - [Node.js and npm](https://nodejs.org/en/) - [React](https://react.dev/) environment. Set up a React project or use an existing React application. * * * ## Quick links If you want to jump right in and get started: - [Install the Tableau React npm package](#install-the-tableau-react-npm-package). - See the [React samples on GitHub](https://github.com/tableau/embedding-api-v3-samples/tree/main/react-samples) for examples that use the Tableau React components. * * * ## Install the Tableau React npm package The [Tableau Embedding API React Component](https://www.npmjs.com/package/@tableau/embedding-api-react) 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](/current/api/embedding_api/en-us/docs/embedding_api_get.html#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 `@` 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" } ``` * * * ### Import the React npm package 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](#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](#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", } } ``` * * * ## Set up the Tableau React component with props The Tableau React package provides the ``, ``, and `` components that correspond to their respective Tableau web components in the Embedding API library (``, ``, ``). 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 `` and `` React components, see the HTML properties in the [Table of properties and values for embedded objects and components](/current/api/embedding_api/en-us/docs/embedding_api_configure.html#table-of-properties-and-values-for-embedded-objects-and-components). - For the list of props to use with the `` component, see the HTML properties in the table to [Configure TableauPulse objects and components](/current/api/embedding_api/en-us/docs/embedding_api_pulse.html#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 ( ); } ``` Here’s an example of a default root component (`App`) that imports the component function (`MyViz`), which includes the `` component. ``` import React from 'react'; import MyViz from './my-viz'; export default function App() { return (

Tableau Visualization Demo

); } ``` ## Use React refs to reference Tableau web components The Tableau Embedding API React package provides refs for the Tableau embedded components (``, ``, ``). You can use these refs (or _hooks_) to access the components after the React DOM is initially rendered. | Tableau Component | Hook | | --- | --- | | `` | `useTableauVizRef` | | `` | `useTableauAuthoringVizRef` | | `` | `useTableauPulseRef` | * * * ### Import the ref for the Tableau component To use a ref for a `` 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; */ ``` ### Assign the ref attribute in the Tableau component 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 `` 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 ( ); /* .... */ ``` ### Example using `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 ( <>

Click the Get Sheet Info button to get the name and type of the active sheet.

); } ``` * * * ## Use the Tableau React hooks to add event listeners 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 event The 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 ``, ``, or `` 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](#tableau-viz-event-hooks), [TableauAuthoringViz event hooks](#tableau-authoring-event-hooks), and [Pulse event hooks](#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 ( ); /* .... */ ``` ### Use the event hook in your event handler 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](#tableau-viz-event-hooks), [TableauAuthoringViz event hooks](#tableau-authoring-event-hooks), and [Pulse event hooks](#pulse-event-hooks). ### Example using an event hook Here’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 `` 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 ( ); } ``` * * * ### Example using an inline event handler 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 ( { const { target: viz } = event; console.log('---onFirstInteractive---'); console.log('Viz Embedding Successful!'); console.log(`Name of active sheet: ${viz.workbook.activeSheet.name}`); }} /> ); } ``` * * * ### Tableau viz event hooks 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](/current/api/embedding_api/en-us/docs/embedding_api_event.html#supported-events) for the list of web attributes that map to `TableauViz` and `TableauAuthoringViz` components. | Hook | Web attribute | Purpose | | --- | --- | --- | | `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](/current/api/embedding_api/en-us/docs/embedding_api_pulse_events.html#supported-tableau-pulse-events) | Hook | Web attribute | Purpose | | --- | --- | --- | | `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 - To see more examples and to find out what’s possible with Tableau and React, see the Tableau Embedding API v3 [React samples on GitHub](https://github.com/tableau/embedding-api-v3-samples/tree/main/react-samples). #### On This Page