Component Options
Look up element attributes
Every attribute of dbn-dashboard and dbn-metric, with its type, default and effect.
Load the elements once with import '@databrainhq/plugin/web';. Then use the attributes below.
How values are passed
| Type | In HTML | In JavaScript |
|---|---|---|
| string | dashboard-id="abc" | el.dashboardId = 'abc' |
| number | height="400" | el.height = 400 |
| boolean | enable-download-csv="true" (a bare attribute stays off) | el.enableDownloadCsv = true |
| json | options='{"a":true}' (a JSON string) | el.options = { a: true } |
| function | Not possible | el.handleServerEvent = (e) => onEvent(e) |
HTML attributes are kebab case. JavaScript properties are camel case.
- Write a boolean attribute with a value:
enable-download-csv="true". A bareenable-download-csvstays off. - A function can only be set as a property. Assign an inline arrow function:
el.handleServerEvent = (e) => onEvent(e). A named function assigned directly (el.handleServerEvent = onEvent) is dropped.
To show another dashboard, remove the element and add a new one. The element does not load a new dashboard when you change its props.
dbn-dashboard
| Attribute | Property | Type | Default | What it does |
|---|---|---|---|---|
token | token | string | required | The guest token from your backend. |
dashboard-id | dashboardId | string | none | The dashboard to show. Copy it from the Embeds page. |
options | options | json | {} | Viewer actions, layout and URL state. See Set dashboard options. |
theme | theme | json | none | Inline theme object. |
theme-name | themeName | string | none | Name of a saved theme. |
admin-theme-options | adminThemeOptions | json | none | Admin theme fields. With theme-name, they merge onto the named theme field by field. |
color-scheme | colorScheme | string | theme mode, then light | light, dark, system (follows the OS, live) or theme. |
enable-theme-contrast-warnings | enableThemeContrastWarnings | boolean | false | Logs one console warning per theme whose colors fail contrast checks. |
is-hide-chart-settings | isHideChartSettings | boolean | false | Hides chart settings in full screen. |
is-hide-table-preview | isHideTablePreview | boolean | false | Hides the table preview in full screen. |
is-sticky-dashboard-filters | isStickyDashboardFilters | boolean | false | Keeps dashboard filters at the top while the viewer scrolls. |
enable-download-csv | enableDownloadCsv | boolean | false | Shows CSV download on cards. |
enable-email-csv | enableEmailCsv | boolean | false | Shows email CSV on cards. |
disable-download-png | disableDownloadPng | boolean | false | Hides PNG download. |
enable-download-all-metrics | enableDownloadAllMetrics | boolean | false | Shows download all metrics in the dashboard menu. |
enable-download-all-pdf | enableDownloadAllPdf | boolean | false | Shows download as PDF in the dashboard menu. |
enable-multi-metric-filters | enableMultiMetricFilters | boolean | false | Allows more than one metric filter on a card. |
disable-fullscreen | disableFullscreen | boolean | false | Hides full screen on cards. |
enable-title-click-fullscreen | enableTitleClickFullscreen | boolean | false | Opens full screen when the viewer selects a card title. |
enable-adhoc-drill | enableAdhocDrill | boolean | false | Drill into any field. v2 cards only. See Drill and cross-filter switches. |
enable-exclude-filter | enableExcludeFilter | boolean | false | Adds “Exclude” to the data point menu. v2 cards only. |
enable-cross-filter | enableCrossFilter | boolean | false | A chart click filters the other cards. v2 cards only. |
enable-chart-dashboard-navigation | enableChartDashboardNavigation | boolean | false | A chart click with a saved dashboard destination calls chartClickFunction. |
| none | chartClickFunction | function | none | Called on a chart click. See chartClickFunction payloads. |
| none | filterStateFunction | function | none | Called with the applied filters on every filter change. See Filter state. |
| none | handleServerEvent | function | none | Called on embed events. See Server events. |
global-filter-options | globalFilterOptions | json | none | Default values and choices for dashboard filters. See Filter state. |
hide-dashboard-filters | hideDashboardFilters | json | none | Names of dashboard filters to hide, as a string array. |
calendar-type | calendarType | string | default | default or ind. ind makes date presets use the fiscal year. |
custom-chart-settings | customChartSettings | json | none | Defaults and edit rights for chart settings in metric creation. |
chart-columns | chartColumns | json | none | Per metric: [{ "metricId", "dimensions", "measures", "isEnabled" }]. |
long-description-config | longDescriptionConfig | json | none | { "width", "fontColor" } for the long description popover. |
options-icon | optionsIcon | string | kebab-menu-vertical | Card menu icon: kebab-menu-vertical or download. |
settings-icon | settingsIcon | json | none | { "name", "ariaLabel", "iconSvg", "menuPosition" } for the dashboard settings button. |
| none | manageMetricsBtnContent | function | none | Content for the manage metrics button. |
no-data-img | noDataImg | string | none | Image URL for an empty card. |
no-data-found-svg | noDataFoundSvg | string | none | SVG markup for the “No Data” screen. |
custom-messages | customMessages | json | none | Your own text for token and empty states. See Custom messages and support. |
| none | onSupportClick | function | none | Adds a support button to the crash screen. |
support-label | supportLabel | string | Get help | Label of that support button. |
language | language | string | none | Language code to show. See Translate. |
translation-dictionary | translationDictionary | json | none | Your own translations. |
config-id | configId | string | ?configId= in the page URL | Data app configuration id. Set it when two embeds share a page. |
ui-version | uiVersion | string | legacy | v2 loads the v2 design. See Turn on the v2 embed design. |
embed-flags | embedFlags | json | {} | Which parts of the v2 design to turn on. |
data-dbn-ui | dataDbnUi | string | none | v2 turns on the v2 chart engine. |
base-url | baseUrl | string | https://api.usedatabrain.com | Backend origin. See base-url. |
debug | debug | string | off | 1, true, yes or on writes [DBN Debug] logs to the console. |
dbn-metric
| Attribute | Property | Type | Default | What it does |
|---|---|---|---|---|
token | token | string | required | The guest token from your backend. |
metric-id | metricId | string | required | The metric to show. Copy it from the Embeds page. |
variant | variant | string | card | card (full screen included) or fullscreen. |
width | width | number | none | Card width in pixels. |
height | height | number | none | Card height in pixels. |
class-name | className | string | "" | CSS class on the card. |
style | style | json | none | Inline CSS object. |
chart-renderer-type | chartRendererType | string | canvas | canvas or svg. |
chart-colors | chartColors | json | theme colors | Series colors, as a string array. |
chart-appearance | chartAppearance | json | none | Chart appearance fields. |
appearance-options | appearanceOptions | json | none | appearanceOptionsPosition, dynamicBehaviour, cumulativeBar, stackedBars. |
theme | theme | json | none | Inline theme object. |
theme-name | themeName | string | none | Name of a saved theme. |
color-scheme | colorScheme | string | theme mode, then light | light, dark, system or theme. |
enable-theme-contrast-warnings | enableThemeContrastWarnings | boolean | false | Logs theme contrast warnings. |
metric-filter-options | metricFilterOptions | string | none | Choices for the metric filters, as a JSON string. |
metric-filter-position | metricFilterPosition | string | outside | outside or inside the card. |
enable-multi-metric-filters | enableMultiMetricFilters | boolean | false | Allows more than one metric filter on the card. |
global-filter-options | globalFilterOptions | json | none | Default filter values. |
hide-date-picker-options | hideDatePickerOptions | json | none | Date presets to hide, by label. |
calendar-type | calendarType | string | default | default or ind (fiscal year). |
is-hide-chart-settings | isHideChartSettings | boolean | false | Hides chart settings in full screen. |
is-hide-table-preview | isHideTablePreview | boolean | false | Hides the table preview in full screen. |
is-disable-card-title | isDisableCardTitle | boolean | false | Hides the card title. |
is-merged-card | isMergedCard | boolean | false | Shows the metric as a merged card. |
hide-metric-card-shadow | hideMetricCardShadow | boolean | false | Removes the card shadow. |
disable-metric-card-border | disableMetricCardBorder | boolean | false | Removes the card border. |
enable-download-csv | enableDownloadCsv | boolean | false | Shows CSV download. |
enable-email-csv | enableEmailCsv | boolean | false | Shows email CSV. |
disable-download-png | disableDownloadPng | boolean | false | Hides PNG download. |
disable-fullscreen | disableFullscreen | boolean | false | Hides full screen. |
enable-title-click-fullscreen | enableTitleClickFullscreen | boolean | false | Opens full screen when the viewer selects the title. |
disable-underlying-data | disableUnderlyingData | boolean | false | Hides underlying data. |
disable-download-data-no-filters | disableDownloadDataNoFilters | boolean | false | Blocks a data download while no filter is applied. |
disable-download-underlying-data-no-filters | disableDownloadUnderlyingDataNoFilters | boolean | false | Blocks an underlying data download while no filter is applied. |
chart-columns | chartColumns | json | none | { "dimensions", "measures", "isEnabled" }. |
long-description-config | longDescriptionConfig | json | none | { "width", "fontColor" }. |
options-icon | optionsIcon | string | kebab-menu-vertical | kebab-menu-vertical or download. |
no-data-img | noDataImg | string | none | Image URL for an empty card. |
custom-messages | customMessages | json | none | Your own text for token and empty states. |
| none | onSupportClick | function | none | Adds a support button to the crash screen. |
support-label | supportLabel | string | Get help | Label of that support button. |
| none | onMinimize | function | none | Called when the viewer selects minimize. |
language | language | string | none | Language code to show. |
translation-dictionary | translationDictionary | json | none | Your own translations. |
data-dbn-ui | dataDbnUi | string | none | v2 turns on the v2 chart engine. |
base-url | baseUrl | string | https://api.usedatabrain.com | Backend origin. |
debug | debug | string | off | 1, true, yes or on writes debug logs. |
<dbn-metric> has no options, ui-version or embed-flags. The v2 design is for <dbn-dashboard> only.
Drill and cross-filter switches
All four are off until you set them.
| Attribute | Needs | What it does |
|---|---|---|
enable-adhoc-drill | ui-version="v2" and the embed_ui_v2_metric_cards flag | The viewer can drill into any field of a chart. |
enable-cross-filter | ui-version="v2" and the embed_ui_v2_metric_cards flag | A chart click filters the other cards. A metric with cross filtering turned on in its saved settings also publishes. |
enable-exclude-filter | v2 cards | Adds “Exclude <value>” to the data point menu. Test it on your data first: if your query path ignores the negative operator, Exclude acts like Only. |
enable-chart-dashboard-navigation | chartClickFunction | A click on a chart with a saved dashboard destination calls chartClickFunction. Works on the current and the v2 cards. |
The Embed dialog’s v2 snippet already adds enable-adhoc-drill="true" and enable-cross-filter="true".
chartClickFunction payloads
chartClickFunction gets one of two payloads. Check payload.kind first.
| Payload | When | Shape |
|---|---|---|
| A bare value | The metric’s click action sends a value to your app | The clicked value |
kind: "dashboard" | enable-chart-dashboard-navigation is on and the chart has a dashboard destination | { kind, dashboardId, embedDashboardId, filters, globalFilterOptions, openInNewTab, path } |
el.chartClickFunction = (payload) => {
if (payload?.kind !== 'dashboard') return; // a bare value from a click action
mountDashboard(payload.embedDashboardId, payload.globalFilterOptions);
};- The embed never moves your page. You mount a new
<dbn-dashboard>with the id and filters. - The server checks every destination against the current guest token first. A destination the token cannot open does nothing.
filtersis[{ column, value }]. PassglobalFilterOptionsto the new element as it is.pathis a ready query string. It is not a route in your app.
Custom messages and support
custom-messages keys:
| Key | Replaces |
|---|---|
tokenExpiry | “Your access has expired. Ask for a new link.” |
tokenAbsent | “This link is incomplete. Ask the person who shared it for a new link.” |
emptyCard | “No data to show.” (or “No data for these filters.” when a filter is set) |
emptyMetricList | “No metrics yet.” |
<dbn-dashboard
token="GUEST_TOKEN"
dashboard-id="DASHBOARD_ID"
custom-messages='{"tokenExpiry":"Your session ended. Refresh the page."}'
support-label="Contact support"
></dbn-dashboard>
<script>
document.querySelector('dbn-dashboard').onSupportClick = () => openHelpWidget();
</script>The crash screen shows Try Again. With onSupportClick set, it also shows your support button. support-label does nothing without onSupportClick.
Console warnings
The elements write these to the browser console:
| Message | Cause |
|---|---|
dbn-dashboard: no dashboard-id was set. Use the dashboard id from the Embeds page. | No id. dbn-metric says the same for metric-id. |
dbn-dashboard: dashboard-id "..." looks like a name, not an id. Use the dashboard id from the Embeds page. | The id has a space in it. |
[databrain] <dbn-dashboard> "token" must be a string, got ... | token, dashboardId, metricId or themeName is not a string. |
[databrain] <dbn-dashboard> "options" must be a JSON object, got ... The value is ignored. | options, theme, customMessages or adminThemeOptions is not an object. |
[databrain] <dbn-dashboard> "colorScheme" must be one of light, dark, system, theme, got ... The value is ignored. | A wrong color scheme. |
dashboardId="..." written in HTML becomes the attribute dashboardid. The element accepts it, and metricid for <dbn-metric>. If you set both spellings, dashboard-id wins.
base-url
base-url points the embed at another backend origin, for example a self-hosted one. It must be an absolute http or https URL. Without it, the embed uses https://api.usedatabrain.com.
- The origin is page wide. If two elements ask for different origins, the last one wins for both, and the console warns.
window.dbn.proxyAuthUrlandwindow.dbn.baseUrlwin overbase-url.
Next: Set dashboard options.