# 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](embed-a-dashboard.md).

## 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:

```html
<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/embed-sdk.md) 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](../build-dashboards/themes.md).

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.

```js
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:

```js
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`:

```html
<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`:

```json
{ "tenantId": "acme", "permissions": { "drill": false, "rows": false, "export": false } }
```

| Permission | Set to `false`, it turns off |
|---|---|
| `drill` | Drill down. |
| `rows` | Show the rows, and Download CSV. |
| `export` | Download 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:

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