Skip to main content

Embed in your product

Embed options

Themes, initial filters, and turning actions off.

This page covers the options that change how an embedded dashboard looks and what viewers can do: themes, the light or dark appearance, filters set on load, loading on scroll, and turning actions off. For the snippet itself, see Embed a dashboard.

Place a dashboard from your own code​

The snippet from Publish & share uses the qc-embed-view element. You can also mount a dashboard from your own code:

<script src="https://analytics.example.com/embed/qc-embed.js"></script>
<div id="sales"></div>
<script>
const view = QcEmbed.mount('#sales', {
dashboardId: 'dash_abc',
tokenProvider: () => fetch('/my-backend/embed-token').then((r) => r.text()),
themeId: 'default-dark',
});
// Later, to remove it: view.destroy();
</script>

Each option below works with either. On the element, options without an attribute are set as properties in your script, such as view.theme = 'dark'. The full list is in the Embed SDK reference.

Themes​

A dashboard wears the first of these that applies:

  1. A theme named in the viewer token (themeId in the token request).
  2. A theme named on the page: the theme-id attribute, or the themeId option.
  3. The dashboard's own theme, chosen by its author.
  4. Default Light, or Default Dark when the appearance is dark.

default-light and default-dark are always available. A custom theme's id is shown in the builder's theme editor, under Theme ID. See Themes.

A theme that cannot be used, such as an unknown or deleted id, is skipped, and the next one in the list applies. In the token request, GOAT still issues the token and adds a THEME_DROPPED warning.

Use the token when the theme depends on the customer, such as each customer's brand. Use the page when it depends on the page.

Light and dark appearance​

The theme option, 'light' or 'dark', sets the appearance of the embed's own controls, such as menus and the filter bar. Light is the default. A dashboard whose author left it on Follow app wears Default Light in light and Default Dark in dark.

QcEmbed.mount('#sales', { dashboardId: 'dash_abc', tokenProvider, theme: 'dark' });
// or, on the element:
document.querySelector('qc-embed-view').theme = 'dark';

Filters set on load​

The filters option, or the element's filters property, opens the dashboard with filters already set, keyed by the filter's id:

QcEmbed.mount('#sales', {
dashboardId: 'dash_abc',
tokenProvider,
filters: {
flt_region: { values: ['West', 'East'] },
flt_amount: { range: { from: 100, to: 500 } },
flt_date: { preset: 'LAST_30_DAYS' },
},
});

This is for convenience, not security: a viewer can change an open filter. To limit what a customer sees, use the tenant key.

Loading on scroll​

Charts load their data when they come within about 200 pixels of the visible area, and images load as they scroll in. To load everything at once, add eager:

<qc-embed-view base-url="https://analytics.example.com" dashboard-id="dash_abc" eager></qc-embed-view>

or eager: true with QcEmbed.mount.

Turn actions off​

The viewer token can turn chart actions off, for one viewer or one customer. Add permissions to the token request, with each action you want off set to false:

{ "tenantId": "acme", "permissions": { "drill": false, "rows": false, "export": false } }
PermissionSet to false, it turns off
drillDrill down.
rowsShow the rows, and Download CSV.
exportDownload CSV.

The dashboard does not offer an action that is off, and GOAT refuses it if asked directly. Leave permissions out, or send {}, to keep everything the dashboard's author allowed. A permission cannot turn on an action the author left off.

Clicks on charts​

The element sends an actionclick event when a viewer clicks a chart action, such as a filter, a link, or Go to. Your page can listen for it, and call preventDefault() to stop the action, for example to open the link in your own way:

document.querySelector('qc-embed-view').addEventListener('actionclick', (e) => {
if (e.detail.kind === 'link') {
e.preventDefault();
window.open(e.detail.target.url, '_blank', 'noopener');
}
});

Several dashboards on one page​

Paste one snippet per dashboard. Each finds its own element and keeps its own session.

GOAT documentation

Type to search.