Skip to Content

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

TypeIn HTMLIn JavaScript
stringdashboard-id="abc"el.dashboardId = 'abc'
numberheight="400"el.height = 400
booleanenable-download-csv="true" (a bare attribute stays off)el.enableDownloadCsv = true
jsonoptions='{"a":true}' (a JSON string)el.options = { a: true }
functionNot possibleel.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 bare enable-download-csv stays 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

AttributePropertyTypeDefaultWhat it does
tokentokenstringrequiredThe guest token from your backend.
dashboard-iddashboardIdstringnoneThe dashboard to show. Copy it from the Embeds page.
optionsoptionsjson{}Viewer actions, layout and URL state. See Set dashboard options.
themethemejsonnoneInline theme object.
theme-namethemeNamestringnoneName of a saved theme.
admin-theme-optionsadminThemeOptionsjsonnoneAdmin theme fields. With theme-name, they merge onto the named theme field by field.
color-schemecolorSchemestringtheme mode, then lightlight, dark, system (follows the OS, live) or theme.
enable-theme-contrast-warningsenableThemeContrastWarningsbooleanfalseLogs one console warning per theme whose colors fail contrast checks.
is-hide-chart-settingsisHideChartSettingsbooleanfalseHides chart settings in full screen.
is-hide-table-previewisHideTablePreviewbooleanfalseHides the table preview in full screen.
is-sticky-dashboard-filtersisStickyDashboardFiltersbooleanfalseKeeps dashboard filters at the top while the viewer scrolls.
enable-download-csvenableDownloadCsvbooleanfalseShows CSV download on cards.
enable-email-csvenableEmailCsvbooleanfalseShows email CSV on cards.
disable-download-pngdisableDownloadPngbooleanfalseHides PNG download.
enable-download-all-metricsenableDownloadAllMetricsbooleanfalseShows download all metrics in the dashboard menu.
enable-download-all-pdfenableDownloadAllPdfbooleanfalseShows download as PDF in the dashboard menu.
enable-multi-metric-filtersenableMultiMetricFiltersbooleanfalseAllows more than one metric filter on a card.
disable-fullscreendisableFullscreenbooleanfalseHides full screen on cards.
enable-title-click-fullscreenenableTitleClickFullscreenbooleanfalseOpens full screen when the viewer selects a card title.
enable-adhoc-drillenableAdhocDrillbooleanfalseDrill into any field. v2 cards only. See Drill and cross-filter switches.
enable-exclude-filterenableExcludeFilterbooleanfalseAdds “Exclude” to the data point menu. v2 cards only.
enable-cross-filterenableCrossFilterbooleanfalseA chart click filters the other cards. v2 cards only.
enable-chart-dashboard-navigationenableChartDashboardNavigationbooleanfalseA chart click with a saved dashboard destination calls chartClickFunction.
nonechartClickFunctionfunctionnoneCalled on a chart click. See chartClickFunction payloads.
nonefilterStateFunctionfunctionnoneCalled with the applied filters on every filter change. See Filter state.
nonehandleServerEventfunctionnoneCalled on embed events. See Server events.
global-filter-optionsglobalFilterOptionsjsonnoneDefault values and choices for dashboard filters. See Filter state.
hide-dashboard-filtershideDashboardFiltersjsonnoneNames of dashboard filters to hide, as a string array.
calendar-typecalendarTypestringdefaultdefault or ind. ind makes date presets use the fiscal year.
custom-chart-settingscustomChartSettingsjsonnoneDefaults and edit rights for chart settings in metric creation.
chart-columnschartColumnsjsonnonePer metric: [{ "metricId", "dimensions", "measures", "isEnabled" }].
long-description-configlongDescriptionConfigjsonnone{ "width", "fontColor" } for the long description popover.
options-iconoptionsIconstringkebab-menu-verticalCard menu icon: kebab-menu-vertical or download.
settings-iconsettingsIconjsonnone{ "name", "ariaLabel", "iconSvg", "menuPosition" } for the dashboard settings button.
nonemanageMetricsBtnContentfunctionnoneContent for the manage metrics button.
no-data-imgnoDataImgstringnoneImage URL for an empty card.
no-data-found-svgnoDataFoundSvgstringnoneSVG markup for the “No Data” screen.
custom-messagescustomMessagesjsonnoneYour own text for token and empty states. See Custom messages and support.
noneonSupportClickfunctionnoneAdds a support button to the crash screen.
support-labelsupportLabelstringGet helpLabel of that support button.
languagelanguagestringnoneLanguage code to show. See Translate.
translation-dictionarytranslationDictionaryjsonnoneYour own translations.
config-idconfigIdstring?configId= in the page URLData app configuration id. Set it when two embeds share a page.
ui-versionuiVersionstringlegacyv2 loads the v2 design. See Turn on the v2 embed design.
embed-flagsembedFlagsjson{}Which parts of the v2 design to turn on.
data-dbn-uidataDbnUistringnonev2 turns on the v2 chart engine.
base-urlbaseUrlstringhttps://api.usedatabrain.comBackend origin. See base-url.
debugdebugstringoff1, true, yes or on writes [DBN Debug] logs to the console.

dbn-metric

AttributePropertyTypeDefaultWhat it does
tokentokenstringrequiredThe guest token from your backend.
metric-idmetricIdstringrequiredThe metric to show. Copy it from the Embeds page.
variantvariantstringcardcard (full screen included) or fullscreen.
widthwidthnumbernoneCard width in pixels.
heightheightnumbernoneCard height in pixels.
class-nameclassNamestring""CSS class on the card.
stylestylejsonnoneInline CSS object.
chart-renderer-typechartRendererTypestringcanvascanvas or svg.
chart-colorschartColorsjsontheme colorsSeries colors, as a string array.
chart-appearancechartAppearancejsonnoneChart appearance fields.
appearance-optionsappearanceOptionsjsonnoneappearanceOptionsPosition, dynamicBehaviour, cumulativeBar, stackedBars.
themethemejsonnoneInline theme object.
theme-namethemeNamestringnoneName of a saved theme.
color-schemecolorSchemestringtheme mode, then lightlight, dark, system or theme.
enable-theme-contrast-warningsenableThemeContrastWarningsbooleanfalseLogs theme contrast warnings.
metric-filter-optionsmetricFilterOptionsstringnoneChoices for the metric filters, as a JSON string.
metric-filter-positionmetricFilterPositionstringoutsideoutside or inside the card.
enable-multi-metric-filtersenableMultiMetricFiltersbooleanfalseAllows more than one metric filter on the card.
global-filter-optionsglobalFilterOptionsjsonnoneDefault filter values.
hide-date-picker-optionshideDatePickerOptionsjsonnoneDate presets to hide, by label.
calendar-typecalendarTypestringdefaultdefault or ind (fiscal year).
is-hide-chart-settingsisHideChartSettingsbooleanfalseHides chart settings in full screen.
is-hide-table-previewisHideTablePreviewbooleanfalseHides the table preview in full screen.
is-disable-card-titleisDisableCardTitlebooleanfalseHides the card title.
is-merged-cardisMergedCardbooleanfalseShows the metric as a merged card.
hide-metric-card-shadowhideMetricCardShadowbooleanfalseRemoves the card shadow.
disable-metric-card-borderdisableMetricCardBorderbooleanfalseRemoves the card border.
enable-download-csvenableDownloadCsvbooleanfalseShows CSV download.
enable-email-csvenableEmailCsvbooleanfalseShows email CSV.
disable-download-pngdisableDownloadPngbooleanfalseHides PNG download.
disable-fullscreendisableFullscreenbooleanfalseHides full screen.
enable-title-click-fullscreenenableTitleClickFullscreenbooleanfalseOpens full screen when the viewer selects the title.
disable-underlying-datadisableUnderlyingDatabooleanfalseHides underlying data.
disable-download-data-no-filtersdisableDownloadDataNoFiltersbooleanfalseBlocks a data download while no filter is applied.
disable-download-underlying-data-no-filtersdisableDownloadUnderlyingDataNoFiltersbooleanfalseBlocks an underlying data download while no filter is applied.
chart-columnschartColumnsjsonnone{ "dimensions", "measures", "isEnabled" }.
long-description-configlongDescriptionConfigjsonnone{ "width", "fontColor" }.
options-iconoptionsIconstringkebab-menu-verticalkebab-menu-vertical or download.
no-data-imgnoDataImgstringnoneImage URL for an empty card.
custom-messagescustomMessagesjsonnoneYour own text for token and empty states.
noneonSupportClickfunctionnoneAdds a support button to the crash screen.
support-labelsupportLabelstringGet helpLabel of that support button.
noneonMinimizefunctionnoneCalled when the viewer selects minimize.
languagelanguagestringnoneLanguage code to show.
translation-dictionarytranslationDictionaryjsonnoneYour own translations.
data-dbn-uidataDbnUistringnonev2 turns on the v2 chart engine.
base-urlbaseUrlstringhttps://api.usedatabrain.comBackend origin.
debugdebugstringoff1, 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.

AttributeNeedsWhat it does
enable-adhoc-drillui-version="v2" and the embed_ui_v2_metric_cards flagThe viewer can drill into any field of a chart.
enable-cross-filterui-version="v2" and the embed_ui_v2_metric_cards flagA chart click filters the other cards. A metric with cross filtering turned on in its saved settings also publishes.
enable-exclude-filterv2 cardsAdds “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-navigationchartClickFunctionA 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.

PayloadWhenShape
A bare valueThe metric’s click action sends a value to your appThe 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.
  • filters is [{ column, value }]. Pass globalFilterOptions to the new element as it is.
  • path is a ready query string. It is not a route in your app.

Custom messages and support

custom-messages keys:

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

MessageCause
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.proxyAuthUrl and window.dbn.baseUrl win over base-url.

Next: Set dashboard options.