# GoodData.UI Documentation (full text)
> GoodData.UI: A React SDK, Web Components, and REST API clients for building analytics into your application.
Every guide page of the documentation, in sidebar order, as Markdown. The index of all pages, including the API reference (one Markdown page per package and per symbol), is https://www.gooddata.ai/docs/gooddata-ui/llms.txt.
---
# Getting started
> GoodData.UI is the official React SDK for embedding GoodData analytics, from single charts and filters to whole dashboards and the AI assistant, directly into your application.
Source: https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/index.md
GoodData.UI talks to [GoodData Cloud and GoodData.CN](https://www.gooddata.ai/) over the analytical backend API and ships as a set of npm packages under the `@gooddata/*` scope. The SDK is written for React. If your app is Angular, Vue, or plain HTML, the same components are available as [Web Components](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/index.md).
If you only need a saved dashboard inside an existing page and don't want to install any SDK code, you can [embed a dashboard in an iframe](https://www.gooddata.ai/docs/cloud/embed-visualizations/iframes/). That works in any framework with no code at all. You can hide parts of the dashboard through URL query parameters (the filter bar, for example) and talk to it from the host page over [`postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage). Reach for the React SDK or Web Components when you need more than that: your own layout, control over single widgets, state shared between components, or raw data in your own UI.
## [See a chart in five minutes](https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/#see-a-chart-in-five-minutes)
One command scaffolds a React app that already talks to a public demo workspace. The dev server proxies the API, so you don't set up CORS or sign in to anything:
```bash
npx @gooddata/app-toolkit@latest init my-analytics-app
```
The [Quick start](https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/quickstart/index.md) explains what the command creates and how to swap the sample chart for a dashboard, or for a chart you define in code. It ends with the app pointed at your own workspace.
To add GoodData.UI to a React codebase you already have instead, see [Add GoodData.UI to an existing React app](https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/installation/index.md).
Before you start, check your toolchain. [Platform compatibility](https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/platform-compatibility/index.md) lists the Node.js, React, TypeScript, and bundler versions you need, and which SDK major works with which GoodData platform.
## [Core concepts](https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/#core-concepts)
A GoodData.UI application is built from a small set of primitives. You rarely need all of them at once, so pick what fits the screen you are building.
**Backend and workspace context.** Every app is wrapped in a [`BackendProvider`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.backendprovider/index.md) and [`WorkspaceProvider`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.workspaceprovider/index.md). The backend object knows how to authenticate and talk to your GoodData instance. The workspace identifies which workspace's data you are rendering. Everything downstream, whether a chart, a filter, a dashboard, or a raw execution, reads both through React context, so you configure them once at the root. Configure them as described in [Integrations](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/index.md).
**Visualizations.** A broad chart library: bar, column, line, area, pie, scatter, heatmap, funnel, waterfall, bullet, treemap, sankey, geo, and more, plus a pivot table and a repeater for tabular output. You can build charts in code by passing `measures`, `viewBy`, and `stackBy` props, or render any saved visualization by identifier with the universal [`InsightView`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-ext/sdk-ui-ext.insightview/index.md) component. Every chart shares one chart-config object for colors, legends, axes, and labels. See [Visualizations](https://www.gooddata.ai/docs/gooddata-ui/latest/visualisations/index.md).
**Dashboards and plugins.** A full GoodData dashboard, with its layout, filters, widgets, and cross-filtering, drops into your app as a single [`Dashboard`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.dashboard/index.md) component. For deeper integration, a plugin system lets you register custom widgets, replace built-in rendering, intercept drills, dispatch commands, and react to events. A full set of React hooks exposes the underlying Redux state machine for plugin authors. See [Dashboard & plugins](https://www.gooddata.ai/docs/gooddata-ui/latest/dashboard-plugins/index.md).
**Filters.** The SDK ships ready-to-use React components for four filter types: attribute (single- and multi-select), date (absolute, relative, presets), measure-value, and ranking. Attribute filters also come as headless hooks, so you can build a custom UI while reusing the SDK's loading, paging, and selection logic. See [Filters](https://www.gooddata.ai/docs/gooddata-ui/latest/filters/index.md).
**Data layer.** When a ready-made chart is not enough, the data layer gives you the raw data. [`Execute`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.execute/index.md), [`RawExecute`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.rawexecute/index.md), and [`ExecuteInsight`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.executeinsight/index.md) are render-prop components that run analytics queries; hooks such as `useExecutionDataView` and `useInsightDataView` expose the same power to function components. The data model covers measures, attributes, and a generated metadata catalog that gives you typed references to workspace objects. See [Data layer](https://www.gooddata.ai/docs/gooddata-ui/latest/data-layer/index.md).
**AI and high-level modules.** Ready-made product surfaces built on top of the SDK: an AI Assistant for conversational analytics, Semantic Search for meaning-based discovery, the Analytics Catalog explorer, and a Notifications panel for alerts. See [AI & modules](https://www.gooddata.ai/docs/gooddata-ui/latest/ai-modules/index.md).
**Integrations.** Everything that sits between the SDK and your app shell: authentication, cross-origin setup, theming, drilling and interactivity, Angular and Vue adapters, and context hooks for reading backend, workspace, organization, and theme from any component. See [Integrations](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/index.md).
## [Building with an AI coding assistant?](https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/#building-with-an-ai-coding-assistant)
This documentation is also published as Markdown for tools such as Cursor, GitHub Copilot, or Claude. Point your assistant at [llms.txt](https://www.gooddata.ai/docs/gooddata-ui/llms.txt), the index of every page. The [LLMs](https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/llms/index.md) page has the details.
To let the assistant work with your GoodData workspace itself, connect it to the GoodData MCP server. The [LLMs](https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/llms/index.md#give-the-assistant-access-to-your-workspace) page links the setup.
---
# Add GoodData.UI to an existing React app
> Add GoodData.UI to an existing React application by installing the packages, importing the styles, connecting the analytical backend, and rendering a dashboard your users pick from a list.
Source: https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/installation/index.md
GoodData.UI is distributed as npm packages under the `@gooddata` scope. This guide adds them to a React project you already have and ends with a dashboard on screen, chosen from a list of the dashboards in your workspace. Starting from scratch? The [Quick start](https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/quickstart/index.md) scaffolds a working app in one command instead.
## [Check the prerequisites](https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/installation/#check-the-prerequisites)
- **Node.js** `>=24.12.0` (an LTS release is recommended)
- **React** 18 or 19
- **TypeScript** 5.8.3 or newer
- A bundler that resolves ES modules. The packages are [ES modules only](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/platform/esm-only/index.md) and have no CommonJS build
- A **GoodData Cloud** or **GoodData.CN** workspace, and its hostname
Using GoodData Legacy (the deprecated GoodData Platform)? Stay on GoodData.UI version 9. [Platform compatibility](https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/platform-compatibility/index.md) explains why.
## [Install the packages](https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/installation/#install-the-packages)
> **Note:**
> No access to npm? On GoodData.CN, your own deployment already serves GoodData.UI as the Web Components library, so you
> can embed dashboards and visualizations without installing any package. See
> [Web Components overview](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/web-components-overview/index.md#load-the-library).
Every GoodData.UI app needs the backend connector, the core UI package, and the data model:
```bash
npm install @gooddata/sdk-backend-tiger @gooddata/sdk-ui @gooddata/sdk-model
```
Then add the packages for the components you plan to render. Install only what you use, because each one brings its own stylesheet and bundle weight:
```bash
# Dashboard: renders a whole saved dashboard
npm install @gooddata/sdk-ui-dashboard
# Charts: BarChart, PieChart, LineChart, ...
npm install @gooddata/sdk-ui-charts
# Pivot table
npm install @gooddata/sdk-ui-pivot
# InsightView: renders any visualization saved in your workspace
npm install @gooddata/sdk-ui-ext
# Attribute, date, measure-value, and ranking filters
npm install @gooddata/sdk-ui-filters
# Shared UI primitives (buttons, dropdowns, overlays) the packages above rely on
npm install @gooddata/sdk-ui-kit
```
If you prefer a single dependency, `@gooddata/sdk-ui-all` re-exports `@gooddata/sdk-model`, `@gooddata/sdk-backend-spi`, `@gooddata/sdk-ui`, and the charts, geo, pivot, filters, and [`InsightView`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-ext/sdk-ui-ext.insightview/index.md) packages. It does not include `@gooddata/sdk-ui-dashboard` or the AI packages, so install those separately.
## [Import the styles](https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/installation/#import-the-styles)
The components ship CSS you have to import once, typically in your app's entry file. Import only the packages you installed:
```tsx
import "@gooddata/sdk-ui-kit/styles/css/main.css";
import "@gooddata/sdk-ui-filters/styles/css/main.css";
import "@gooddata/sdk-ui-charts/styles/css/main.css";
import "@gooddata/sdk-ui-pivot/styles/css/main.css";
import "@gooddata/sdk-ui-ext/styles/css/main.css";
import "@gooddata/sdk-ui-dashboard/styles/css/main.css";
```
## [Connect the backend](https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/installation/#connect-the-backend)
Create one analytical backend instance and hand it to the whole component tree through [`BackendProvider`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.backendprovider/index.md). [`WorkspaceProvider`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.workspaceprovider/index.md) names the workspace whose data you render. Every GoodData.UI component reads both from React context, so you set them up once at the root:
```tsx
import { BackendProvider, WorkspaceProvider } from "@gooddata/sdk-ui";
import {
ContextDeferredAuthProvider,
redirectToTigerAuthentication,
tigerFactory,
} from "@gooddata/sdk-backend-tiger";
// The browser already holds a GoodData session (SSO, or you are signed in to GoodData Cloud).
// When your app is served from a different origin than GoodData, call onHostname first:
// tigerFactory().onHostname("https://your-instance.gooddata.com").withAuthentication(...)
// and allow your app's origin in the CORS settings.
const backend = tigerFactory().withAuthentication(
new ContextDeferredAuthProvider(redirectToTigerAuthentication),
);
export function App() {
return (
);
}
```
[`ContextDeferredAuthProvider`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-tiger/sdk-backend-tiger.contextdeferredauthprovider/index.md) is the right choice for production apps. It expects the user to be signed in already, and `redirectToTigerAuthentication` sends them to the GoodData sign-in flow when they aren't. [Authenticate to the backend](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/authentication/index.md) covers the other options, such as API tokens during development and JWT. If your app runs on a different origin than GoodData, read [Resolve cross-origin errors](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/cross-origin-issues/index.md) for the dev server proxy and the production CORS setup.
## [Render a dashboard your users pick](https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/installation/#render-a-dashboard-your-users-pick)
Most embedded apps don't hardcode a dashboard id. They ask the workspace which dashboards exist, show the titles in a sidebar or a menu, and render whichever one the user picks. The same `backend` you created above exposes that list, and the [`Dashboard`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.dashboard/index.md) component accepts the picked identifier as a plain string.
`useBackendStrict` and `useWorkspaceStrict` read the two providers from context. `useCancelablePromise` is the SDK's small hook for async calls in components. It tracks loading and error state and cancels the call if the component unmounts. Swap in your own data-fetching library if you already use one.
```tsx
import { useState } from "react";
import { useBackendStrict, useCancelablePromise, useWorkspaceStrict } from "@gooddata/sdk-ui";
import { Dashboard } from "@gooddata/sdk-ui-dashboard";
export function Analytics() {
const backend = useBackendStrict();
const workspace = useWorkspaceStrict();
const [selectedId, setSelectedId] = useState();
const { result: dashboards, status, error } = useCancelablePromise(
{ promise: () => backend.workspace(workspace).dashboards().getDashboards() },
[backend, workspace],
);
if (status === "error") {
return
);
}
```
Each entry in the list has an `identifier`, a `title`, and a `description`, so you can build whatever navigation fits your app. Store the selected id in your router or global state if the dashboard should survive a page reload.
The [`Dashboard`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.dashboard/index.md) component brings the whole thing: layout, filter bar, widgets, drilling, and exports. The [Dashboard component](https://www.gooddata.ai/docs/gooddata-ui/latest/dashboard-plugins/dashboard/index.md) page lists every prop, and [Embed dashboards](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/embedding/embed-dashboards/index.md) shows how to react to its events and tune what it shows.
## [Optional: typed references with the metadata catalog](https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/installation/#optional-typed-references-with-the-metadata-catalog)
When you build charts in code rather than rendering saved ones, you reference measures and attributes by id. `@gooddata/catalog-export` can generate a TypeScript file with a typed constant for each object in your workspace, so a mistyped id fails at compile time:
```tsx
import { BarChart } from "@gooddata/sdk-ui-charts";
import * as Md from "./catalog.js";
export function Revenue() {
return ;
}
```
The constant names come from your workspace, so `Md.Revenue` and `Md.Product.Default` stand in for whatever the exporter generated for you. Install the tool as a dev dependency, describe your workspace in a `gooddata` block in `package.json`, and give it an API token through the `TIGER_API_TOKEN` environment variable. [Export catalog](https://www.gooddata.ai/docs/gooddata-ui/latest/data-layer/data-model/export-catalog/index.md) has the setup and the [Quick start](https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/quickstart/index.md#look-around-the-project) shows it wired into a project.
## [Next steps](https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/installation/#next-steps)
- The [Quick start](https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/quickstart/index.md) shows the same setup in a scaffolded app, then renders a chart built in code and reads raw data.
- [Integrate into an existing application](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/backend-setup/index.md) is the long version of this page, including production CORS and authentication.
- [Apply theming](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/embedding/apply-theming/index.md) makes the embedded dashboard match your app.
- [Visualizations](https://www.gooddata.ai/docs/gooddata-ui/latest/visualisations/index.md) helps you pick a component when one chart is enough.
---
# Quick start
> Scaffold a GoodData.UI React app with app-toolkit, render a dashboard and a chart you define in code, read raw data, apply a theme, and connect your own workspace.
Source: https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/quickstart/index.md
The fastest way to see GoodData.UI working is `@gooddata/app-toolkit`. It scaffolds a small React app that is already connected to a public demo workspace, so the first chart renders before you configure anything. This tutorial takes you from that command to your own data.
You need Node.js `>=24.12.0` (an LTS release is recommended) and npm. You don't need a GoodData account yet.
## [Create the project](https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/quickstart/#create-the-project)
Run the toolkit and answer its one prompt, the language (TypeScript or JavaScript):
```bash
npx @gooddata/app-toolkit@latest init my-analytics-app
```
The toolkit unpacks the `react-app` template into `my-analytics-app/` and installs its dependencies with npm. Prefer yarn, or want to skip the prompt? Pass `--package-manager yarn`, `--language ts`, or `--skip-install`; `npx @gooddata/app-toolkit@latest init --help` lists every option.
Start the dev server:
```bash
cd my-analytics-app
npm start
```
Your browser opens on `https://127.0.0.1:3000` with a page that says "Hello GoodWorld!" and renders a pie chart of product categories from the demo workspace. That chart is a saved visualization, rendered by the [`InsightView`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-ext/sdk-ui-ext.insightview/index.md) component. The dev server uses a self-signed certificate, so accept the browser's warning once. Set the `PORT` environment variable if 3000 is taken; the dev server fails rather than picking another port.
## [Look around the project](https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/quickstart/#look-around-the-project)
There is no framework hiding anything. Every file is yours to edit:
```text
my-analytics-app/
├── package.json # Dependencies, scripts, and the gooddata block
├── vite.config.ts # Vite build and dev server, including the API proxy
├── index.html # Page that Vite serves; loads src/index.tsx
├── tsconfig.json # TypeScript configuration (TypeScript projects only)
├── .env # Holds TIGER_API_TOKEN, empty for now
├── .gitignore # Already ignores .env
├── README.md
├── public/ # Static files served as-is, currently the favicon
└── src/
├── index.tsx # React entry point; imports the SDK stylesheets
├── App.tsx # The sample component. Start here
├── backend.ts # Analytical backend instance and auth provider
├── catalog.ts # Generated workspace metadata, don't edit by hand
├── index.css # Styles for the sample page
├── typings.d.ts # Ambient types for SVG and CSS imports and WORKSPACE_ID
└── assets/ # Logo and background image used by the sample page
```
If you chose JavaScript at the prompt, the same files use `.jsx` and `.js` extensions, including `vite.config.js`, and there's no `tsconfig.json` or `typings.d.ts`.
Three files do most of the work:
`src/App.tsx` is where you'll spend your time. It wraps the app in [`BackendProvider`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.backendprovider/index.md) and [`WorkspaceProvider`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.workspaceprovider/index.md) and renders a single [`InsightView`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-ext/sdk-ui-ext.insightview/index.md). Every step below edits this file, and each starts from the sample as the toolkit generated it, so take them in any order.
> **Note:**
> The term 'insight' is an obsolete expression for 'visualizations' but is still employed within the SDK's components and functions.
That's why the catalog constant is `Insights` and the component is [`InsightView`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-ext/sdk-ui-ext.insightview/index.md).
`src/catalog.ts` is generated. `@gooddata/catalog-export` reads your workspace and writes a typed constant for each visualization, dashboard, measure, and attribute. In TypeScript, a mistyped reference then fails at compile time rather than at runtime. Run `npm run refresh-md` to regenerate it.
`package.json` carries a `gooddata` block that the rest of the setup reads:
```json
"gooddata": {
"hostname": "https://public-examples.gooddata.com",
"workspaceId": "demo",
"backend": "tiger",
"catalogOutput": "src/catalog.ts"
}
```
The dev server [proxies API calls](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/cross-origin-issues/index.md#proxy-the-api-in-development) to `hostname`, so the browser never makes a cross-origin request. Vite's `define` option injects `workspaceId` into the app as the `WORKSPACE_ID` global, and `refresh-md` writes to `catalogOutput`. You'll change the first two values when you [connect your own data](#connect-your-own-data).
The scripts you'll use:
- `npm start` starts the dev server.
- `npm run build` bundles the production version of the app into `dist/`.
- `npm run refresh-md` regenerates the [metadata catalog](https://www.gooddata.ai/docs/gooddata-ui/latest/data-layer/data-model/export-catalog/index.md#applications-created-with-app-toolkit).
## [Render a dashboard](https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/quickstart/#render-a-dashboard)
The sample renders one saved visualization. Let's render a whole saved dashboard instead, with its filters, layout, and cross-filtering. Two edits in `App.tsx`:
1. Import the [`Dashboard`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.dashboard/index.md) component and the `Dashboards` catalog constants.
```diff
- import { InsightView } from "@gooddata/sdk-ui-ext";
+ import { Dashboard } from "@gooddata/sdk-ui-dashboard";
- import { Insights } from "./catalog.js";
+ import { Dashboards } from "./catalog.js";
```
2. Swap the component in JSX and point it at a dashboard from the catalog.
```diff
-
+
```
The dev server reloads and the "1. Overview" dashboard from the demo workspace fills the page. Read more about the [Dashboard component](https://www.gooddata.ai/docs/gooddata-ui/latest/dashboard-plugins/dashboard/index.md).
The catalog constant is handy here, but real apps usually don't hardcode a dashboard. They list the workspace's dashboards at runtime and render the one the user picks. [Add GoodData.UI to an existing React app](https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/installation/index.md#render-a-dashboard-your-users-pick) shows that pattern.
## [Build a chart in code](https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/quickstart/#build-a-chart-in-code)
You don't have to save a visualization first. Any chart component accepts measures and attributes straight from the catalog. Let's build the same pie chart by hand:
1. Import [`PieChart`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.piechart/index.md) and the measure and attribute it needs.
```diff
- import { InsightView } from "@gooddata/sdk-ui-ext";
+ import { PieChart } from "@gooddata/sdk-ui-charts";
- import { Insights } from "./catalog.js";
+ import { Category_1, PercentRevenue } from "./catalog.js";
```
2. Replace the component in JSX, passing a measure and an attribute to slice it by.
```diff
-
+
```
Every chart component works this way. You pass `measures` plus one or more attribute props such as `viewBy` or `stackBy`. Read more about [PieChart](https://www.gooddata.ai/docs/gooddata-ui/latest/visualisations/pie-chart/index.md) and the rest of the [visualizations](https://www.gooddata.ai/docs/gooddata-ui/latest/visualisations/index.md).
## [Read the raw data](https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/quickstart/#read-the-raw-data)
Sometimes you want the numbers rather than a chart, maybe to feed your own visualization library or your app's business logic. The `useInsightDataView` hook runs the same execution a chart would and hands you the result.
1. Create `src/MyTable.tsx`, which renders the pie chart's data as a plain table:
```tsx
import { useInsightDataView } from "@gooddata/sdk-ui";
import { idRef } from "@gooddata/sdk-model";
import { Insights } from "./catalog.js";
export function MyTable() {
const { result, error, status } = useInsightDataView({
insight: idRef(Insights.ProductCategoriesPieChart),
});
if (error) {
console.error(error);
return
);
}
```
2. Render it from `App.tsx`:
```diff
- import { InsightView } from "@gooddata/sdk-ui-ext";
+ import { MyTable } from "./MyTable.js";
```
```diff
-
+
```
Read more about [useInsightDataView](https://www.gooddata.ai/docs/gooddata-ui/latest/data-layer/use-insight-data-view/index.md) and the rest of the [data layer](https://www.gooddata.ai/docs/gooddata-ui/latest/data-layer/index.md).
## [Apply a theme](https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/quickstart/#apply-a-theme)
Theming makes embedded analytics look like part of your app rather than a widget dropped in. [`ThemeProvider`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-theme-provider/sdk-ui-theme-provider.themeprovider/index.md) loads the theme configured on your GoodData server and lets you override any part of it in code. In `App.tsx`:
1. Import [`ThemeProvider`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-theme-provider/sdk-ui-theme-provider.themeprovider/index.md).
```diff
+ import { ThemeProvider } from "@gooddata/sdk-ui-theme-provider";
```
2. Wrap the content inside [`WorkspaceProvider`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.workspaceprovider/index.md).
```diff
+
...
+
```
If your workspace has a custom theme defined on the server, it is applied now.
3. Override how tooltips look:
```diff
-
+
```
Read more about [theming](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/embedding/apply-theming/index.md) and try [the theming example in the gallery](https://gdui-examples.herokuapp.com/theming).
## [Connect your own data](https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/quickstart/#connect-your-own-data)
So far the app has been reading the [public demo workspace](https://www.gooddata.ai/docs/cloud/getting-started/connect-data/#example-database), the same data a GoodData Cloud or GoodData.CN trial starts with. Point it at your workspace in four steps:
1. In `package.json`, replace `hostname` and `workspaceId`:
```diff
- "hostname": "https://public-examples.gooddata.com",
- "workspaceId": "demo",
+ "hostname": "https://",
+ "workspaceId": "",
```
2. Create an [API token](https://www.gooddata.ai/docs/cloud/manage-organization/user-token/) and paste it into the `.env` file in the project root. The dev-server proxy attaches it to every API call, and `refresh-md` uses it too:
```bash
TIGER_API_TOKEN=
```
The file is already listed in `.gitignore`. Never commit it.
3. Regenerate the catalog for the new workspace:
```bash
npm run refresh-md
```
4. Update `App.tsx`. The demo visualization no longer exists in your workspace, so pick one of yours from the regenerated `Insights` constants:
```diff
-
+ } showTitle />
```
Restart `npm start` and your own data renders. Putting the token in the dev proxy is fine for development only. Before you ship, switch to the sign-in flow described in [Authenticate to the backend](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/authentication/index.md) and allow your app's origin in [CORS settings](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/cross-origin-issues/index.md#allow-your-origin-in-production).
## [Next steps](https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/quickstart/#next-steps)
Your app renders your data. From here, pick the guide that matches what you're building:
- [Add GoodData.UI to an existing React app](https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/installation/index.md) applies the same setup to a React app you already have.
- [Embed dashboards](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/embedding/embed-dashboards/index.md) drops a full dashboard into your app and configures it.
- [Apply theming](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/embedding/apply-theming/index.md) matches embedded analytics to your brand.
- [Filters](https://www.gooddata.ai/docs/gooddata-ui/latest/filters/index.md) let users narrow down what a chart or dashboard shows.
- The [Angular](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/framework-integrations/angular-integration/index.md), [Vue](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/framework-integrations/vue-integration/index.md), and [Next.js](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/framework-integrations/nextjs-integration/index.md) guides take GoodData.UI outside a plain React app.
---
# Platform compatibility
> Which GoodData.UI major works with GoodData Cloud, GoodData.CN, and GoodData Legacy, the Node.js, React, and TypeScript versions it needs, and which frameworks it supports.
Source: https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/platform-compatibility/index.md
Use this page to confirm that your GoodData platform, your toolchain, and your frontend framework all work with the GoodData.UI version you are about to install.
## [GoodData platform](https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/platform-compatibility/#gooddata-platform)
| GoodData.UI | GoodData Cloud | GoodData.CN | GoodData Legacy |
| :---------- | :------------- | :---------- | :-------------- |
| **11** | Yes | Yes | No |
| **10** | Yes | Yes | No |
| **9** | Yes | Yes | Yes |
Version 11 is the current major and the one this documentation describes. Version 10 reached end of support on March 26, 2026, and no longer receives fixes.
> **GoodData Legacy:**
> GoodData Legacy (the deprecated GoodData Platform) is supported only by GoodData.UI version 9. Stay on version 9 and do not upgrade to version 10 or higher. From version 10 onwards, GoodData.UI supports only GoodData Cloud and GoodData.CN.
## [Toolchain](https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/platform-compatibility/#toolchain)
| Technology | Requirement |
| :------------- | :---------------------------------------- |
| **Node.js** | `>=24.12.0` (an LTS release is recommended) |
| **React** | 18 or 19 |
| **TypeScript** | 5.8.3 or newer |
| **Bundler** | Resolves ES modules and the `exports` field: Vite, webpack 5, Rollup, esbuild, Parcel 2, or Next.js |
With `skipLibCheck` turned off, TypeScript older than 5.8.3 reports errors in the package typings.
Every `@gooddata` package is published as [ES modules only](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/platform/esm-only/index.md). There is no CommonJS build, so TypeScript needs `moduleResolution` set to `NodeNext` or `Bundler`, and Jest needs its ESM mode. The project that `@gooddata/app-toolkit` scaffolds is already configured this way.
## [Frameworks](https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/platform-compatibility/#frameworks)
GoodData.UI directly supports React, which is what the SDK is written for, and Web Components. The `gd-dashboard-embed`, `gd-insight-embed`, and `gd-ai-assistant` custom elements load from your GoodData server with one `
```
The file must be served from the same origin as your app; the provider ignores messages from anywhere else.
## [Create the provider](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/renew-session-silently/#create-the-provider)
Now extend [`ContextDeferredAuthProvider`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-tiger/sdk-backend-tiger.contextdeferredauthprovider/index.md) and override `authenticate()`:
```ts
import {
type IAuthenticatedPrincipal,
type IAuthenticationContext,
isNotAuthenticated,
type NotAuthenticatedHandler,
} from "@gooddata/sdk-backend-spi";
import { ContextDeferredAuthProvider } from "@gooddata/sdk-backend-tiger";
const AUTH_FINISHED = "gooddata-auth-finished";
export class SilentRenewalAuthProvider extends ContextDeferredAuthProvider {
// withAuthentication() remembers the first signed-in user and would never call authenticate() again.
public override disablePrincipalCache = true;
private renewal: Promise | undefined;
constructor(
private readonly gooddataHost: string, // "https://example.gooddata.com"
private readonly callbackUrl: string, // "https://app.example.com/auth-callback.html"
onNotAuthenticated: NotAuthenticatedHandler,
private readonly timeoutMs = 15_000,
) {
super(onNotAuthenticated);
}
public override async authenticate(context: IAuthenticationContext): Promise {
try {
// The cookie may still be valid, for example on the first call.
return await super.authenticate(context);
} catch (error) {
if (!isNotAuthenticated(error)) {
throw error;
}
}
// One renewal at a time, however many requests failed.
this.renewal ??= this.renewInIframe().finally(() => {
this.renewal = undefined;
});
await this.renewal;
// Throws NotAuthenticated if the renewal didn't help; the SDK then calls onNotAuthenticated.
return super.authenticate(context);
}
private renewInIframe(): Promise {
return new Promise((resolve) => {
const loginUrl = new URL("/appLogin", this.gooddataHost);
loginUrl.searchParams.set("redirectTo", this.callbackUrl);
const iframe = document.createElement("iframe");
iframe.hidden = true;
iframe.src = loginUrl.href;
const finish = () => {
window.clearTimeout(timer);
window.removeEventListener("message", onMessage);
iframe.remove();
resolve();
};
const onMessage = (event: MessageEvent) => {
if (event.origin === window.location.origin && event.data === AUTH_FINISHED) {
finish();
}
};
// A stuck or prompting identity provider never reaches the callback page.
const timer = window.setTimeout(finish, this.timeoutMs);
window.addEventListener("message", onMessage);
document.body.appendChild(iframe);
});
}
}
```
The promise always resolves, also on timeout. The next `super.authenticate()` decides whether the renewal
worked, so a failed renewal ends in your handler instead of a request that never returns.
## [Connect the provider to the backend](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/renew-session-silently/#connect-the-provider-to-the-backend)
Pass the provider to the backend, with a handler for the case the renewal can't fix, for example a user whose
identity provider session has ended too:
```ts
import { redirectToTigerAuthentication, tigerFactory } from "@gooddata/sdk-backend-tiger";
import debounce from "lodash/debounce";
const authProvider = new SilentRenewalAuthProvider(
"https://example.gooddata.com",
`${window.location.origin}/auth-callback.html`,
// Last resort: the full sign-in. Debounced, because every failed request calls it.
debounce(redirectToTigerAuthentication, 500),
);
const backend = tigerFactory().onHostname("https://example.gooddata.com").withAuthentication(authProvider);
```
Instead of the redirect, you can show a "Your session expired" message and let the user choose when to sign
in. See [Write your own handler](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/authentication/index.md#write-your-own-handler).
## [Test the renewal](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/renew-session-silently/#test-the-renewal)
1. Sign in and open a page with GoodData components.
2. Delete the GoodData session cookies for the GoodData host in your browser's developer tools.
3. Change a filter or open another dashboard.
In the Network tab you see a 401, a request to `/appLogin` from an iframe, the callback page, and the retried
request with a 200. The page doesn't reload.
If the retried request still fails, look at the iframe's requests: a blocked frame (`X-Frame-Options`,
`frame-ancestors`), a blocked cookie, or a sign-in form from the identity provider means one of the
requirements at the top of this page isn't met.
## [Retry your own API calls](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/renew-session-silently/#retry-your-own-api-calls)
If your app also calls the GoodData API with `fetch`, those requests don't go through the SDK's retry. Wrap them the same way: on 401, call
`backend.authenticate(true)` once and repeat the request.
```ts
async function gooddataFetch(path: string, init: RequestInit = {}): Promise {
const send = () =>
fetch(new URL(path, "https://example.gooddata.com"), {
...init,
credentials: "include",
// Without it, GoodData answers an expired session with a login page instead of 401.
headers: { "X-Requested-With": "XMLHttpRequest", ...init.headers },
});
const response = await send();
if (response.status !== 401) {
return response;
}
await backend.authenticate(true); // runs the renewal; throws if the user must sign in
return send();
}
```
---
# Resolve cross-origin errors
> Resolve CORS errors between your app and GoodData Cloud or GoodData.CN by proxying the API through your dev server or allowing your origin in production.
Source: https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/cross-origin-issues/index.md
The browser blocks a request when your app's origin differs from the GoodData origin and GoodData hasn't allowed that origin. You'll see it the moment an app on `http://localhost:3000` calls `https://your-org.cloud.gooddata.com` — the request fails with a CORS error, even though the same URL works when you paste it into the address bar. This is the browser's [same-origin policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy) at work.
There are two fixes, one per environment:
- **In development, proxy the API through your dev server.** The browser sees a single origin, so no cross-origin request happens and no GoodData-side configuration is needed.
- **In production, allow your app's origin on the GoodData side.** Add the origin to your organization's CORS settings.
Loading a dashboard plugin from your own host is the reverse direction: the GoodData dashboard requests files from your server, so your host needs the CORS headers instead. See [Host the plugin](https://www.gooddata.ai/docs/gooddata-ui/latest/dashboard-plugins/develop-your-first-plugin/index.md#host-the-plugin).
## [Proxy the API in development](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/cross-origin-issues/#proxy-the-api-in-development)
Your dev server forwards every request under `/api` to your GoodData host. As far as the browser is concerned the API lives at `http://localhost:3000/api`, so the request is same-origin and never triggers a preflight.
For this to work, the backend must build origin-relative URLs. Create it without `onHostname`:
```ts
import {
ContextDeferredAuthProvider,
redirectToTigerAuthentication,
tigerFactory,
} from "@gooddata/sdk-backend-tiger";
// no onHostname() — requests go to the dev server, which proxies them
export const backend = tigerFactory().withAuthentication(
new ContextDeferredAuthProvider(redirectToTigerAuthentication),
);
```
If you scaffolded your app with `@gooddata/app-toolkit`, this proxy is already configured — see [Quick start](https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/quickstart/index.md).
### [Vite](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/cross-origin-issues/#vite)
Add a `server.proxy` entry to `vite.config.ts`:
```ts
import react from "@vitejs/plugin-react";
import { defineConfig, loadEnv } from "vite";
const BACKEND_URL = "https://public-examples.gooddata.com";
// Everything that has to reach the backend rather than the dev server.
const BACKEND_ENDPOINTS = "^/(api/|gdc/|account\\.html|truste\\.html|account/)";
export default defineConfig(({ mode }) => {
// the third argument loads every variable, not just the VITE_-prefixed ones
const env = loadEnv(mode, process.cwd(), "");
const apiToken = env["TIGER_API_TOKEN"];
return {
plugins: [react()],
server: {
port: 3000,
// Vite's dev server allows any origin by default. The proxy below injects your API token into
// every backend request, so leaving CORS on would let any other page on localhost ride that
// token through your dev server. Turn it off.
cors: false,
proxy: {
[BACKEND_ENDPOINTS]: {
target: BACKEND_URL,
changeOrigin: true,
// An empty string strips the cookie's Domain attribute, so the browser stores a host-only
// cookie valid for whichever of 127.0.0.1 / localhost you opened the dev server on.
cookieDomainRewrite: "",
secure: false,
headers: {
// The literal string "null" is the serialized opaque origin. Setting it here, rather
// than stripping the header in a proxyReq callback, also covers requests http-proxy
// skips that callback for (any request carrying `Expect: 100-continue`).
origin: "null",
...(apiToken ? { Authorization: `Bearer ${apiToken}` } : {}),
},
},
},
},
};
});
```
### [webpack](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/cross-origin-issues/#webpack)
Add a `devServer.proxy` entry to `webpack.config.cjs`. `webpack-dev-server` 5 takes an array of proxy rules:
```js
require("dotenv").config();
const BACKEND_URL = "https://public-examples.gooddata.com";
// Everything that has to reach the backend rather than the dev server.
const BACKEND_ENDPOINTS = /^\/(api\/|gdc\/|account\.html|truste\.html|account\/)/;
const apiToken = process.env.TIGER_API_TOKEN;
module.exports = {
// ...the rest of your configuration
devServer: {
host: "127.0.0.1",
port: 3000,
proxy: [
{
context: (pathname) => BACKEND_ENDPOINTS.test(pathname),
target: BACKEND_URL,
changeOrigin: true,
// An empty string strips the cookie's Domain attribute, so the browser stores a host-only
// cookie valid for whichever of 127.0.0.1 / localhost you bind the dev server to.
cookieDomainRewrite: "",
secure: false,
headers: {
// The literal string "null" is the serialized opaque origin. Setting it here, rather
// than stripping the header in an onProxyReq callback, also covers requests http-proxy
// skips that callback for (any request carrying `Expect: 100-continue`).
origin: "null",
...(apiToken ? { Authorization: `Bearer ${apiToken}` } : {}),
},
},
],
},
};
```
Both configurations use the same options:
- `changeOrigin` rewrites the `Host` header to the target host, so GoodData sees a request addressed to itself.
- `cookieDomainRewrite: ""` strips the session cookie's `Domain` attribute, so the browser stores a host-only cookie that works no matter which of `127.0.0.1`/`localhost` you bind the dev server to — no need to keep it in sync with your dev server's host.
- `secure: false` accepts a self-signed certificate, which you need when proxying to a local GoodData.CN instance.
- Setting `headers.origin` to the string `"null"` stops the forwarded request from still advertising your dev server, which GoodData would read as cross-origin. Setting it as a static header, rather than removing it in a `proxyReq`/`onProxyReq` callback, also covers requests where the underlying `http-proxy` library skips that callback (any request carrying `Expect: 100-continue`).
- The proxy path pattern covers more than `/api` — GoodData Cloud and GoodData.CN also serve some endpoints under `/gdc/`, `/account/`, `/account.html`, and `/truste.html`.
> **cors: false is Vite-specific:**
> Vite's dev server allows any origin by default, which would let any other page on `localhost` ride your injected API token through the proxy — hence `cors: false` in the Vite example above. `webpack-dev-server` doesn't enable permissive CORS by default, so it needs no equivalent setting.
> **The API token is for development only:**
> Injecting `Authorization` in the proxy keeps the token out of your bundle, but it's still a token with your permissions on a machine you control. Keep it in `.env`, keep `.env` out of version control, and never carry this proxy into production — deploy with a real authentication flow instead. See [Authenticate to the backend](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/authentication/index.md).
> **Geo charts need one more rule:**
> [`GeoChart`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-geo/sdk-ui-geo.geochart/index.md) and [`GeoPushpinChart`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-geo/sdk-ui-geo.geopushpinchart/index.md) load map glyphs and tiles from URLs returned by `/api/v1/location/style`. Those URLs are absolute and point at the GoodData host, so MapLibre fetches them cross-origin and the map stays blank. A working proxy has to intercept that response and rewrite its URLs to the dev-server origin. The `vite.config.ts` that `npx @gooddata/app-toolkit@latest init` generates already does this — start from it rather than writing the rewrite yourself. See [Quick start](https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/quickstart/index.md).
## [Allow your origin in production](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/cross-origin-issues/#allow-your-origin-in-production)
A deployed app can't proxy its way around CORS, so add its origin to your organization's allowlist.
### [GoodData Cloud](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/cross-origin-issues/#gooddata-cloud)
Configure CORS in the settings of your GoodData Cloud instance. If your instance is at `https://example.com`, the settings are at `https://example.com/settings`; you can also reach the page from your instance's home page. You can set the same `allowedOrigins` attribute through the organization API.
For the accepted origin formats and the API call, see [Set up CORS for an organization](https://www.gooddata.ai/docs/cloud/manage-organization/set-up-cors-for-organization/).
### [GoodData.CN](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/cross-origin-issues/#gooddatacn)
Set `allowedOrigins` on the organization the same way you would in GoodData Cloud. The GoodData.CN All-in-One image is already configured to allow cross-origin requests from an application running on `https://localhost:8443`, so a local development setup needs no change.
> **CORS is not authentication:**
> An allowed origin lets the request through; it doesn't make the request authenticated. Configure authentication separately — see [Authenticate to the backend](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/authentication/index.md) for API token and context-deferred flows.
---
# Embedding
> Embed GoodData content at different levels — full dashboards, individual visualizations, or custom visualizations using your own charting library — and apply theming.
Source: https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/embedding/index.md
Embed GoodData content at the level that fits your app: render an entire dashboard, show saved visualizations inline, or build custom visualizations on GoodData's execution pipeline. To embed without React, see [Web Components](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/index.md).
---
# Embed dashboards
> Choose among a built-in dashboard embedded through an iframe, the Dashboard component, and a custom dashboard by comparing their integration, customization, and implementation trade-offs.
Source: https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/embedding/embed-dashboards/index.md
GoodData.UI offers the following methods of building and embedding dashboards:
- Embedding the [built-in dashboards](#built-in-dashboards)
- Using the [Dashboard component](#dashboard-component)
- Building [custom dashboards](#custom-dashboards)
Each method has its advantages and disadvantages.
This page explains how these methods differ, so you can pick the one that fits your use case.
The methods are described from the simplest to the most complex. As a general rule, choose the simplest method that satisfies your needs over a more complex one that requires more code or special skills to implement.
## [Built-in dashboards](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/embedding/embed-dashboards/#built-in-dashboards)
The dashboards built into GoodData Cloud and GoodData.CN are an end-to-end solution that covers both creation and consumption of dashboards. They offer many features out of the box, such as filtering, drilling, sharing, responsive layout, theming, email scheduling, export, and embedding.
Users build new dashboards and edit existing ones in a drag-and-drop user interface.
With the built-in dashboards, you have the following options:
- Embed a dashboard in your application via an [iframe](#embed-a-dashboard-via-an-iframe).
- Extend the default functionality with [dashboard plugins](#add-dashboard-plugins-to-a-dashboard).
### [Embed a dashboard via an iframe](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/embedding/embed-dashboards/#embed-a-dashboard-via-an-iframe)
Embedding a dashboard via an iframe lets you integrate it in your application or an HTML page without any SDK code.
For more information, see [Embed a dashboard via an iframe](https://www.gooddata.ai/docs/cloud/embed-visualizations/iframes/).
Advantages:
- Basic customization options via query parameters (for example, hide the filter bar)
- Support for [dashboard plugins](#add-dashboard-plugins-to-a-dashboard)
- Communication via the [postMessage API](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage)
Disadvantages:
- Limited customization options compared to the [Dashboard component](#dashboard-component)
### [Add dashboard plugins to a dashboard](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/embedding/embed-dashboards/#add-dashboard-plugins-to-a-dashboard)
Dashboard plugins let you enhance the built-in dashboards with third-party libraries, custom visualizations, and custom behavior.
With dashboard plugins, you run your own code within the dashboard. For more information, see [Dashboard plugins](https://www.gooddata.ai/docs/gooddata-ui/latest/dashboard-plugins/dashboard-plugins/index.md).
Advantages:
- Stable APIs that support GoodData Cloud and GoodData.CN
- A [CLI tool](https://www.gooddata.ai/docs/gooddata-ui/latest/dashboard-plugins/develop-your-first-plugin/index.md) (`@gooddata/plugin-toolkit`) that scaffolds, builds, and links plugins
- Support for TypeScript
Disadvantages:
- Limited customization options compared to the Dashboard component
## [Dashboard component](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/embedding/embed-dashboards/#dashboard-component)
The [`Dashboard`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.dashboard/index.md) component from `@gooddata/sdk-ui-dashboard` is a React component that renders dashboards created and saved in the built-in dashboards. It is the engine that the built-in dashboards use in the background, and you can customize it extensively.
The [`Dashboard`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.dashboard/index.md) component provides many built-in features. See [Dashboard component](https://www.gooddata.ai/docs/gooddata-ui/latest/dashboard-plugins/dashboard/index.md), which also lists its props.
On its own, the component does not load the plugins linked to a dashboard. To render a dashboard together with its plugins, load it with `useDashboardLoader` as described in [Embed a dashboard with plugins](https://www.gooddata.ai/docs/gooddata-ui/latest/dashboard-plugins/embed-dashboard-with-plugins/index.md).
Advantages:
- Deep integration with React applications with a wide range of options (eventing API, customizations)
- Extensive customization options such as custom visualization types, integration of third-party libraries, [dashboard plugins](#add-dashboard-plugins-to-a-dashboard), and so on
- APIs that support GoodData Cloud and GoodData.CN
- Support for TypeScript
Disadvantages:
- Some customization options are at alpha or beta stage
- Limited styling or layout customization options compared to [custom dashboards](#custom-dashboards)
## [Custom dashboards](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/embedding/embed-dashboards/#custom-dashboards)
If none of the methods above satisfies your needs, GoodData.UI lets you create your own dashboard.
This is the most involved method of building dashboards, but it offers the most flexibility.
Advantages:
- Everything under your control (custom visualization types, custom layout, styling and so on)
- The core `sdk-model` and `sdk-backend-*` packages compatible with any JavaScript/TypeScript framework
- Multiple ready-to-use React components and hooks, both high- and low-level: charts, contexts, and more
- The deepest integration with your application with a wide range of options
- APIs that support GoodData Cloud and GoodData.CN
Disadvantages:
- More time needed for development and maintenance compared to the other methods
- Deeper knowledge of GoodData required compared to the other methods
- More complex (but not impossible) integration with applications without React
---
# Embed visualizations
> Render a visualization saved in Analyze with InsightView by getting its identifier, importing the component and styles, and setting its insight prop.
Source: https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/embedding/embed-visualizations/index.md
To embed a visualization saved in [Analyze](https://www.gooddata.ai/docs/cloud/create-visualizations/), use the [`InsightView`](https://www.gooddata.ai/docs/gooddata-ui/latest/visualisations/insightview/index.md) component.
> **Note:**
> The term 'insight' is an obsolete expression for 'visualizations' but is still employed within the SDK's components and functions.
1. Get the identifier of the visualization. Copy it from the browser's address bar when the visualization is open in Analyze, or use the `Insights` constants that [catalog-export](https://www.gooddata.ai/docs/gooddata-ui/latest/data-layer/data-model/export-catalog/index.md) generates.
2. Render [`InsightView`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-ext/sdk-ui-ext.insightview/index.md) with that identifier, and import the styles of `@gooddata/sdk-ui-ext` once in your app:
```tsx
import { InsightView } from "@gooddata/sdk-ui-ext";
import "@gooddata/sdk-ui-ext/styles/css/main.css";
export function MyVisualization() {
return (
);
}
```
[`InsightView`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-ext/sdk-ui-ext.insightview/index.md) reads the backend and the workspace from [`BackendProvider`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.backendprovider/index.md) and [`WorkspaceProvider`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.workspaceprovider/index.md); pass the `backend` and `workspace` props to override them. See [Integrate into an existing application](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/backend-setup/index.md#provide-the-backend-and-workspace).
For every prop of the component, see [`InsightView`](https://www.gooddata.ai/docs/gooddata-ui/latest/visualisations/insightview/index.md#props).
---
# How custom visualizations get data
> Understand the hooks, components, and backend API that feed custom visualizations, and how series, slices, and data points structure the result.
Source: https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/embedding/custom-visualizations/index.md
With GoodData.UI, you can build your own visual components on top of GoodData data. This page explains the data side: which APIs fetch the data, how to describe what you need, and how to read the result. For a worked example that also replaces the filters and adds an export, follow [Build a fully custom frontend](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/embedding/build-custom-frontend/index.md).
> **Note:**
> This page builds on the [execution model](https://www.gooddata.ai/docs/gooddata-ui/latest/data-layer/execution/execution-model/index.md). The [catalog-export](https://www.gooddata.ai/docs/gooddata-ui/latest/data-layer/data-model/export-catalog/index.md) tool generates typed constants for your measures and attributes, which make the data specification easier to read.
## [Ways to get the data](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/embedding/custom-visualizations/#ways-to-get-the-data)
You can get the data for a custom visualization with React [hooks](#react-hooks), React [components](#react-components), or the [execution API](#execution-api).
Hooks and components have similar APIs and capabilities. For more complex scenarios, for example when one execution depends on another, hooks avoid nesting components inside each other.
### [React hooks](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/embedding/custom-visualizations/#react-hooks)
- [`useExecutionDataView`](https://www.gooddata.ai/docs/gooddata-ui/latest/data-layer/use-execution-data-view/index.md) fetches the data you describe with [series and slices](#series-and-slices) or with a [custom execution](https://www.gooddata.ai/docs/gooddata-ui/latest/data-layer/execution/execution-model/index.md), and reports the loading status and errors.
- [`useInsightDataView`](https://www.gooddata.ai/docs/gooddata-ui/latest/data-layer/use-insight-data-view/index.md) fetches the data of a visualization saved in [Analyze](https://www.gooddata.ai/docs/cloud/create-visualizations/), so you can render it with your own component. It's [`InsightView`](https://www.gooddata.ai/docs/gooddata-ui/latest/visualisations/insightview/index.md) without the view part.
### [React components](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/embedding/custom-visualizations/#react-components)
- [`Execute`](https://www.gooddata.ai/docs/gooddata-ui/latest/data-layer/execute/index.md) is the component counterpart of `useExecutionDataView` for data described with [series and slices](#series-and-slices).
- [`RawExecute`](https://www.gooddata.ai/docs/gooddata-ui/latest/data-layer/raw-execute/index.md) is the component counterpart of `useExecutionDataView` for a [custom execution](https://www.gooddata.ai/docs/gooddata-ui/latest/data-layer/execution/execution-model/index.md).
- [`ExecuteInsight`](https://www.gooddata.ai/docs/gooddata-ui/latest/data-layer/execute-insight/index.md) is the component counterpart of `useInsightDataView`: it fetches the data of a saved visualization.
Each of them fetches the result and reports the loading status and errors.
### [Execution API](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/embedding/custom-visualizations/#execution-api)
Without hooks or components, you can get the data directly from the analytical backend instance. See [custom executions](https://www.gooddata.ai/docs/gooddata-ui/latest/data-layer/execution/execution-model/index.md).
## [Series and slices](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/embedding/custom-visualizations/#series-and-slices)
The execution hooks and components describe the data as series and slices. Two examples show how they relate.
### [Tabular data](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/embedding/custom-visualizations/#tabular-data)
Imagine a custom table component that shows one row for each value of the attribute `A1`. Each row has two columns, one for the measure `M1` and one for the measure `M2`.
Here, the data series are the two measures `M1` and `M2`, and the slices come from the attribute `A1`.
Now the table becomes more dynamic: for each value of the attribute `A2`, it includes two columns, one for each measure, `M1` and `M2`.
Here, the data series are the measures `M1` and `M2`, **scoped** to the values of the attribute `A2`. On top of that, these columns are sliced by the values of the attribute `A1`.
### [Scalars](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/embedding/custom-visualizations/#scalars)
Imagine a custom headline component that shows several key figures, each calculated from a different measure: `M1`, `M2`, and `M3`.
Here, the data series are the measures `M1`, `M2`, and `M3`, and there are no data slices at all.
## [Working with the results](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/embedding/custom-visualizations/#working-with-the-results)
The result instance has methods for convenient data access:
- `result.data().series()` returns the result as a collection of data series.
- `result.data().slices()` returns the result as a collection of data slices.
- You can iterate a collection with a `for-of` loop, or turn it into an array and use the usual array functions.
- For each series or slice, you can iterate its data points:
- Iterating the data points of a series gives you one data point per slice.
- Iterating the data points of a slice gives you one data point per series.
- Each data point holds the data and the metadata: the series descriptor and the slice descriptor. You can read either the raw or the formatted value.
> **Avoid the raw backend result:**
> The result instance also exposes the raw result from the backend. Its structure is an implementation detail, so read the data through series and slices instead.
---
# Build a fully custom frontend
> Build an analytics screen with no GoodData visual components, only your own markup, by driving an execution, a headless attribute filter, a date filter, and a CSV export through GoodData.UI hooks.
Source: https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/embedding/build-custom-frontend/index.md
Sometimes nothing GoodData.UI draws should be visible: the charts come from your design system, the filters are your own controls, and the layout is yours. GoodData.UI still knows the semantic model, runs the executions, loads attribute values, caches, and exports. You only render.
In this tutorial you build a "Revenue by category" screen with a bar list drawn in plain HTML, a region filter rendered as checkboxes, a period dropdown, and a CSV download. No `@gooddata/sdk-ui-charts` or `@gooddata/sdk-ui-filters` component is involved, only hooks.
You need the project from the [Quick start](https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/quickstart/index.md), or any React app with [`BackendProvider`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.backendprovider/index.md), [`WorkspaceProvider`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.workspaceprovider/index.md), and a generated catalog, as set up in [Installation](https://www.gooddata.ai/docs/gooddata-ui/latest/getting-started/installation/index.md).
You'll use these APIs:
| To | Use | From |
| :-- | :-- | :-- |
| Run a query and read the result | `useExecutionDataView` | `@gooddata/sdk-ui` |
| Load attribute values and manage a selection | `useAttributeFilterController` | `@gooddata/sdk-ui-filters` |
| Define filters in code | `newNegativeAttributeFilter`, `newRelativeDateFilter`, `newAllTimeFilter` | `@gooddata/sdk-model` |
| Export the same query | `useDataExport` with `useBackendStrict` and `useWorkspaceStrict` | `@gooddata/sdk-ui` |
| Refer to workspace objects by name | the generated catalog | `@gooddata/catalog-export` |
The code below uses the demo workspace's catalog constants: `Revenue`, `Category_1` (the product category; the catalog adds `_1` because the workspace has two attributes titled Category), `Region`, and `DateDatasets.Date`. In your own workspace, pick the equivalents from your `catalog.ts`.
## [Draw the data yourself](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/embedding/build-custom-frontend/#draw-the-data-yourself)
Create `src/RevenueByCategory.tsx`. The hook runs one execution: the measure in `seriesBy`, the attribute to break it down by in `slicesBy`, and whatever filters the parent passes. The result has one slice per category with a single data point. `rawValue` is the number you compute with, `formattedValue()` the string to show, formatted the way the measure is defined in the workspace.
```tsx
import type { IFilter } from "@gooddata/sdk-model";
import { useExecutionDataView } from "@gooddata/sdk-ui";
import { Category_1, Revenue } from "./catalog.js";
interface IRevenueByCategoryProps {
filters: IFilter[];
}
export function RevenueByCategory({ filters }: IRevenueByCategoryProps) {
const { result, status, error } = useExecutionDataView(
{
execution: {
seriesBy: [Revenue],
slicesBy: [Category_1],
filters,
},
},
[filters],
);
if (status === "error") {
return
))}
);
}
```
The second argument, `[filters]`, is the dependency list. The hook runs again when a value in it changes, compared by reference, so the parent has to memoize the array. Render the component from `App.tsx` in place of the sample [`InsightView`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-ext/sdk-ui-ext.insightview/index.md):
```diff
- import { InsightView } from "@gooddata/sdk-ui-ext";
+ import { RevenueByCategory } from "./RevenueByCategory.js";
```
```diff
-
+
```
Four bars appear, one per category, with revenue formatted as currency. Read more about [useExecutionDataView](https://www.gooddata.ai/docs/gooddata-ui/latest/data-layer/use-execution-data-view/index.md) and the [series and slices](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/embedding/custom-visualizations/index.md#access-custom-visualization-data) behind `slices()`.
## [Add a headless attribute filter](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/embedding/build-custom-frontend/#add-a-headless-attribute-filter)
An attribute filter needs the attribute's values, paging for long lists, a selection the user is editing, and the selection they last applied. `useAttributeFilterController` manages all of that and leaves the rendering to you. Create `src/RegionFilter.tsx`:
```tsx
import { useAttributeFilterController } from "@gooddata/sdk-ui-filters";
import { type IAttributeElement, type IAttributeFilter, newNegativeAttributeFilter } from "@gooddata/sdk-model";
import { Region } from "./catalog.js";
interface IRegionFilterProps {
onApply: (filter: IAttributeFilter) => void;
}
export function RegionFilter({ onApply }: IRegionFilterProps) {
const {
isInitializing,
elements,
workingSelectionElements,
isWorkingSelectionInverted,
onSelect,
onApply: applySelection,
} = useAttributeFilterController({
// A negative filter with nothing excluded means "all regions".
filter: newNegativeAttributeFilter(Region, []),
onApply: (filter) => onApply(filter),
});
if (isInitializing) {
return
Loading regions…
;
}
const isChecked = (element: IAttributeElement) => {
const inWorkingSelection = workingSelectionElements.some((el) => el.uri === element.uri);
return isWorkingSelectionInverted ? !inWorkingSelection : inWorkingSelection;
};
const toggle = (element: IAttributeElement) => {
// Keep the selection mode and add or remove the value from the working list.
const inWorkingSelection = workingSelectionElements.some((el) => el.uri === element.uri);
const next = inWorkingSelection
? workingSelectionElements.filter((el) => el.uri !== element.uri)
: [...workingSelectionElements, element];
onSelect(next, isWorkingSelectionInverted);
};
return (
);
}
```
Two details matter here. The initial filter is a negative filter with an empty list, which GoodData.UI reads as "everything selected", and the controller reports it as an inverted selection: the working list holds the excluded values. The `toggle` function keeps that mode and only adds or removes the clicked value from the list, so values on pages you haven't loaded yet stay selected. Calling the controller's `onApply` commits the working selection and calls your `onApply` with an [`IAttributeFilter`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.iattributefilter/index.md) that executions understand. The controller loads elements in pages; for attributes with many values, call `onLoadNextElementsPage` when the user scrolls, as described in [useAttributeFilterController](https://www.gooddata.ai/docs/gooddata-ui/latest/filters/use-attribute-filter-controller/index.md).
## [Wire the filters into the execution](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/embedding/build-custom-frontend/#wire-the-filters-into-the-execution)
Now hold the filters in state and pass them down. A period dropdown adds a date filter built in code. `newRelativeDateFilter` takes the date dataset, a granularity, and a range of periods where `0` is the current one, so `-11` to `0` is the last 12 months and `-1` to `-1` is last year. `newAllTimeFilter` removes the date restriction. Replace `App.tsx`:
```tsx
import { type IAttributeFilter, type IDateFilter, newAllTimeFilter, newRelativeDateFilter } from "@gooddata/sdk-model";
import { BackendProvider, WorkspaceProvider } from "@gooddata/sdk-ui";
import { useMemo, useState } from "react";
import { backend } from "./backend.js";
import { DateDatasets } from "./catalog.js";
import { RegionFilter } from "./RegionFilter.js";
import { RevenueByCategory } from "./RevenueByCategory.js";
// WORKSPACE_ID is the global that the Quick start project injects with Vite's `define`.
// In another app, use your workspace ID string.
const workspaceId = WORKSPACE_ID;
const periods = {
all: newAllTimeFilter(DateDatasets.Date.ref),
last12Months: newRelativeDateFilter(DateDatasets.Date.ref, "GDC.time.month", -11, 0),
lastYear: newRelativeDateFilter(DateDatasets.Date.ref, "GDC.time.year", -1, -1),
} satisfies Record;
export function App() {
const [regionFilter, setRegionFilter] = useState();
const [period, setPeriod] = useState("all");
const filters = useMemo(
() => [periods[period], ...(regionFilter ? [regionFilter] : [])],
[period, regionFilter],
);
return (
Revenue by category
);
}
```
Uncheck a region and click **Apply**, or pick a period, and the bars update. The `useMemo` around `filters` is what makes that efficient: the array only changes when a filter changes, so the execution runs exactly then. Every filter you can build in code is listed in [Filters](https://www.gooddata.ai/docs/gooddata-ui/latest/filters/index.md), and the [execution model](https://www.gooddata.ai/docs/gooddata-ui/latest/data-layer/execution/execution-model/index.md) explains how filters, measures, and attributes combine.
## [Export the same data](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/embedding/build-custom-frontend/#export-the-same-data)
Export reuses the execution definition rather than the rendered result. Build an [`IPreparedExecution`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ipreparedexecution/index.md) from the same items and filters, and hand it to `useDataExport`, which runs it, asks the backend for a CSV, and returns the download URI. Render the URI as a link rather than opening it from a callback: the export can take longer than the browser's window for user-initiated popups. Create `src/ExportButton.tsx`:
```tsx
import type { IFilter } from "@gooddata/sdk-model";
import { useBackendStrict, useDataExport, useWorkspaceStrict } from "@gooddata/sdk-ui";
import { useMemo, useState } from "react";
import { Category_1, Revenue } from "./catalog.js";
interface IExportButtonProps {
filters: IFilter[];
}
export function ExportButton({ filters }: IExportButtonProps) {
const backend = useBackendStrict();
const workspace = useWorkspaceStrict();
const [requestCount, setRequestCount] = useState(0);
// Build the execution only after the first click; useDataExport stays "pending" while it is null.
const execution = useMemo(
() =>
requestCount > 0
? backend.workspace(workspace).execution().forItems([Revenue, Category_1], filters)
: null,
[requestCount, backend, workspace, filters],
);
const {
status,
result: downloadUri,
error,
} = useDataExport(
{
execution,
exportConfig: { format: "csv", title: "revenue-by-category" },
},
[execution],
);
return (
<>
{status === "success" && downloadUri ? Download the CSV : null}
{status === "error" ?
{error?.message}
: null}
);
}
```
Render `` under the bars in `App.tsx`. `useBackendStrict` and `useWorkspaceStrict` read the providers at the top of the app, so the button needs no props beyond the filters.
## [Where to go next](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/embedding/build-custom-frontend/#where-to-go-next)
The screen is yours end to end, and the pattern scales: one hook per query, filters in state, memoized arrays as dependencies.
- [How custom visualizations get data](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/embedding/custom-visualizations/index.md) explains series and slices for shapes beyond one measure by one attribute, and the [`Execute`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.execute/index.md) components when you prefer render props to hooks.
- [Result structure](https://www.gooddata.ai/docs/gooddata-ui/latest/data-layer/execution/result-structure/index.md) and [Run a custom execution](https://www.gooddata.ai/docs/gooddata-ui/latest/data-layer/execution/custom-executions/index.md) cover dimensions, totals, sorting, and running executions outside React.
- [useAttributeFilterHandler](https://www.gooddata.ai/docs/gooddata-ui/latest/filters/use-attribute-filter-handler/index.md) is the lower-level API under the controller, for filter UIs with their own state management.
- The hooks and the ready-made components share the same providers, so you can mix them. An [InsightView](https://www.gooddata.ai/docs/gooddata-ui/latest/visualisations/insightview/index.md) next to your bars reads the same `filters` array.
- Before you ship, replace the development token with a [sign-in flow](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/authentication/index.md).
---
# Apply theming
> Apply custom themes to GoodData.UI dashboards and visualizations by wrapping your app in ThemeProvider.
Source: https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/embedding/apply-theming/index.md
To apply theming in GoodData.UI, wrap your application in the [`ThemeProvider`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-theme-provider/sdk-ui-theme-provider.themeprovider/index.md) component. It loads the theme selected in your workspace, or a theme you pass in, and applies it to your dashboards and visualizations (see [Create custom themes](https://www.gooddata.ai/docs/cloud/customize-appearance/create-custom-themes/)).
To load a theme from your workspace, [`ThemeProvider`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-theme-provider/sdk-ui-theme-provider.themeprovider/index.md) needs a `backend` and a `workspace` — either from the surrounding providers or from its own props (see [Integrate into an existing application](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/backend-setup/index.md)).
> **Warning:**
> Always place [`ThemeProvider`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-theme-provider/sdk-ui-theme-provider.themeprovider/index.md) at the root of your application. A theme is applied globally to everything on the page: when you wrap one visual component in [`ThemeProvider`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-theme-provider/sdk-ui-theme-provider.themeprovider/index.md), everything else on the page is themed too, even though it is not wrapped.
## [Use ThemeProvider with backend and workspace providers](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/embedding/apply-theming/#use-themeprovider-with-backend-and-workspace-providers)
When [`ThemeProvider`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-theme-provider/sdk-ui-theme-provider.themeprovider/index.md) is rendered inside [`BackendProvider`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.backendprovider/index.md) and [`WorkspaceProvider`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.workspaceprovider/index.md), you do not need to pass it any additional props.
```tsx
import { BackendProvider, WorkspaceProvider } from "@gooddata/sdk-ui";
import { ThemeProvider } from "@gooddata/sdk-ui-theme-provider";
```
## [Use ThemeProvider without backend and workspace providers](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/embedding/apply-theming/#use-themeprovider-without-backend-and-workspace-providers)
Without [`BackendProvider`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.backendprovider/index.md) and [`WorkspaceProvider`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.workspaceprovider/index.md) in the tree, pass the `backend` and `workspace` props to [`ThemeProvider`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-theme-provider/sdk-ui-theme-provider.themeprovider/index.md) directly.
```tsx
import { ThemeProvider } from "@gooddata/sdk-ui-theme-provider";
```
## [Use ThemeProvider with a custom theme](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/embedding/apply-theming/#use-themeprovider-with-a-custom-theme)
You can define a custom theme and pass it to [`ThemeProvider`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-theme-provider/sdk-ui-theme-provider.themeprovider/index.md) through the `theme` prop; the provider then uses it instead of loading one from the workspace. For all available properties, see the [`ITheme`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.itheme/index.md) interface (beta) in the API reference.
Usage:
```tsx
import { ThemeProvider } from "@gooddata/sdk-ui-theme-provider";
```
Declaration:
```ts
import type { ITheme } from "@gooddata/sdk-model";
export const customTheme: ITheme = {
button: {
borderRadius: "15",
dropShadow: true,
textCapitalization: true,
},
modal: {
borderColor: "#1b4096",
borderRadius: "5",
borderWidth: "2",
dropShadow: false,
outsideBackgroundColor: "#e8cda2",
title: {
color: "#1b4096",
lineColor: "#000",
},
},
palette: {
error: {
base: "#ff2e5f",
},
primary: {
base: "#eba12a",
},
success: {
base: "#13ed4d",
},
warning: {
base: "#ddff19",
},
},
tooltip: {
backgroundColor: "#101050",
color: "#fff",
},
typography: {
font:
"url(https://cdn.jsdelivr.net/npm/roboto-font@0.1.0/fonts/Roboto/roboto-regular-webfont.ttf)",
fontBold:
"url(https://cdn.jsdelivr.net/npm/roboto-font@0.1.0/fonts/Roboto/roboto-bold-webfont.ttf)",
},
};
```
## [Props](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/embedding/apply-theming/#props)
| Prop | Type | Required | Description | Inherited from |
|------|------|----------|-------------|----------------|
| [`backend`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-theme-provider/sdk-ui-theme-provider.ithemeproviderprops/index.md#ithemeproviderpropsbackend) | [`IAnalyticalBackend`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ianalyticalbackend/index.md) | No | Analytical backend, from which the ThemeProvider will obtain selected theme object. | — |
| [`children`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-theme-provider/sdk-ui-theme-provider.ithemeproviderprops/index.md#ithemeproviderpropschildren) | `ReactNode` | No | React children | — |
| [`enableComplementaryPalette`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-theme-provider/sdk-ui-theme-provider.ithemeproviderprops/index.md#ithemeproviderpropsenablecomplementarypalette) | `boolean` | No | Flag determining whether the complementary palette is enabled or not. | — |
| [`modifier`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-theme-provider/sdk-ui-theme-provider.ithemeproviderprops/index.md#ithemeproviderpropsmodifier) | [`ThemeModifier`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-theme-provider/sdk-ui-theme-provider.thememodifier/index.md) | No | If provided it is called with loaded theme to allow its modification according to the app needs. | — |
| [`removeGlobalStylesOnUnmout`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-theme-provider/sdk-ui-theme-provider.ithemeproviderprops/index.md#ithemeproviderpropsremoveglobalstylesonunmout) | `boolean` | No | Should ThemeProvider remove global styles during the unmount phase? | — |
| [`theme`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-theme-provider/sdk-ui-theme-provider.ithemeproviderprops/index.md#ithemeproviderpropstheme) | [`ITheme`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.itheme/index.md) | No | Theme that will be used if defined. | — |
| [`workspace`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-theme-provider/sdk-ui-theme-provider.ithemeproviderprops/index.md#ithemeproviderpropsworkspace) | `string` | No | Identifier of analytical workspace, from which the ThemeProvider will obtain the selected theme identifier | — |
---
# Web Components
> Custom HTML elements that embed GoodData dashboards, visualizations, and the AI assistant in any framework or vanilla HTML, without a direct React dependency.
Source: https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/index.md
Custom HTML elements (`gd-dashboard-embed`, `gd-insight-embed`, `gd-ai-assistant`, and others) that work in any framework or in plain HTML. A single `
```
> **Note:**
> The Web Components library runs GoodData.UI under the hood. It loads React and the other dependencies it needs, in an isolated scope that doesn't conflict with other JavaScript in your app.
## [Choosing the right embedding option](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/web-components-overview/#choosing-the-right-embedding-option)
GoodData offers several ways to embed analytics: iframe embedding for dashboards, and the GoodData.UI React library for dashboards and visualizations. The Web Components library sits between the two. It's more flexible than an iframe and simpler to integrate than the React library.
### [When to use the Web Components library](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/web-components-overview/#when-to-use-the-web-components-library)
- You don't want iframe embedding, because of the overhead it creates or because of your company's security and compliance requirements.
- You want to embed a single visualization; iframe embedding works only for a complete dashboard.
- Your host application uses Angular, Vue, or another non-React framework.
- Your application uses a React version that GoodData.UI doesn't support.
- You can't or don't want to install packages from npm, for example on a GoodData.CN deployment in a restricted network. Your GoodData.CN instance serves the library itself; see [How the library loads](#load-the-library).
### [When to use an iframe instead](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/web-components-overview/#when-to-use-an-iframe-instead)
If you want the simplest possible dashboard embedding and don't need deep integration between the host application and the dashboard, an iframe is enough.
An iframe also fits when you want dashboard plugins but can't provide a Module Federation runtime, which `gd-dashboard-embed` needs to load plugins linked to the dashboard. The legacy `gd-dashboard` element doesn't load plugins at all.
### [When to use the GoodData.UI React library instead](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/web-components-overview/#when-to-use-the-gooddataui-react-library-instead)
If the host application is already written in React, use the GoodData.UI React components. They are more flexible, and you avoid loading a second copy of React and ReactDOM.
## [How the library loads](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/web-components-overview/#load-the-library)
The library is a JavaScript module that your GoodData instance serves at `/components/.js`. You load it with a `
```
## [Prerequisites and limitations](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/web-components-overview/#prerequisites-and-limitations)
### [Supported web browsers](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/web-components-overview/#supported-web-browsers)
The library needs a browser that supports custom elements; it doesn't work in older browsers such as Internet Explorer. See the [Custom Elements browser compatibility](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry#browser_compatibility) table on MDN.
### [Cross-origin requests](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/web-components-overview/#cross-origin-requests)
The script makes requests from your application's origin to the GoodData host, so the organization must allow your origin. See [Allow your origin in production](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/cross-origin-issues/index.md#allow-your-origin-in-production).
### [Content Security Policy (CSP)](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/web-components-overview/#content-security-policy-csp)
If your server sends [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) headers, add the GoodData host to the `script-src`, `style-src`, `font-src`, and `img-src` policies. For a GoodData host at `example.gooddata.com`, the policy could look like this:
```text
script-src 'self' 'unsafe-inline' example.gooddata.com;
img-src 'self' data: blob: example.gooddata.com;
style-src 'self' 'unsafe-inline' example.gooddata.com;
font-src 'self' data: example.gooddata.com;
```
### [Third-party cookie blocking](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/web-components-overview/#third-party-cookie-blocking)
The script authenticates its requests to the GoodData host with the GoodData session cookie. When your application runs on a different site than GoodData, the browser treats that cookie as a third-party cookie, and browsers that block third-party cookies make the requests fail even though the user signed in. Serve GoodData from the same site as your application, for example `https://analytics.example.com` next to `https://example.com`. [Cookies across sites](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/authentication/index.md#cookies-across-sites) explains the problem and the other fixes.
### [Dashboard plugins](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/web-components-overview/#dashboard-plugins)
The legacy `gd-dashboard` element doesn't load dashboard plugins. The `gd-dashboard-embed` element does; see [Dashboard plugins](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/embed-custom-elements/index.md#dashboard-plugins). Plugins linked to the dashboard on the server need the `moduleFederationIntegration` property; without it, only the plugins you pass through `extraPlugins` load. If you can provide neither, embed the dashboard with an iframe or the React [`Dashboard`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.dashboard/index.md) component.
### [CSS class name collisions](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/web-components-overview/#css-class-name-collisions)
The script adds a CSS `` to the `` of your page when it loads. The library's CSS class names can, rarely, collide with your own. If that happens, [open a GitHub issue](https://github.com/gooddata/gooddata-ui-sdk/issues/new).
---
# Dashboard and visualization embed elements
> Embed a dashboard or a saved visualization with gd-dashboard-embed and gd-insight-embed, and drive them through properties, methods, and events.
Source: https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/embed-custom-elements/index.md
`gd-dashboard-embed` and `gd-insight-embed` are the recommended custom elements for new integrations. They render the same React components as the legacy `gd-dashboard` and `gd-insight` elements, the [`Dashboard`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.dashboard/index.md) component and [`InsightView`](https://www.gooddata.ai/docs/gooddata-ui/latest/visualisations/insightview/index.md), and add JavaScript properties, methods, lifecycle events, and dashboard plugin loading. The legacy elements stay registered for existing integrations; see the [dashboard](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/dashboard-custom-element/index.md) and [visualization](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/insight-custom-element/index.md) pages.
> **Note:**
> The term 'insight' is an obsolete expression for 'visualizations' but is still employed within the SDK's components and functions.
## [Embed elements compared with the legacy elements](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/embed-custom-elements/#embed-elements-compared-with-the-legacy-elements)
| | `gd-dashboard-embed`, `gd-insight-embed` | `gd-dashboard`, `gd-insight` |
| --- | --- | --- |
| Inputs | Attributes for the initial setup, JavaScript properties for everything after | Attributes only |
| `dashboard` / `insight` identity | Locked after the first render; a change dispatches `gd-error` | Any attribute change re-renders, including the identity |
| Methods | `refresh()`; `replaceFilters()` on the dashboard | None |
| Lifecycle events | `gd-ready`, `gd-error`; `gd-warning` on the dashboard | None; load failures go to `console.error` |
| Dashboard plugins | Loaded, controlled by `pluginMode` | Not loaded |
| Backend and workspace | The shared context, or a per-element `context` property | The shared context and the `workspace` attribute |
## [Minimal example](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/embed-custom-elements/#minimal-example)
```html
```
Load the library and sign the user in as described in the [Web Components overview](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/web-components-overview/index.md) and [Web Components authentication](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/web-components-auth/index.md).
## [How inputs resolve](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/embed-custom-elements/#how-inputs-resolve)
Both elements follow the same rules:
- **Attributes bootstrap, properties drive.** An attribute is read at render time. Once you assign the JavaScript property of the same name, the property wins over the attribute, even when you assign `undefined`.
- **Changes are batched.** Several property assignments or attribute changes in the same task cause one re-render.
- **Identity is immutable.** After the first successful render, `dashboard` (or `insight`) can't change through the attribute or the property. The element dispatches `gd-error` with `phase: "invalidUsage"` and the message `"dashboard" cannot change after first render.`, and keeps rendering the original object. To show a different dashboard or visualization, mount a new element.
- **Context merges field by field.** The `context` property `{ backend, workspaceId?, mapboxToken?, agGridToken? }` overrides the shared context set from the script URL or with [`setContext`](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/web-components-auth/index.md). The workspace resolves as `context.workspaceId`, then the `workspace` attribute, then the shared context.
- **Loading state.** Until a backend is known and the component code has loaded, the element renders the [`LoadingComponent`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.loadingcomponent/index.md) from `@gooddata/sdk-ui`. If either fails, it dispatches `gd-error` with `phase: "init"`.
- **Disconnecting unmounts.** Removing the element from the DOM unmounts its React tree. Reconnecting renders it again with the same, still locked, identity.
## [`gd-dashboard-embed`](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/embed-custom-elements/#gd-dashboard-embed)
Loads the dashboard through the same loader as the [`useDashboardLoader`](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/hooks/use-dashboard-loader/index.md) hook and renders the [`Dashboard`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.dashboard/index.md) component.
### Attributes
| Attribute | Value | Description |
| --- | --- | --- |
| `dashboard` | Dashboard ID | Required unless you set the `dashboard` property. Locked after the first render. |
| `workspace` | Workspace ID | Overrides the workspace of the shared context. |
| `locale` | Locale code such as `en-US` | Sets `config.locale`. Ignored once you assign the `config` property. |
| `readonly` | Boolean attribute | Sets `config.isReadOnly: true`. Ignored once you assign the `config` property. |
| `mapbox` | Mapbox access token | Sets `config.mapboxToken`; overrides `mapboxToken` from the context. Ignored once you assign the `config` property. |
| `agGrid` | AG Grid license key | Sets `config.agGridToken`; overrides `agGridToken` from the context. Ignored once you assign the `config` property. |
### Properties
| Property | Type | Description |
| --- | --- | --- |
| `context` | `{ backend, workspaceId?, mapboxToken?, agGridToken? }` | Per-element backend and workspace. Missing fields fall back to the shared context. |
| `config` | [`DashboardConfig`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.dashboardconfig/index.md) | The complete `config` prop of the [`Dashboard`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.dashboard/index.md) component. Replaces the config built from the attributes and the context tokens, so include `locale`, `isReadOnly`, `mapboxToken`, and `agGridToken` yourself when you need them. |
| `dashboard` | `string` | Dashboard ID. Same identity rule as the attribute. |
| `pluginMode` | `"all" \| "embeddedOnly" \| "backendOnly" \| "disabled"` | Which dashboard plugins load. See [Dashboard plugins](#dashboard-plugins). |
| `extraPlugins` | `IEmbeddedPlugin \| IEmbeddedPlugin[]` | Plugins bundled with your application. |
| `moduleFederationIntegration` | [`ModuleFederationIntegration`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-loaders/sdk-ui-loaders.modulefederationintegration/index.md) | Module Federation runtime needed to load plugins linked to the dashboard on the server. |
### [Dashboard plugins](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/embed-custom-elements/#dashboard-plugins)
Unlike `gd-dashboard`, the embed element loads [dashboard plugins](https://www.gooddata.ai/docs/gooddata-ui/latest/dashboard-plugins/dashboard-plugins/index.md). `pluginMode` selects which ones:
| `pluginMode` | Plugins linked on the server | `extraPlugins` | Needs `moduleFederationIntegration` |
| --- | --- | --- | --- |
| Not set | Loaded when `moduleFederationIntegration` is set; otherwise skipped with a `gd-warning` | Loaded | No |
| `"all"` | Loaded | Loaded | Yes; otherwise `gd-error` with `phase: "init"` and the dashboard doesn't render |
| `"embeddedOnly"` | Skipped; a `gd-warning` is dispatched when the dashboard has any | Loaded | No |
| `"backendOnly"` | Loaded | Ignored, with a `gd-warning` | Yes; otherwise `gd-error` with `phase: "init"` |
| `"disabled"` | Skipped | Ignored, with a `gd-warning` | No |
Set `pluginMode = "disabled"` to keep the no-plugin behavior of `gd-dashboard` without the warning.
### Methods
| Method | Description |
| --- | --- |
| `refresh(): Promise` | Re-initializes the dashboard with the current `config` by dispatching the `initializeDashboard` command. Resolves on `GDC.DASH/EVT.INITIALIZED`; rejects, and dispatches `gd-error` with `phase: "refresh"`, on `GDC.DASH/EVT.COMMAND.FAILED`. |
| `replaceFilters(filters: (IDashboardFilter \| FilterContextItem)[]): Promise` | Replaces the filter selection by dispatching `changeFilterContextSelection(filters, true)`; filters you leave out are reset. Resolves on `GDC.DASH/EVT.FILTER_CONTEXT.CHANGED`; rejects, and dispatches `gd-error` with `phase: "replaceFilters"`, on `GDC.DASH/EVT.COMMAND.FAILED`. This is the Web Components counterpart of the `setFilterContext` postMessage command used with iframe embedding. |
Command rules:
- Call a method only after `gd-ready`. Before that, it rejects with `Dashboard is not ready for commands yet.` and dispatches `gd-error` with `phase: "invalidUsage"` and `command` set to the method name.
- Calling a method again while its previous call is in flight returns the same promise.
- Removing the element, or a reload that recreates the dashboard runtime, rejects in-flight commands with `Dashboard runtime is no longer active.`
### Events
| Event | `detail` | When |
| --- | --- | --- |
| `gd-ready` | `undefined` | The dashboard runtime accepts commands. Fires again whenever the runtime is recreated, for example after you assign a new `config` or `context`. |
| `gd-warning` | `{ phase: "pluginMode", message, pluginMode, ignoredSource: "extraPlugins" \| "backendPlugins", dashboard? }` | Plugins were skipped; see [Dashboard plugins](#dashboard-plugins). The message is also logged with `console.warn`. |
| `gd-error` | `{ phase, message, cause, command?, dashboard? }` | `phase` is `"init"` (dependencies, the context, or the dashboard failed to load), `"update"` (a re-render failed), `"invalidUsage"` (an identity change, or a command before `gd-ready`), `"refresh"`, or `"replaceFilters"` (the command failed). |
| `GDC.DASH/EVT.*` | The event's `payload` | Every [dashboard event](https://www.gooddata.ai/docs/gooddata-ui/latest/dashboard-plugins/dashboard-events/index.md) is forwarded as a DOM event named after its type, for example `GDC.DASH/EVT.INITIALIZED`. |
All events are `CustomEvent` instances that don't bubble and aren't cancelable.
```html
```
## [`gd-insight-embed`](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/embed-custom-elements/#gd-insight-embed)
Renders [`InsightView`](https://www.gooddata.ai/docs/gooddata-ui/latest/visualisations/insightview/index.md).
### Attributes
| Attribute | Value | Description |
| --- | --- | --- |
| `insight` | Visualization ID | Required unless you set the `insight` property. Locked after the first render. |
| `workspace` | Workspace ID | Overrides the workspace of the shared context. |
| `locale` | Locale code such as `en-US` | Locale of the visualization UI. Attribute only; there is no `locale` property. |
| `title` | Boolean attribute or string | Present without a value: shows the title stored with the visualization. With a string: shows that string instead. Absent: no title. |
| `filters` | JSON array of filter objects | Parsed into [`IFilter[]`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.ifilter/index.md) and validated. An invalid value is logged with `console.error` and ignored. |
| `mapbox` | Mapbox access token | Sets `config.mapboxToken`; overrides the context token. Ignored once you assign the `config` property. |
| `agGrid` | AG Grid license key | Sets `config.agGridToken`; overrides the context token. Ignored once you assign the `config` property. |
### Properties
| Property | Type | Description |
| --- | --- | --- |
| `context` | `{ backend, workspaceId?, mapboxToken?, agGridToken? }` | Per-element backend and workspace. Missing fields fall back to the shared context. |
| `config` | The `config` prop of [`InsightView`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-ext/sdk-ui-ext.insightview/index.md) | Replaces the config built from the `mapbox` and `agGrid` attributes and the context tokens. |
| `insight` | `string \| ObjRef` | Visualization ID or reference. Same identity rule as the attribute. |
| `filters` | [`IFilter[]`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.ifilter/index.md) | Filters applied to the visualization. Replaces the `filters` attribute once assigned. |
| `title` | `boolean \| string` | Same meaning as the attribute. |
### Methods
| Method | Description |
| --- | --- |
| `refresh(): Promise` | Evicts the cached definition of this visualization from the bundle's [`InsightView`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-ext/sdk-ui-ext.insightview/index.md) cache and remounts the visualization, so it's fetched again. Resolves when loading finishes (`insightLoaded`, or `loadingChanged` with `isLoading: false`); rejects when the visualization reports `error` or when the cache eviction fails. If the workspace or the `insight` input can't be resolved yet, the eviction is skipped and the visualization is only remounted. Concurrent calls share one promise. |
`refresh()` runs after the element has already rendered, so a stale visualization is briefly visible and fetched twice. When you control the mount timing, for example after a user edits a visualization and returns to a page of embeds, call [`clearCaches()`](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/web-components-overview/index.md#module-exports) and await it before mounting the elements instead.
### Events
| Event | `detail` | When |
| --- | --- | --- |
| `drill` | [`IDrillEvent`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.idrillevent/index.md) | The user drills in the visualization. |
| `error` | [`GoodDataSdkError`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.gooddatasdkerror/index.md) | Loading or computing the visualization failed. `gd-error` fires too. |
| `exportReady` | [`IExportFunction`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexportfunction/index.md) | The export function is available. |
| `loadingChanged` | `ILoadingState` | Loading started or finished. |
| `insightLoaded` | [`IInsight`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.iinsight/index.md) | The visualization definition has loaded. |
| `gd-ready` | `undefined` | Once, after the first successful render. |
| `gd-error` | `{ phase, message, cause, insight? }` | `phase` is `"init"`, `"update"` (the visualization reported an error; `insight` holds its ID), or `"invalidUsage"`. |
All events are `CustomEvent` instances that don't bubble and aren't cancelable.
```html
```
## [Migrate from `gd-dashboard` and `gd-insight`](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/embed-custom-elements/#migrate-from-gd-dashboard-and-gd-insight)
1. Rename the tags. The attributes are the same (`dashboard`, `workspace`, `locale`, `readonly`, `mapbox`, `agGrid`; `insight`, `workspace`, `locale`, `title`, `filters`, `mapbox`, `agGrid`), and existing listeners for `GDC.DASH/EVT.*`, `drill`, `error`, `exportReady`, `loadingChanged`, and `insightLoaded` keep working.
2. Add CSS. Give the embed elements `display: block` or `display: flex` and a height in your own stylesheet.
3. Stop switching the `dashboard` or `insight` attribute to show another object. Replace the element instead; the embed elements reject identity changes with `gd-error`.
4. Move runtime updates from attributes to properties: `el.filters = [...]`, `el.title = "..."`, `el.config = {...}`, and `await el.replaceFilters([...])` for dashboard filters.
5. Listen for `gd-error`. The legacy elements only log load failures to the console.
6. Decide on plugins. Without `moduleFederationIntegration`, `gd-dashboard-embed` warns that plugins linked on the server were skipped. Set `pluginMode = "disabled"` to keep the legacy behavior without the warning, or provide `moduleFederationIntegration` to load them.
---
# Dashboard custom element
> Embed a dashboard with gd-dashboard, configure its workspace, locale, and read-only mode, and subscribe to dashboard events.
Source: https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/dashboard-custom-element/index.md
> **Legacy element:**
> `gd-dashboard` is the legacy dashboard element, kept for existing integrations. For new integrations, use `gd-dashboard-embed`, which adds JavaScript properties, the `refresh()` and `replaceFilters()` methods, dashboard plugin loading, and the `gd-ready` and `gd-error` events. See [Dashboard and visualization embed elements](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/embed-custom-elements/index.md).
`gd-dashboard` embeds a GoodData dashboard. It renders the [[`Dashboard`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.dashboard/index.md) component](https://www.gooddata.ai/docs/gooddata-ui/latest/dashboard-plugins/dashboard/index.md):
```html
```
## [Supported attributes](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/dashboard-custom-element/#supported-attributes)
```html
```
- `dashboard` - required, the ID of the dashboard to embed.
- `workspace` - optional, the ID of the workspace for this dashboard. By default, it's taken from the context, for example from the script URL.
- `locale` - optional, defaults to `en-US`. The localization of the dashboard UI. Use the hyphenated form (`en-US`, `de-DE`); an unknown value falls back to `en-US`. For all available languages, see [the full list of available localizations][1].
- `readonly` - optional. If enabled, the dashboard is embedded in read-only mode and all user interaction that would alter any backend state is disabled (for example, creating or changing alerts and scheduled emails).
- `mapbox` - optional, a Mapbox access token used by geo charts on the dashboard. Overrides the `mapboxToken` from the context.
- `agGrid` - optional, an AG Grid license key used by pivot tables on the dashboard. Overrides the `agGridToken` from the context.
You can also set the workspace ID once on the context instead of passing it to every element. See the code example in [Web Components authentication][2].
> **Note:**
> The locale affects only the UI elements, not your data or the metadata language.
## [Supported events](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/dashboard-custom-element/#supported-events)
`gd-dashboard` forwards every event the [`Dashboard`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.dashboard/index.md) component emits as a DOM event named after the event type (see [`DashboardEventType`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.dashboardeventtype/index.md)), for example `GDC.DASH/EVT.INITIALIZED`.
Events don't bubble and aren't cancelable. Subscribe to them as to any other DOM event:
```html
```
[1]: https://github.com/gooddata/gooddata-ui-sdk/blob/master/libs/sdk-model/src/base/localization.ts
[2]: ../web-components-auth/
---
# Visualization custom element
> Embed a saved visualization with the legacy gd-insight element, set its workspace, locale, title, filters, and size, and subscribe to its events.
Source: https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/insight-custom-element/index.md
> **Legacy element:**
> `gd-insight` is the legacy visualization element, kept for existing integrations. For new integrations, use `gd-insight-embed`, which adds the `filters`, `title`, `config`, and `context` properties, the `refresh()` method, and the `gd-ready` and `gd-error` events. See [Dashboard and visualization embed elements](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/embed-custom-elements/index.md).
`gd-insight` embeds a single saved visualization. It renders the [`InsightView`](https://www.gooddata.ai/docs/gooddata-ui/latest/visualisations/insightview/index.md) component:
```html
```
> **Give the element a height:**
> The `gd-insight` element uses a flex layout that adjusts to the size of its container. If the container doesn't have `display: flex`, the element has zero height. You can also set the height explicitly with CSS, for example with the inline `style="height: 500px"`.
> **Note:**
> The term 'insight' is an obsolete expression for 'visualizations' but is still employed within the SDK's components and functions.
## [Supported attributes](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/insight-custom-element/#supported-attributes)
```html
```
- `insight` - required, the ID of the visualization to embed.
- `workspace` - optional, the ID of the workspace of this visualization. By default, it's taken from the context, for example from the script URL.
- `locale` - optional, defaults to `en-US`. The localization of the visualization UI. Use the hyphenated form (`en-US`, `de-DE`); an unknown value falls back to `en-US`. For all available languages, see [the full list of available localizations][1].
- `title` - optional. As a boolean attribute, it renders the title stored with the visualization. As a string, it renders that string instead.
- `filters` - optional, a JSON array of filter objects applied to the visualization. An invalid value is logged with `console.error` and ignored.
- `mapbox` - optional, a Mapbox access token used by geo charts. Overrides the `mapboxToken` from the context.
- `agGrid` - optional, an AG Grid license key used by pivot tables. Overrides the `agGridToken` from the context.
```html
```
You can also set the workspace ID once on the context instead of passing it to every element. See the code example in [Web Components authentication][2].
> **Note:**
> The locale affects only the UI elements, not your data or the metadata language.
## [Supported events](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/insight-custom-element/#supported-events)
`gd-insight` emits the following events. The `detail` of each event is the argument of the matching [[`InsightView`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-ext/sdk-ui-ext.insightview/index.md) callback][3]:
- `drill` - the user drilled in the visualization. The detail is the drill event, [`IDrillEvent`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.idrillevent/index.md).
- `error` - loading or computing the visualization failed. The detail is the [`GoodDataSdkError`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.gooddatasdkerror/index.md).
- `exportReady` - the visualization is ready to be exported. The detail is the export function, [`IExportFunction`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexportfunction/index.md); call it to export the data.
- `loadingChanged` - the loading state of the visualization changed. The detail is `ILoadingState`.
- `insightLoaded` - the visualization definition has loaded. The detail is the [`IInsight`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.iinsight/index.md).
Events don't bubble and aren't cancelable. Subscribe to them as to any other DOM event:
```html
```
[1]: https://github.com/gooddata/gooddata-ui-sdk/blob/master/libs/sdk-model/src/base/localization.ts
[2]: ../web-components-auth/
[3]: ../../../visualisations/insightview/#props
---
# AI Assistant custom element
> Embed the AI Assistant with gd-ai-assistant, set its workspace and locale, subscribe to its chat events, and compose the chat from several elements.
Source: https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/ai-assistant-custom-element/index.md
`gd-ai-assistant` embeds the GoodData AI Assistant. It renders the [`GenAIAssistant`](https://www.gooddata.ai/docs/gooddata-ui/latest/ai-modules/ai-assistant/index.md) component:
```html
```
## [Supported attributes](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/ai-assistant-custom-element/#supported-attributes)
```html
```
- `workspace` - optional, the ID of the workspace for this AI Assistant. By default, it's taken from the context, for example from the script URL.
- `locale` - optional, defaults to `en-US`. The localization of the AI Assistant interface. For all available languages, see [the full list of available localizations][1].
- `objectTypes` - optional, a JSON array of metadata object types that the assistant searches and suggests, for example `'["dashboard","visualization"]'`. Valid values are `dataset`, `attribute`, `label`, `fact`, `date`, `metric`, `visualization`, and `dashboard` (see [`GenAIObjectType`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.genaiobjecttype/index.md)). If omitted, the assistant uses its default set of object types.
You can also set the workspace ID once on the context instead of passing it to every element. See the code example in [Web Components authentication][2].
> **Note:**
> The locale affects only the UI elements, not your data or the metadata language.
## [Supported events](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/ai-assistant-custom-element/#supported-events)
`gd-ai-assistant` emits `linkClick` and forwards every chat event of the [`GenAIAssistant`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.genaiassistant/index.md) component (see [`ChatEvent`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.chatevent/index.md)) as a DOM event named after the event type. The most common ones are:
- `linkClick` - when a user clicks on a link in the chat.
- `chatOpened` / `chatClosed` - when the chat is opened or closed.
- `chatReset` - when the chat is reset.
- `chatUserMessage` - when a user message is added to the chat.
- `chatAssistantMessage` - when an assistant message is added to the chat.
- `chatFeedback` - when a user provides feedback on the assistant message.
- `chatVisualizationError` - when an error occurs while rendering the visualization in the chat.
- `chatSaveVisualizationSuccess` / `chatSaveVisualizationError` - when saving a visualization from the chat succeeds or fails.
- `chatCopyToClipboard` - when a user copies content to the clipboard.
Events **do not bubble** and **are not cancelable**. Here is how you can subscribe to one from your code:
```html
```
## [Compose the chat from several elements](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/ai-assistant-custom-element/#compose-the-chat-from-several-elements)
The library registers three more elements that share the AI Assistant's code:
| Element | Renders | Use it to |
| --- | --- | --- |
| `gd-ai-chat` | The same [`GenAIAssistant`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.genaiassistant/index.md) component as `gd-ai-assistant` | Alias of `gd-ai-assistant`; the two tags behave identically. |
| `gd-ai-conversations` | The [`GenAIConversations`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.genaiconversations/index.md) component: the list of the user's conversations | Show the conversation list separately from the chat. Selecting a conversation makes it the current one in the shared store. |
| `gd-ai-provider` | Nothing visible; it owns the chat store | Make the `gd-ai-assistant`, `gd-ai-chat`, and `gd-ai-conversations` elements placed inside it share one conversation state. |
`gd-ai-chat` and `gd-ai-conversations` support the same `workspace`, `locale`, and `objectTypes` attributes as `gd-ai-assistant` and emit the same events.
### [Share one store with `gd-ai-provider`](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/ai-assistant-custom-element/#share-one-store-with-gd-ai-provider)
Wrap the chat and the conversation list in `gd-ai-provider`. When the provider connects and the shared context is available, it creates the chat store, and every `gd-ai-assistant`, `gd-ai-chat`, or `gd-ai-conversations` element inside it connects to that store instead of creating its own:
```html
```
| Attribute | Description |
| --- | --- |
| `workspace`, `locale`, `objectTypes` | Applied to the shared store. Same values as on `gd-ai-assistant`. |
| `store` | Optional ID of the store. The provider generates one when the attribute is absent. Child elements look up the nearest ancestor with a `store` attribute, so the provider doesn't have to be their direct parent. |
The provider reads its attributes once, when it connects; changing them later has no effect. The provider itself dispatches no DOM events; listen on the `gd-ai-assistant` and `gd-ai-conversations` elements.
### [JavaScript properties and methods](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/ai-assistant-custom-element/#javascript-properties-and-methods)
`gd-ai-assistant`, `gd-ai-chat`, `gd-ai-conversations`, and `gd-ai-provider` expose these JavaScript properties. Assign them after the element is defined, for example after `await customElements.whenDefined("gd-ai-provider")`.
| Property or method | Description |
| --- | --- |
| `onLinkClick` | Callback invoked when the user clicks a link in the chat, with a `CustomEvent` whose `detail` is the `linkClick` payload described below. The element always suppresses the chat's own navigation and dispatches the `linkClick` event before it calls the callback. |
| `onDispatcher` | Callback that receives the store's `dispatch` function once the store exists. Use it to dispatch the actions exported by `@gooddata/sdk-ui-gen-ai`. |
| `startNewConversationAction()` | Dispatches the start-new-conversation action to the store. The method is attached asynchronously after the element connects, so guard early calls with `?.`. |
On `gd-ai-provider`, assigning `onLinkClick` or `onDispatcher` forwards the callback to the shared store, and `startNewConversationAction()` acts on the shared store.
```html
```
The `linkClick` event `detail` carries `type` (the linked object type, `"setting"`, or `"report"`), `id`, `workspaceId`, `itemUrl`, `newTab`, and `action` (`"open"` or `"copy"`), and, depending on the link, `section`, `dashboard`, `insights`, `dashboardStatus`, `visualization`, and `visualizationStatus`.
[1]: https://github.com/gooddata/gooddata-ui-sdk/blob/master/libs/sdk-model/src/base/localization.ts
[2]: ../web-components-auth/
---
# Authenticate Web Components
> Authenticate Web Components against GoodData using the auth=sso script parameter for automatic SSO or setContext for a programmatic flow.
Source: https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/web-components-auth/index.md
The Web Components library can sign the user in to GoodData automatically when you add the `auth` query parameter to the script URL. For more control over the flow, [authenticate the user programmatically](#programmatic-authentication) instead.
The only supported value of the `auth` parameter is `sso`. With it, the script checks whether the user is signed in and, if not, redirects the user to the sign-in page of your identity provider. See [Automatic authentication](#automatic-authentication).
Without the `auth` parameter, or with any other value, the library doesn't sign the user in and expects you to set up [programmatic authentication](#programmatic-authentication).
Until you call `setContext`, the custom elements on the page render nothing or a loading indicator, and after five seconds the library logs a console warning that no authentication context was provided.
> **Note:**
> All your users must have a GoodData account and have access to your GoodData workspace.
## [Programmatic authentication](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/web-components-auth/#programmatic-authentication)
To customize the authentication flow, create the authenticated backend yourself. Next to the library, your GoodData instance serves `tigerBackend.js`, which exports the backend factory for GoodData Cloud and GoodData.CN (code name `tiger`).
A custom authentication setup looks like this:
```html
```
See [Authenticate to the backend](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/authentication/index.md) for the other provider options, including a JWT from your own portal and API tokens (development only). `tigerBackend.js` exports everything from `@gooddata/sdk-backend-tiger`, so every provider on that page is available here.
The `gd-dashboard-embed` and `gd-insight-embed` elements also accept a per-element `context` property with the same `{ backend, workspaceId }` shape, which overrides the shared context for that element only. See [Dashboard and visualization embed elements](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/embed-custom-elements/index.md#how-inputs-resolve).
## [Automatic authentication](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/web-components-auth/#automatic-authentication)
Add the `?auth=sso` parameter to the script URL to sign users in automatically on GoodData Cloud and GoodData.CN:
```html
```
This is equivalent to the following programmatic setup:
```html
```
Whenever the user isn't signed in to GoodData, the library redirects the browser window to the identity provider configured in GoodData. After the user signs in, the identity provider redirects the window back to the page the user started on.
If your organization uses Federated Identity Management, pass the user's identity provider ID to the redirect: replace `redirectToTigerAuthentication` with the handler that `createRedirectToTigerAuthenticationWithParams({ externalProviderId })` returns, imported from the same `tigerBackend.js`. See [Pick the identity provider](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/authentication/index.md#pick-the-identity-provider).
---
# Framework guides
> Use GoodData.UI in Angular, Next.js, and Vue apps — framework-specific setup via React components or the Web Components wrapper.
Source: https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/framework-integrations/index.md
GoodData.UI ships as React components, but you don't need a React app to use it. These guides add GoodData to other frameworks, either by wrapping the React components or by embedding the framework-agnostic [Web Components](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/web-components/web-components-overview/index.md).
Any JavaScript or TypeScript framework can embed GoodData through Web Components. For SvelteKit, see the [frontend integration series blog post](https://www.gooddata.ai/blog/frontend-integration-series-sveltekit/).
---
# Embed GoodData in an Angular app
> Embed GoodData dashboards, visualizations, and the AI Assistant in an Angular app with the Web Components library, custom element schemas, and event listeners.
Source: https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/framework-integrations/angular-integration/index.md
Angular works well with Web Components and custom elements. This guide embeds a GoodData dashboard, a visualization, and the AI Assistant in an Angular app with the `gd-dashboard-embed`, `gd-insight-embed`, and `gd-ai-assistant` custom elements. It's based on a project generated with `ng new my-app`, with standalone components; adapt the file names to your project.
## [Load the Web Components library](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/framework-integrations/angular-integration/#load-the-web-components-library)
Add a `