Dashboard and visualization embed elements

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 component and InsightView, and add JavaScript properties, methods, lifecycle events, and dashboard plugin loading. The legacy elements stay registered for existing integrations; see the dashboard and visualization pages.

Embed elements compared with the legacy elements

Minimal example

<script type="module" src="https://example.gooddata.com/components/my-workspace-id.js?auth=sso"></script>

<gd-dashboard-embed dashboard="my-dashboard-id"></gd-dashboard-embed>

<gd-insight-embed insight="my-visualization-id" title style="display: block; height: 500px"></gd-insight-embed>

Load the library and sign the user in as described in the Web Components overview and Web Components authentication.

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. 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 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

Loads the dashboard through the same loader as the useDashboardLoader hook and renders the Dashboard component.

Attributes

Properties

Dashboard plugins

Unlike gd-dashboard, the embed element loads dashboard plugins. pluginMode selects which ones:

Set pluginMode = "disabled" to keep the no-plugin behavior of gd-dashboard without the warning.

Methods

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

All events are CustomEvent instances that don’t bubble and aren’t cancelable.

<gd-dashboard-embed dashboard="my-dashboard-id" id="dashboard"></gd-dashboard-embed>
<script type="module">
    const dashboardEl = document.getElementById("dashboard");

    dashboardEl.addEventListener("gd-error", (event) => {
        console.error(event.detail.phase, event.detail.message);
    });

    dashboardEl.addEventListener(
        "gd-ready",
        async () => {
            await dashboardEl.replaceFilters([
                {
                    positiveAttributeFilter: {
                        displayForm: { identifier: "region" },
                        in: { values: ["West Coast"] },
                    },
                },
            ]);
        },
        { once: true },
    );
</script>

gd-insight-embed

Renders InsightView.

Attributes

Properties

Methods

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() and await it before mounting the elements instead.

Events

All events are CustomEvent instances that don’t bubble and aren’t cancelable.

<gd-insight-embed insight="my-visualization-id" id="visualization" style="display: block; height: 500px"></gd-insight-embed>
<script type="module">
    const insightEl = document.getElementById("visualization");

    insightEl.addEventListener("insightLoaded", (event) => {
        console.log(event.detail);
    });

    insightEl.filters = [
        {
            positiveAttributeFilter: {
                displayForm: { identifier: "region" },
                in: { values: ["West Coast"] },
            },
        },
    ];
    insightEl.title = "Revenue by region";
</script>

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.