Skip to Content

Component Options

Style an embed

Pick a saved theme, set light or dark mode, and override theme fields from your page.

Before you start

  • You have a saved theme, or you use the workspace default. Create a theme in Settings > Embed & Distribution > UI Theming.

Props

PropElementTypeWhat it does
theme-namebothstringLoads a saved theme by its name.
color-schemebothlight, dark, system or themeSets light or dark mode.
admin-theme-options<dbn-dashboard>JSONA full theme object, or the fields you want to override.
themebothJSONColors for buttons, checkboxes, switches, filters and layout breakpoints.
chart-appearance<dbn-metric>JSONTooltip, label, legend and axis style for the chart.
enable-theme-contrast-warningsbothbooleanLogs a console warning when theme colors fail WCAG contrast.

Source: webcomponents.ts:275-397, 410-490.

Pick the theme

<dbn-dashboard
  token="GUEST_TOKEN"
  dashboard-id="DASHBOARD_ID"
  theme-name="Brand"
  color-scheme="system"
></dbn-dashboard>

The dashboard picks one theme (theme/resolveApplicableTheme.ts:24-31):

You setTheme used
theme-name and admin-theme-optionsThe named theme, with each field you set in admin-theme-options on top
theme-name onlyThe named theme
admin-theme-options onlyThe inline theme
NeitherThe workspace default theme

The merge is field by field. An array, such as chart.palettes, replaces the array in the named theme.

<dbn-metric> has no admin-theme-options. It uses theme-name, else the workspace default.

Set light or dark mode

color-scheme takes four values (theme/resolveRuntimeAppearance.ts:54-59):

ValueMode
lightLight
darkDark
systemFollows the viewer’s OS setting, and changes when the OS setting changes
themeUses the theme’s own mode

The embed uses the first value it finds (theme/resolveRuntimeAppearance.ts:131-146):

  1. color-scheme.
  2. options.colorScheme on <dbn-dashboard>.
  3. The theme’s mode. A theme set to Auto (general.isSystemMode: true) follows the OS setting. Else it uses general.mode.
  4. Light.

An unknown value counts as not set.

In dark mode, the embed makes dark colors from your light colors. To set a dark color yourself, put it in general.darkOverrides.

Override theme fields

<dbn-dashboard
  token="GUEST_TOKEN"
  dashboard-id="DASHBOARD_ID"
  theme-name="Brand"
  admin-theme-options='{
    "general": { "fontFamily": "Inter", "datePickerFormat": "DD-MMM-YYYY" },
    "dashboard": { "ctaColor": "#4F46E5", "ctaTextColor": "#FFFFFF" },
    "cardCustomization": { "borderRadius": "12px", "responsiveFontScaling": true }
  }'
></dbn-dashboard>

To start from a saved theme, open it in the theme editor, select Code, then Export. Paste the JSON here.

admin-theme-options fields

Source: publicTypes.ts:195-328.

BlockFieldTypeWhat it does
generalnamestringTheme name
fontFamilystringFont for the embed
datePickerFormatstringDay.js format for date pickers, for example DD-MMM-YYYY
modelight or darkThe theme’s mode. Not set means light.
isSystemModebooleanFollow the viewer’s OS setting (Auto)
darkOverridesobjectDark mode values, with the same blocks as this table except general
dashboardbackgroundColorcolorPage background
ctaColor, ctaTextColorcolorMain button fill and text
selectBoxSizesmall, medium or largeFilter control size
selectBoxVariantfloating or staticFilter control style
selectBoxBorderRadius, selectBoxTextColorstring, colorFilter control corners and text
metricCardColorcolorCard background
horizontalGap, verticalGapnumber (px)Space between cards
underlyingDataobjectTable style of the underlying data drawer
disableDashboardMinimapbooleanHides the dashboard minimap
cardTitlefontSize, fontWeight, colorstringCard title text
elementColorcolorTitle color of text and section elements
cardDescriptionfontSize, fontWeight, color, elementColorstringCard description text
chartpalettes[{ name, colors[] }]Chart color palettes
paletteOptions, selectedstring array, stringPalette names and the one in use
fontFamily, fontColor, letterSpacingstringChart text
chartSettingsOverridebooleanTheme chart text wins over each metric’s settings
tooltipobjectheader, label, value text, card box, pointerStyle, override
tableSettingsobjectheader and content text, override, autoPagination, paginationPosition
cardCustomizationpadding, borderRadius, shadowstringCard box
disableShadowOnHover, disableStrokebooleanCard shadow on hover, card border
metricStrokeColorcolorCard border color
responsiveFontScalingbooleanShrinks card title and description text on dashboards under 1100 px wide
darkElevationbooleanIn dark mode, makes cards lighter than the page

theme fields

Source: publicTypes.ts:58-93.

FieldTypeWhat it does
button{ primary, secondary, primaryText, secondaryText }Button colors
checkbox{ checked, unChecked }Checkbox colors
switch{ enabled, disabled }Switch colors
drillBreadCrumbs{ fontFamily, fontColor, activeColor }Drill path text
multiSelectFilterDropdown{ badgeColor, badgeTextColor }Badges in multi select filters
datePickerColorcolorDate picker accent
manageMetricsStyleCSS objectStyle of the Manage Metrics button
breakpoint{ xl, lg, md, sm, xs }Layout breakpoints in px
metricLayoutCols{ xl, lg, md, sm, xs, xxs }Grid columns at each breakpoint

chart-appearance fields

<dbn-metric> only. Source: publicTypes.ts:330-385.

FieldWhat it sets
chartTooltippointerStyle (solid or dashed), labelStyle, valueStyle, tooltipHeader, tooltipCard (bgColor, borderColor, borderRadius, padding)
chartLabelposition (hidden, top, left, right, bottom, inside), radialChartposition (outside, inside, hidden)
chartMarginmarginTop, marginBottom, marginLeft, marginRight
chartLegendshow, fixedPosition (for example bottom-center), legendAppearance (horizontal or vertical), legendShape, truncateLegend, font fields
verticalAxis, horizontalAxishideAxisLines, hideSplitLines, hideAxisLabels, hideAxisTicks, axisName, axisNameOffset, axisLabelMargin, visibleLabelCount, font and color fields

Choose the font

The embed uses the first font it finds: admin-theme-options general.fontFamily, then the named theme’s font, then chart-appearance fontFamily, then Inter (theme/resolveRuntimeAppearance.ts:166-185).

Inter ships with the embed. For any other named font, the embed adds one Google Fonts <link> to your page’s <head>. System fonts such as sans-serif load nothing (theme/webfontLoader.ts:1-43, 155). If your page blocks fonts.googleapis.com, load the font yourself.

Check contrast

Add enable-theme-contrast-warnings="true". The embed logs one console warning for each theme with text that fails WCAG contrast. The warning names the theme fields to change (theme/themeContrastDiagnostic.ts:80-105).

To turn the warnings off for the session, set window.__DBN_DISABLE_THEME_CONTRAST_WARNING__ = true.

Next, preview the theme.