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
| Prop | Element | Type | What it does |
|---|---|---|---|
theme-name | both | string | Loads a saved theme by its name. |
color-scheme | both | light, dark, system or theme | Sets light or dark mode. |
admin-theme-options | <dbn-dashboard> | JSON | A full theme object, or the fields you want to override. |
theme | both | JSON | Colors for buttons, checkboxes, switches, filters and layout breakpoints. |
chart-appearance | <dbn-metric> | JSON | Tooltip, label, legend and axis style for the chart. |
enable-theme-contrast-warnings | both | boolean | Logs 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 set | Theme used |
|---|---|
theme-name and admin-theme-options | The named theme, with each field you set in admin-theme-options on top |
theme-name only | The named theme |
admin-theme-options only | The inline theme |
| Neither | The 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):
| Value | Mode |
|---|---|
light | Light |
dark | Dark |
system | Follows the viewer’s OS setting, and changes when the OS setting changes |
theme | Uses the theme’s own mode |
The embed uses the first value it finds (theme/resolveRuntimeAppearance.ts:131-146):
color-scheme.options.colorSchemeon<dbn-dashboard>.- The theme’s mode. A theme set to Auto (
general.isSystemMode: true) follows the OS setting. Else it usesgeneral.mode. - 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.
| Block | Field | Type | What it does |
|---|---|---|---|
general | name | string | Theme name |
fontFamily | string | Font for the embed | |
datePickerFormat | string | Day.js format for date pickers, for example DD-MMM-YYYY | |
mode | light or dark | The theme’s mode. Not set means light. | |
isSystemMode | boolean | Follow the viewer’s OS setting (Auto) | |
darkOverrides | object | Dark mode values, with the same blocks as this table except general | |
dashboard | backgroundColor | color | Page background |
ctaColor, ctaTextColor | color | Main button fill and text | |
selectBoxSize | small, medium or large | Filter control size | |
selectBoxVariant | floating or static | Filter control style | |
selectBoxBorderRadius, selectBoxTextColor | string, color | Filter control corners and text | |
metricCardColor | color | Card background | |
horizontalGap, verticalGap | number (px) | Space between cards | |
underlyingData | object | Table style of the underlying data drawer | |
disableDashboardMinimap | boolean | Hides the dashboard minimap | |
cardTitle | fontSize, fontWeight, color | string | Card title text |
elementColor | color | Title color of text and section elements | |
cardDescription | fontSize, fontWeight, color, elementColor | string | Card description text |
chart | palettes | [{ name, colors[] }] | Chart color palettes |
paletteOptions, selected | string array, string | Palette names and the one in use | |
fontFamily, fontColor, letterSpacing | string | Chart text | |
chartSettingsOverride | boolean | Theme chart text wins over each metric’s settings | |
tooltip | object | header, label, value text, card box, pointerStyle, override | |
tableSettings | object | header and content text, override, autoPagination, paginationPosition | |
cardCustomization | padding, borderRadius, shadow | string | Card box |
disableShadowOnHover, disableStroke | boolean | Card shadow on hover, card border | |
metricStrokeColor | color | Card border color | |
responsiveFontScaling | boolean | Shrinks card title and description text on dashboards under 1100 px wide | |
darkElevation | boolean | In dark mode, makes cards lighter than the page |
theme fields
Source: publicTypes.ts:58-93.
| Field | Type | What 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 |
datePickerColor | color | Date picker accent |
manageMetricsStyle | CSS object | Style 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.
| Field | What it sets |
|---|---|
chartTooltip | pointerStyle (solid or dashed), labelStyle, valueStyle, tooltipHeader, tooltipCard (bgColor, borderColor, borderRadius, padding) |
chartLabel | position (hidden, top, left, right, bottom, inside), radialChartposition (outside, inside, hidden) |
chartMargin | marginTop, marginBottom, marginLeft, marginRight |
chartLegend | show, fixedPosition (for example bottom-center), legendAppearance (horizontal or vertical), legendShape, truncateLegend, font fields |
verticalAxis, horizontalAxis | hideAxisLines, 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.