Component Options Reference

Interactive Demo

Try out the components with different options in DataBrain’s playground

This reference guide provides detailed documentation for all available options and properties for Databrain’s web components: dbn-dashboard and dbn-metric.

Understanding the Configuration Layers

Databrain components have four configuration layers that are applied in a specific priority order. Understanding this hierarchy is essential for getting the behavior you expect.

Settings are resolved from highest priority (top) to lowest priority (bottom). A higher-priority layer always wins when the same setting exists in multiple layers.

Priority	Layer	Scope	Prop	When to Use
1 (highest)	Chart Appearance	Per-metric (on `dbn-metric`)	`chart-appearance`	Fine-tune visual styling (margins, axis labels, legend position, tooltip fonts) for a single metric.
2	Admin Theme Options	Global (on `dbn-dashboard`)	`admin-theme-options`	Apply org-wide branding: fonts, card styles, color palettes, dashboard background.
3	Custom Chart Settings	Per-metric defaults (on `dbn-dashboard`)	`custom-chart-settings`	Set default chart behaviors (axis visibility, bar width, sort, zoom) and lock/unlock end-user editing via `canEdit`.
4 (lowest)	Saved Metric Settings	Per-metric (stored in DB)	N/A	Settings saved by the metric creator in the Databrain admin UI.

chart-appearance vs custom-chart-settings field names differ. These two layers evolved independently and use different keys for overlapping concepts. See the Field Name Mapping table below for a cross-reference.

custom-chart-settings only applies to newly created metrics. If a metric already exists in the database with saved settings, the custom-chart-settings prop will not override those saved values. This is by design — custom-chart-settings provides defaults for metric creation, not runtime overrides. To override settings on existing metrics, use chart-appearance instead.

Dashboard Component (`dbn-dashboard`)

The dashboard component displays a complete dashboard with multiple metrics and interactive features.

Required Properties

string

required

Guest token for authentication. Must be generated from your backend using the Databrain API.

string

required

Unique identifier for the dashboard to display.

Display & Layout Options

Basic Display Controls

boolean

default:"false"

Hides the table preview in full screen view.

boolean

default:"false"

Hides chart settings in full screen view.

boolean

default:"false"

Disables the full screen option for the dashboard.

boolean

default:"false"

Enables fullscreen mode when the metric title is clicked. Provides an alternative way for users to enter fullscreen without using the fullscreen button.

string

default:"kebab-menu-vertical"

Controls which options icon to display. Options: kebab-menu-vertical | download

boolean

default:"false"

Makes dashboard filters sticky at the top when scrolling.

object

Controls the visibility and configuration of the settings icon. Must be passed as JSON.stringify(...).

Settings Icon Configuration

{
  name: 'random',
  iconSvg: 'svg',
  menuPosition: 'bottom-start', // optional; defaults to "bottom-start"
}

string

Custom label text for the settings button.

string

Custom SVG markup for the settings button icon.

Download & Export Options

boolean

default:"false"

Enables CSV download option in metric card actions.

boolean

default:"false"

Enables email CSV option in metric card actions.

boolean

default:"false"

Disables PNG download option in full screen mode.

boolean

default:"false"

Enables download option for all metrics at once.

boolean

default:"false"

Enables PDF download option for all metrics at once.

Advanced Configuration

Dashboard Options Object

The options prop accepts a JSON object with the following properties:

{
  "disableDownloadDataNoFilters": false,
  "disableDownloadUnderlyingDataNoFilters": false,
  "isShowNoDataFoundScreen": false,
  "disableMetricCreation": false,
  "disableMetricUpdation": false,
  "disableMetricCardBorder": false,
  "disableMetricDeletion": false,
  "disableLayoutCustomization": false,
  "dashboardSpacing": {
    "verticalGap": 30,
    "horizontalGap": 30,
    "hide": false,
  },
  "disableSaveLayout": false,
  "disableScheduleEmailReports": false,
  "disableManageMetrics": false,
  "disableMainLoader": false,
  "disableMetricLoader": false,
  "hideDashboardName": false,
  "allowedChartTypes": ["line", "bar", "stack", "row", "combo", "pie", "doughnut", "waterfall", "funnelV2", "gaugeV2", "singleValue", "table", "pivotV2", "rose", "horizontalStack", "treeMap", "progressBarV2"],
  "hideMetricCardShadow": false,
  "showDashboardActions": true,
  "disableUnderlyingData": false,
  "shouldFitFullScreen": false,
  "isModifyUrl": false,
  "exportMsgPosition": "bottom",
  "dashboardPadding": "16px",
  "ctaButtonCustomization": {
    "primary": {
      "styles": "background-color: #2563eb; color: #ffffff; border-radius: 8px;",
      "hoverStyles": "background-color: #1d4ed8;",
      "activeStyles": "background-color: #1e40af;",
      "disabledStyles": "opacity: 0.5;"
    },
    "secondary": {
      "styles": "background-color: #f1f5f9; color: #0f172a;"
    },
    "tertiary": {
      "styles": "color: #2563eb;"
    }
  },
  "showAllChartSettings": false,
  "renameBoard": "workspace",
  "enableDashboardMinimap": true
}

{
  "chartColors": ["#FF6B6B", "#4ECDC4", "#45B7D1", "#96CEB4"],
  "chartPaletteOptions": [
    {
      "name": "custom1",
      "colors": ["...9 colors"]
    },
    {
      "name": "custom2",
      "colors": ["...9 colors"]
    },
    {
      "name": "custom3",
      "colors": ["...9 colors"]
    }
  ],
  "hideDatePickerOptions": ["this month", "yesterday"],
  "chartAppearance": {
    "chartTooltip": {
      "labelStyle": {
        "size": 14,
        "family": "Inter",
        "weight": 400,
        "color": "#000000"
      },
      "valueStyle": {
        "size": 14,
        "family": "Inter",
        "weight": 400,
        "color": "#000000"
      },
      "tooltipHeader": {
        "size": 14,
        "family": "Inter",
        "weight": 400,
        "color": "#000000"
      }
      "tooltipCard": {
        "bgColor": "#FFFFFF",
        "borderColor": "#FFFFFF",
        "borderRadius": 14,
        "padding": 10,
      },
    },
    "chartLabel": {
      "position": "hidden",
      "radialChartposition": "outside"
    },
    "chartMargin": {
      "marginTop": 15,
      "marginLeft": 15,
      "marginRight": 15,
      "marginBottom": 15
    },
    "chartLegend": {
      "show": true,
      "fixedPosition": "top-left",
      "enableVariablePosition": false,
      "top": 15,
      "left": 15,
      "disableLegendScrolling": true,
      "legendAppearance": "horizontal",
      "truncateLegend": 22,
      "legendShape": "circle",
      "fontSize": 14,
      "fontWeight": 400,
      "fontFamily": "Inter",
      "color": "#000000"
    },
    "verticalAxis": {
      "hideAxisLines": false,
      "hideSplitLines": false,
      "hideAxisLabels": false,
      "hideAxisTicks": false,
      "axisName": "axisName",
      "axisNameOffset": 20,
      "axisLabelMargin": 0,
      "fontSize": 14,
      "fontFamily": "Inter",
      "fontWeight": 400,
      "color": "#000000",
      "axisColor": "#000000",
      "axisNameFontConfig": {
        "fontFamily": "Inter",
        "fontSize": 14,
        "fontWeight": 400
      }
    },
    "horizontalAxis": {
      "hideAxisLines": false,
      "hideSplitLines": false,
      "hideAxisLabels": false,
      "hideAxisTicks": false,
      "axisName": "axisName",
      "axisNameOffset": 20,
      "axisLabelMargin": 0,
      "fontSize": 14,
      "fontFamily": "Inter",
      "fontWeight": 400,
      "color": "#000000",
      "axisColor": "#000000",
      "axisNameFontConfig": {
        "fontFamily": "Inter",
        "fontSize": 14,
        "fontWeight": 400
      }
    }
  }
}

boolean

default:"false"

Prevents downloading data when no filters are applied.

boolean

default:"false"

Prevents downloading underlying data when no filters are applied.

boolean

default:"false"

Shows a custom screen when no data is available.

boolean

default:"false"

Disables the ability to create new metrics.

boolean

default:"false"

Disables the ability to update existing metrics.

boolean

default:"true"

Controls visibility of dashboard actions like create metric, customize layout.

string

default:"board"

Renames the dashboard “Board” view-filter UI text (tab label, dropdown label, Add/Save CTA, and modal copy). If the value contains multiple words, only the first word is used.

boolean

default:"false"

Enables the dashboard minimap and progress header in an embedded dashboard. The minimap is disabled by default in embeds; set this option to true inside the dashboard options object to enable it. This option applies to dbn-dashboard and does not change the UI Theming setting used by dashboards in the app.

boolean

default:"false"

Makes full screen modal take up space equivalent to the dashboard component.

boolean

default:"false"

When enabled, the component appends state information (such as the active metric) to the browser URL. Useful for deep-linking into a specific view.

string

default:"bottom-right"

object

Controls the horizontal and vertical spacing between the metrics on the grid. Optional hide field hides the Adjust Spacing button from Customize Layout.

Show Example

"dashboardSpacing": {
  "verticalGap": 30,
  "horizontalGap": 30,
  "hide": true,
}

Show Notes

When omitted, default layout spacing applies.
Applying either of the verticalGap or horizontalGap sets the other to a default of 10, unless configured here.
This controls the spacing between metrics on the grid. For setting outer wrapper padding around the embedded dashboard use dashboardPadding inside the same options object.

string

Optional CSS value for the main dashboard embed wrapper padding. Uses the same rules as the standard CSS padding shorthand (for example "16px", "12px 24px", "8px 12px 16px"). Applied as an inline style on the embed dashboard container.

Show Notes

When omitted, default layout padding from stylesheets applies.
This controls outer wrapper padding around the embedded dashboard. For spacing between metrics on the grid, use dashboardSpacing inside the same options object.

object

Optional styling overrides for dashboard CTA buttons (primary, secondary, and tertiary variants). Injected styles target .cta-primary, .cta-secondary, and .cta-tertiary, so they apply anywhere those classes are used in the embedded experience (for example dashboard action buttons and full-screen metric controls).Each variant supports optional string fields — pass fragments of CSS declarations (semicolon-separated), similar to inline style text:

styles — base state
hoverStyles — :hover:enabled
activeStyles — :active
disabledStyles — :disabled

Show Nested shape

{
  primary?: {
    styles?: string;
    hoverStyles?: string;
    activeStyles?: string;
    disabledStyles?: string;
  };
  secondary?: { /* same fields */ };
  tertiary?: { /* same fields */ };
}

Show Implementation notes

background-color and color rules you provide are enforced with !important so they win over theme defaults.
If styles includes a height: declaration, a companion height helper class may be generated for layout alignment (implementation detail).
This is separate from admin-theme-options.dashboard.ctaColor / ctaTextColor, which set broad theme defaults; ctaButtonCustomization targets granular CSS per variant and state.

array

Array of color strings for chart styling. Defaults to Recharts default colors.

Show Example

["#FF6B6B", "#4ECDC4", "#45B7D1", "#96CEB4", "#FECA57"]

array

Array of custom color palette options that users can select from. Each palette should contain a name and an array of 9 colors for comprehensive chart coverage.

Show Example

[
  {
    name: "Ocean Blues",
    colors: ["#003f5c", "#2f4b7c", "#665191", "#a05195", "#d45087", "#f95d6a", "#ff7c43", "#ffa600", "#ffd700"]
  },
  {
    name: "Forest Greens",
    colors: ["#004d00", "#006600", "#008000", "#009900", "#00b300", "#00cc00", "#00e600", "#00ff00", "#66ff66"]
  },
  {
    name: "Sunset Warmth",
    colors: ["#8b0000", "#a52a2a", "#cd5c5c", "#dc143c", "#ff6347", "#ff7f50", "#ffa500", "#ffd700", "#ffffe0"]
  }
]

object

Detailed chart styling configuration for tooltips, labels, margins, legends, and axes.

Show Example

{
  chartTooltip?: {
    labelStyle?: {
      size?: number,
      family?: string,
      weight?: number,
      color?: string,
    },
    valueStyle?: {
      size?: number,
      family?: string,
      weight?: number,
      color?: string,
    },
    tooltipHeader?: {
      size?: number,
      family?: string,
      weight?: number,
      color?: string,
    },
    tooltipCard?: {
      bgColor?: string,
      borderColor?: string,
      borderRadius?: number,
      padding?: number,
    },
  },
  chartLabel?: {
    position?: "hidden" | "top" | "left" | "right" | "bottom" | "inside",
    radialChartposition?: "outside" | "inside",
  },
  chartMargin?: {
    marginTop?: number,
    marginLeft?: number,
    marginRight?: number,
    marginBottom?: number,
  },
  chartLegend?: {
    show?: boolean,
    fixedPosition?: "top-left" | "top-center" | "top-right" | "left-center" | "right-center" | "bottom-left" | "bottom-center" | "bottom-right",
    enableVariablePosition?: boolean,
    top?: number,
    left?: number,
    disableLegendScrolling?: boolean,
    legendAppearance?: "horizontal" | "vertical",
    truncateLegend?: number,
    legendShape?: "circle" | "rect" | "roundRect" | "triangle" | "diamond" | "arrow" | "none",
    fontSize?: number,
    fontWeight?: number,
    fontFamily?: string,
    color?: string,
  },
  verticalAxis?: {
    hideAxisLines?: boolean,
    hideSplitLines?: boolean,
    hideAxisLabels?: boolean,
    hideAxisTicks?: boolean,
    axisName?: string,
    axisNameOffset?: number,
    axisLabelMargin?: number,
    fontSize?: number,
    fontFamily?: string,
    fontWeight?: number,
    color?: string,
    axisColor?: string,
    axisNameFontConfig?: {
      fontFamily?: string,
      fontSize?: number,
      fontWeight?: number,
    },
  },
  horizontalAxis?: {
    hideAxisLines?: boolean,
    hideSplitLines?: boolean,
    hideAxisLabels?: boolean,
    hideAxisTicks?: boolean,
    axisName?: string,
    axisNameOffset?: number,
    axisLabelMargin?: number,
    fontSize?: number,
    fontFamily?: string,
    fontWeight?: number,
    color?: string,
    axisColor?: string,
    axisNameFontConfig?: {
      fontFamily?: string,
      fontSize?: number,
      fontWeight?: number,
    },
  },
}

Configure global filters for the dashboard:

{
  "Filter name for a string datatype": {
    "options": [
      { "value": "James Smith", "label": "James" },
      { "value": "Olivia Johnson", "label": "Olivia" },
      { "value": "Emma Brown", "label": "Emma" }
    ],
    "defaultOption": "James Smith"
  }
}

{
  "Filter name for a number datatype": {
    "defaultOption": {"min": 100, "max": 900}
  }
}

{
  "Filter name for a date datatype": {
    "defaultOption": {"startDate": "2024-01-01", "endDate": "2024-12-31"},
    "datePresetOptions": [
      {
        "type": "this",
        "interval": 1,
        "timeGrain": "month",
        "label": "this month",
        "startDate": "2024-01-01",
        "endDate": "2024-01-31"
      }
    ]
  }
}

Theme Configuration

object

Custom theme configuration for component styling.

Show Theme Structure

{
  "button": {
    "primaryText": "white",
    "primary": "#007bff",
    "secondaryText": "black", 
    "secondary": "white"
  },
  "checkbox": {
    "checked": "#007bff",
    "unChecked": "#6c757d"
  },
  "switch": {
    "enabled": "#28a745",
    "disabled": "#6c757d"
  },
  "drillBreadCrumbs": {
    "fontFamily": "Inter",
    "fontColor": "black",
    "activeColor": "#007bff"
  },
  "multiSelectFilterDropdown": {
    "badgeColor": "#007bff",
    "badgeTextColor": "white"
  }
}

string

Name of a predefined theme from app settings UI theming.

Admin Theme Options

object

Advanced UI theming configuration for the dashboard. Controls fonts, backgrounds, CTA colors, card styling, and chart palettes. Must be passed as JSON.stringify(...).

Show Admin Theme Options Structure

{
  "general": {
    "name": "My Theme",
    "fontFamily": "Inter",
    "datePickerFormat": "DD-MM-YYYY"
  },
  "dashboard": {
    "backgroundColor": "#FFFFFF",
    "ctaColor": "#007bff",
    "ctaTextColor": "#FFFFFF",
    "selectBoxSize": "medium",
    "selectBoxVariant": "floating",
    "selectBoxBorderRadius": "8px",
    "selectBoxTextColor": "#333333",
    "metricCardColor": "#FFFFFF"
  },
  "cardTitle": {
    "fontSize": "16px",
    "fontWeight": "600",
    "color": "#000000",
    "elementColor": "#1e293b"
  },
  "cardDescription": {
    "fontSize": "12px",
    "fontWeight": "400",
    "color": "#666666",
    "elementColor": "#64748b"
  },
  "chart": {
    "palettes": [
      {
        "name": "Custom Palette",
        "colors": ["#FF6B6B", "#4ECDC4", "#45B7D1", "#96CEB4", "#FECA57"]
      }
    ],
    "paletteOptions": ["Custom Palette"],
    "selected": "Custom Palette",
    "fontFamily": "Roboto",
    "fontColor": "#333333",
    "letterSpacing": "0.5px",
    "tooltip": {
      "header": {
        "fontFamily": "Roboto",
        "fontSize": "14px",
        "fontWeight": "bold",
        "fontColor": "#000000"
      },
      "label": {
        "fontFamily": "Roboto",
        "fontSize": "12px",
        "fontWeight": "normal",
        "fontColor": "#333333"
      },
      "value": {
        "fontFamily": "Roboto",
        "fontSize": "12px",
        "fontWeight": "bold",
        "fontColor": "#000000"
      }
    }
  },
  "cardCustomization": {
    "padding": "16px",
    "borderRadius": "8px",
    "shadow": "0 2px 8px rgba(0,0,0,0.1)",
    "disableShadowOnHover": false,
    "disableStroke": false,
    "metricStrokeColor": "#E0E0E0"
  }
}

string

Name of the theme.

string

Global font family applied to the dashboard.

string

Date format string for date pickers (e.g. "DD-MM-YYYY", "MM-DD-YYYY", "YYYY-MM-DD").

string

Background color of the dashboard container.

string

Primary call-to-action button color.

string

Text color for call-to-action buttons.

string

default:"medium"

Size of filter select boxes. Options: "small" | "medium" | "large"

string

default:"floating"

Style variant for filter select boxes. Options: "floating" | "static"

string

Border radius for filter select boxes (e.g. "8px").

string

Text color for filter select boxes.

string

Background color of individual metric cards.

string

Font size of metric card titles (e.g. "16px").

string

Font weight of metric card titles (e.g. "600").

string

Text color of standard metric card titles (.dbn-metric-card-title).

string

Text color for element metric titles — titles rendered in the element layout (.dbn-metric-element-title). Use when element metrics should differ from cardTitle.color. Applied with !important when set.

Show Relationship to `cardTitle.color`

color styles the default card chrome title.
elementColor styles only element-mode titles. Omit either field to fall back to product defaults for that surface.

string

Font size of metric card descriptions.

string

Font weight of metric card descriptions.

string

Text color of standard metric card descriptions (.dbn-metric-card-description).

string

Text color for element metric descriptions (.dbn-metric-element-description). Separate from cardDescription.color; applied with !important when set.

array

Array of custom chart color palettes. Each palette has a name and an array of colors.

array

Array of palette name strings available for selection.

string

Name of the currently selected palette.

string

Font family applied to chart axis labels, legend text, and chart titles (e.g. "Roboto").

string

Default text color for chart axis labels, legend text, and chart titles (e.g. "#333333").

string

Letter spacing applied to chart text elements (e.g. "0.5px").

Global tooltip font configuration with nested header, label, and value objects. Each accepts fontFamily, fontSize, fontWeight, and fontColor.

Known limitation: The chart-level font fields (chart.fontFamily, chart.fontColor, chart.letterSpacing, chart.tooltip) are currently only applied from saved admin themes (configured via the Databrain admin UI or the theme-name prop). Passing them directly via the admin-theme-options prop will not affect chart rendering. Other admin-theme-options fields (dashboard colors, card styling, palettes, datePickerFormat) work correctly via the prop.

string

Inner padding of metric cards (e.g. "16px").

string

Border radius of metric cards (e.g. "8px").

string

Box shadow of metric cards (e.g. "0 2px 8px rgba(0,0,0,0.1)").

boolean

default:"false"

Disables the shadow effect when hovering over metric cards.

boolean

default:"false"

Disables the border stroke around metric cards.

string

Border stroke color for metric cards when stroke is enabled (e.g. "#E0E0E0").

Additional Dashboard Properties

object

Controls the appearance of metric long-description tooltips. Must be passed as JSON.stringify(...).

Show Long Description Config

{
  "width": "300px",
  "fontColor": "#333333"
}

array

Restricts which columns are available to end users for each metric. Each entry targets a specific metric. Must be passed as JSON.stringify(...).

Show Chart Columns Config

[
  {
    "metricId": "metric-1",
    "isEnabled": true,
    "dimensions": ["region", "category"],
    "measures": ["revenue", "profit"]
  }
]

Per-Metric Chart Settings

object

Per-metric chart settings that allow you to set default values and control whether end users can edit each setting. Must be passed as JSON.stringify(...). Refer to the Custom Chart Settings Reference section below for the complete schema.

{
  labelSettings: {
    XAxisStyle: {
      size: { defaultValue: 12, canEdit: true }
    }
  },
  legendSettings: {
    show: { defaultValue: true, canEdit: false }
  }
}

<dbn-dashboard
  custom-chart-settings={JSON.stringify({
    legendSettings: {
      show: { defaultValue: true, canEdit: false },
      position: { defaultValue: "horizontal", canEdit: true }
    },
    customSettings: {
      hideXSplitLines: { defaultValue: false, canEdit: true }
    }
  })}
  ...other-props
/>

Internationalization

string

default:"en"

Language code for component localization (e.g., “fr”, “es”, “de”).

object

Custom translation dictionary for component text.

Show Translation Example

{
  "total sales": {
    "en": "total sales",
    "fr": "ventes totales", 
    "es": "ventas totales",
    "de": "Gesamtumsatz"
  }
}

string

default:"default"

Calendar system to use. Options: default | ind

Event Handling

string

Name of a global function to handle server events. Define the function in the global scope.

// Define globally accessible function
window.myServerEventHandler = (event) => {
  console.log('Server event:', event);
  // Handle the event
};

<dbn-dashboard 
  handle-server-event="myServerEventHandler"
  ...other-props
/>

Custom Chart Click Action

string

Name of a global function to call when a user clicks on a chart data point. Define the function in the global scope.

// Define globally accessible function
window.myChartClickHandler = (data) => {
  console.log('Chart clicked:', data);
  // Handle the click data
};

<dbn-dashboard 
  chart-click-function="myChartClickHandler"
  ...other-props
/>

The shape of the data parameter depends on the chart type:

Chart Type	Data Shape	Example
Table	`{ columnName: value, ... }`	`{ "product name": "Product A1", "price": 4.444 }`
Tree Map, Sankey	`{ name: xVal, value: yVal }`	`{ name: "Category A", value: 1200 }`
All other charts	`{ name: xVal, value: yVal, columnName: colName }`	`{ name: "Jan", value: 500, columnName: "revenue" }`

When Pass Complete Data is not enabled, the clicked value is directly passed instead of the data object.

Custom Messages

object

Custom messages for various component states.

Show Available Messages

{
  "tokenExpiry": "Your session has expired. Please refresh the page.",
  "tokenAbsent": "Authentication token is missing. Please log in again."
}

Custom Chart Settings Reference

The custom-chart-settings prop allows you to configure default values and control end-user editability for individual chart settings on each metric card. Every field follows the shape { defaultValue: <value>, canEdit: true | false }.

custom-chart-settings defaults are only applied when a metric is first created. They do not override settings already saved on existing metrics. See Understanding the Configuration Layers.

Field Name Mapping

The chart-appearance prop (Priority 1) and custom-chart-settings prop (Priority 3) use different field names for overlapping concepts. Use this table to find the equivalent field when switching between layers.

Concept	`chart-appearance` field	`custom-chart-settings` field
Legend visibility	`chartLegend.show`	`legendSettings.show`
Legend orientation	`chartLegend.legendAppearance` (`"horizontal"` / `"vertical"`)	`legendSettings.position` (`"horizontal"` / `"vertical"`)
Legend position	`chartLegend.fixedPosition` (e.g. `"bottom-center"`)	`legendSettings.fixedPosition`
Legend shape	`chartLegend.legendShape`	`legendSettings.legendShape`
Legend scrolling	`chartLegend.disableLegendScrolling`	`legendSettings.disableScroll`
Legend truncation	`chartLegend.truncateLegend`	`legendSettings.truncateLegendValue`
Legend font	`chartLegend.fontSize` / `fontWeight` / `fontFamily` / `color`	`legendSettings.fontSize` / `fontWeight` / `fontFamily` / `color`
Tooltip label font	`chartTooltip.labelStyle.{size,family,weight,color}`	`tooltipSettings.labelStyle.{size,family,weight,color}`
Tooltip value font	`chartTooltip.valueStyle.{size,family,weight,color}`	`tooltipSettings.valueStyle.{size,family,weight,color}`
Tooltip header font	`chartTooltip.tooltipHeader.{size,family,weight,color}`	`tooltipSettings.tooltipHeader.{size,family,weight,color}`
Label position	`chartLabel.position`	`labelSettings.position`
Margins	`chartMargin.{marginTop,marginLeft,marginRight,marginBottom}`	`margins.{marginTop,marginLeft,marginRight,marginBottom}`
X-axis label font	`horizontalAxis.{fontSize,fontFamily,fontWeight,color}`	`labelSettings.XAxisStyle.{size,family,weight,color}`
Y-axis label font	`verticalAxis.{fontSize,fontFamily,fontWeight,color}`	`labelSettings.YAxisStyle.{size,family,weight,color}`
Hide axis lines	`verticalAxis.hideAxisLines` / `horizontalAxis.hideAxisLines`	`customSettings.hideXAxisLines` / `customSettings.hideYAxisLines`
Hide split lines	`verticalAxis.hideSplitLines` / `horizontalAxis.hideSplitLines`	`customSettings.hideXSplitLines` / `customSettings.hideYSplitLines`
Axis label margin	`verticalAxis.axisLabelMargin` / `horizontalAxis.axisLabelMargin`	`labelSettings.XAxisStyle.axisMargin` / `labelSettings.YAxisStyle.axisMargin`

Margins

margins: {
  marginTop: { defaultValue: 20, canEdit: true | false },
  marginBottom: { defaultValue: 5, canEdit: true | false },
  marginLeft: { defaultValue: 5, canEdit: true | false },
  marginRight: { defaultValue: 5, canEdit: true | false },
}

Chart Colors

chartColors: { defaultValue: ['#FF0000', '#FF7F00', '#FFFF00', '#00FF00', '#0000FF', '#4B0082', '#8B00FF', '#FF1493', '#00FFFF'], canEdit: true | false }

Legend Settings

legendSettings: {
  show: { defaultValue: true | false, canEdit: true | false },
  top: { defaultValue: 0, canEdit: true | false },
  left: { defaultValue: 0, canEdit: true | false },
  position: { defaultValue: 'horizontal' | 'vertical', canEdit: true | false },
  truncateLegendValue: { defaultValue: 20, canEdit: true | false },
  legendShape: { defaultValue: 'roundRect' | 'diamond' | 'triangle' | 'circle' | 'arrow', canEdit: true | false },
  customise: { defaultValue: true | false, canEdit: true | false },
  fixedPosition: { defaultValue: 'bottom-center', canEdit: true | false },
  disableScroll: { defaultValue: true | false, canEdit: true | false },
  fontSize: { defaultValue: 12, canEdit: true | false },
  fontFamily: { defaultValue: 'Inter', canEdit: true | false },
  fontWeight: { defaultValue: 400, canEdit: true | false },
  color: { defaultValue: '#000000', canEdit: true | false },
}

Label Settings

labelSettings: {
  position: { defaultValue: 'left' | 'right' | 'top' | 'bottom' | 'inside' | 'outside' | 'hidden', canEdit: true | false },
  truncateLabel: { defaultValue: true | false, canEdit: true | false },
  truncateLabelValue: { defaultValue: 10, canEdit: true | false },
  showLabelLine: { defaultValue: true | false, canEdit: true | false },
  isEnableValueSummation: { defaultValue: false, canEdit: true | false },
  showDimension: { defaultValue: true | false, canEdit: true | false },
  isDynamicPosition: { defaultValue: true | false, canEdit: true | false },
  showActualValue: { defaultValue: true | false, canEdit: true | false },
  XAxisStyle: {
    size: { defaultValue: 12, canEdit: true | false },
    family: { defaultValue: 'Inter', canEdit: true | false },
    weight: { defaultValue: 400, canEdit: true | false },
    color: { defaultValue: '#000000', canEdit: true | false },
    axisName: { defaultValue: '', canEdit: true | false },
    axisPadding: { defaultValue: 0, canEdit: true | false },
    axisMargin: { defaultValue: 0, canEdit: true | false },
    axisNameFontConfig: {
      fontFamily: { defaultValue: 'Inter', canEdit: true | false },
      fontSize: { defaultValue: 12, canEdit: true | false },
      fontWeight: { defaultValue: 400, canEdit: true | false },
    },
  },
  YAxisStyle: {
    size: { defaultValue: 12, canEdit: true | false },
    family: { defaultValue: 'Inter', canEdit: true | false },
    weight: { defaultValue: 400, canEdit: true | false },
    color: { defaultValue: '#000000', canEdit: true | false },
    axisName: { defaultValue: '', canEdit: true | false },
    axisPadding: { defaultValue: 0, canEdit: true | false },
    axisMargin: { defaultValue: 0, canEdit: true | false },
    axisNameFontConfig: {
      fontFamily: { defaultValue: 'Inter', canEdit: true | false },
      fontSize: { defaultValue: 12, canEdit: true | false },
      fontWeight: { defaultValue: 400, canEdit: true | false },
    },
  },
}

tooltipSettings: {
  labelStyle: {
    size: { defaultValue: 12, canEdit: true | false },
    family: { defaultValue: 'Inter', canEdit: true | false },
    weight: { defaultValue: 400, canEdit: true | false },
    color: { defaultValue: '#000000', canEdit: true | false },
  },
  valueStyle: {
    size: { defaultValue: 12, canEdit: true | false },
    family: { defaultValue: 'Inter', canEdit: true | false },
    weight: { defaultValue: 400, canEdit: true | false },
    color: { defaultValue: '#000000', canEdit: true | false },
  },
  tooltipHeader: {
    size: { defaultValue: 14, canEdit: true | false },
    family: { defaultValue: 'Inter', canEdit: true | false },
    weight: { defaultValue: 600, canEdit: true | false },
    color: { defaultValue: '#000000', canEdit: true | false },
  },
  tooltipCard: {
    bgColor: {defaultValue: '#FFFFFF', canEdit: true | false },
    borderColor: {defaultValue: '#FFFFFF', canEdit: true | false },
  }
}

Axis Settings

axisSettings: {
  axis: { defaultValue: 'left' | 'right', canEdit: true | false },
}

Custom Settings - Axis & Grid

customSettings: {
  isEnableCustomLimits: { defaultValue: true | false, canEdit: true | false },
  isEnableDynamicLimits: { defaultValue: true | false, canEdit: true | false },
  isEnableLogScale: { defaultValue: true | false, canEdit: true | false },
  customUpperLimit: { defaultValue: 0, canEdit: true | false },
  customLowerLimit: { defaultValue: 0, canEdit: true | false },
  hideXSplitLines: { defaultValue: true | false, canEdit: true | false },
  hideYSplitLines: { defaultValue: true | false, canEdit: true | false },
  hideXAxisLines: { defaultValue: true | false, canEdit: true | false },
  hideYAxisLines: { defaultValue: true | false, canEdit: true | false },
  hideYAxisTicks: { defaultValue: true | false, canEdit: true | false },
  hideXAxisTicks: { defaultValue: true | false, canEdit: true | false },
  hideXAxisLabels: { defaultValue: true | false, canEdit: true | false },
  hideYAxisLabels: { defaultValue: true | false, canEdit: true | false },
}

Custom Settings - Formatting

customSettings: {
  numberFormatter: { defaultValue: '', canEdit: true | false },
  isEnableLabelFormatting: { defaultValue: true | false, canEdit: true | false },
  isEnableTimezoneFormatting: { defaultValue: true | false, canEdit: true | false },
  isEnableBgColor: { defaultValue: true | false, canEdit: true | false },
  timeFormatter: { defaultValue: '', canEdit: true | false },
  labelPrefix: { defaultValue: '', canEdit: true | false },
  labelSuffix: { defaultValue: '', canEdit: true | false },
  isEnableLabelTooltip: { defaultValue: true | false, canEdit: true | false },
  YaxislabelFormatters: {
    defaultValue: [{ upperLimit: 1000, lowerLimit: 0, label: 'Low', color: '#00FF00' }],
    canEdit: true | false,
  },
}

Custom Settings - Title & Sub-header

customSettings: {
  enableTitleDesc: { defaultValue: true | false, canEdit: true | false },
  chartTitle: { defaultValue: '', canEdit: true | false },
  chartDesc: { defaultValue: '', canEdit: true | false },
  titlePosition: { defaultValue: 'top', canEdit: true | false },
  subHeaderShow: { defaultValue: true | false, canEdit: true | false },
  displayText: { defaultValue: '', canEdit: true | false },
  subHeaderAlignment: { defaultValue: 'center', canEdit: true | false },
}

Custom Settings - Single Value / KPI

customSettings: {
  singleValConditionalFormatter: {
    defaultValue: [{ type: 'range', min: 0, max: 100, color: '#00FF00' }],
    canEdit: true | false,
  },
}

Custom Settings - Bar & Column Charts

customSettings: {
  barWidth: { defaultValue: 20, canEdit: true | false },
  barRadius: { defaultValue: [0, 0, 0, 0], canEdit: true | false },
  cumulativeBar: { defaultValue: true | false, canEdit: true | false },
  showFullStacked: { defaultValue: true | false, canEdit: true | false },
}

Custom Settings - Combo Charts

customSettings: {
  comboAxisSettings: {
    defaultValue: [{ axis: 'left', measures: ['revenue'], chartTypes: [{ axis: 'left', type: 'bar' }] }],
    canEdit: true | false,
  },
}

Custom Settings - Zoom, Sort & Behavior

customSettings: {
  isEnableMeasureMode: { defaultValue: true | false, canEdit: true | false },
  chartZoom: {
    isZoomEnabled: { defaultValue: true | false, canEdit: true | false },
    zoomAxis: { defaultValue: 'x', canEdit: true | false },
  },
}

Custom Settings - Markers

customSettings: {
  markers: {
    isEnableMax: { defaultValue: true | false, canEdit: true | false },
    isEnableMin: { defaultValue: true | false, canEdit: true | false },
    isEnableAvg: { defaultValue: true | false, canEdit: true | false },
    maxColor: { defaultValue: '#008000', canEdit: true | false },
    minColor: { defaultValue: '#FF0000', canEdit: true | false },
  },
}

Custom Settings - Linear Gauge V2

customSettings: {
  linearGaugeV2: {
    upperLimit: {
      isEnable: { defaultValue: true | false, canEdit: true | false },
      limit: { defaultValue: 100, canEdit: true | false },
      color: { defaultValue: '#000000', canEdit: true | false },
      message: { defaultValue: '', canEdit: true | false },
      messageSize: { defaultValue: 12, canEdit: true | false },
    },
    lowerLimit: {
      isEnable: { defaultValue: true | false, canEdit: true | false },
      limit: { defaultValue: 0, canEdit: true | false },
      message: { defaultValue: '', canEdit: true | false },
      messageSize: { defaultValue: 12, canEdit: true | false },
    },
  },
}

Table Settings - Conditional Formatting

tableSettings: {
  conditionalFormatting: {
    defaultValue: [{ columnName: 'status', rules: [{ operator: '=', value: 'Active', styles: { backgroundColor: '#00FF00', color: '#000000', isApplyBgColor: true } }] }],
    canEdit: true | false,
  },
}

Table Settings - Number & Time Formatting

tableSettings: {
  isEnableNumberFormatting: { defaultValue: true | false, canEdit: true | false },
  tableNumberFormatter: {
    defaultValue: [{ columns: ['revenue'], formatter: '#,##0.00', suffix: 'K', prefix: '$' }],
    canEdit: true,
  },
  isEnableTimezoneFormatting: { defaultValue: true | false, canEdit: true | false },
  timeFormatter: { defaultValue: 'original' | 'yyyy-MM-dd' | 'yyyy/MM/dd' | 'dd-MM-yyyy' | 'dd/MM/yyyy' | 'dd MMM yyyy' | 'dd MMMM yyyy' | 'yyyy MMMM dd' | 'MMMM dd, yyyy' | 'yyyy-MM-dd, h:mm:ss a' | 'h:mm a', canEdit: true | false },
}

Metric Component (`dbn-metric`)

The metric component displays a single metric with customizable appearance and interactions.

Required Properties

string

required

Guest token for authentication.

string

required

Unique identifier for the metric to display.

Display Properties

string|number

default:"500"

Width of the metric component in pixels.

string|number

default:"300"

Height of the metric component in pixels.

string

default:"card"

Display variant. Options: card | fullscreen

string

default:"svg"

Chart rendering method. Options: svg | canvas

Behavior Options

Download & Export

boolean

default:"false"

Enables CSV download in metric card actions.

boolean

default:"false"

Enables email CSV option in metric card actions.

boolean

default:"false"

Disables PNG download in full screen mode.

UI Controls

boolean

default:"false"

Disables the full screen button.

boolean

default:"false"

Hides table preview in full screen view.

boolean

default:"false"

Hides chart settings in full screen view.

boolean

default:"false"

Disables access to underlying data.

boolean

default:"false"

Removes border from metric card.

boolean

default:"false"

Removes shadow from metric card.

boolean

default:"false"

Hides the metric card title.

boolean

default:"false"

Enables fullscreen mode when the metric title is clicked.

string

default:"kebab-menu-vertical"

Controls which options icon to display. Options: kebab-menu-vertical | download

boolean

default:"false"

Prevents downloading underlying data when no filters are applied.

boolean

default:"false"

Prevents downloading data when no filters are applied.

Filter Configuration

boolean

default:"false"

Allows multiple metric filters.

string

default:"inside"

Position of metric filters. Options: inside | outside

Configuration for metric-specific filters.

Show Filter Configuration

{
  "Filter name for a string datatype": {
    "options": [
      { "value": "James Smith", "label": "James" },
      { "value": "Olivia Johnson", "label": "Olivia" }
    ],
    "defaultOption": "James Smith"
  },
  "Filter name for a number datatype": {
    "options": [
      { "value": 1, "label": "Option 1" },
      { "value": 2, "label": "Option 2" }
    ],
    "defaultOption": 1
  },
  "Filter name for a date datatype": {
    "options": [
      {
        "range": "Last",
        "time": "Year", 
        "name": "Last 10 Years",
        "count": 10,
        "fromDate": "2023-01-01",
        "toDate": "2023-12-31"
      }
    ],
    "defaultOption": "Last 10 Years"
  }
}

Chart Appearance

object

Detailed chart styling configuration.

Show Chart Appearance Options

{
  chartTooltip?: {
    labelStyle?: {
      size?: number;
      family?: string;
      weight?: number;
      color?: string;
    };
    valueStyle?: {
      size?: number;
      family?: string;
      weight?: number;
      color?: string;
    };
    tooltipHeader?: {
      size?: number;
      family?: string;
      weight?: number;
      color?: string;
    };
  };
  chartLabel?: {
    position?: 'hidden' | 'top' | 'left' | 'right' | 'bottom' | 'inside';
    radialChartposition?: 'outside' | 'inside';
  };
  chartMargin?: {
    marginTop?: number;
    marginLeft?: number;
    marginRight?: number;
    marginBottom?: number;
  };
  chartLegend?: {
    show?: boolean;
    fixedPosition?:
      | 'top-left'
      | 'top-center'
      | 'top-right'
      | 'left-center'
      | 'right-center'
      | 'bottom-left'
      | 'bottom-center'
      | 'bottom-right';
    enableVariablePosition?: boolean;
    top?: number;
    left?: number;
    disableLegendScrolling?: boolean;
    legendAppearance?: 'horizontal' | 'vertical';
    truncateLegend?: number;
    legendShape?:
      | 'circle'
      | 'rect'
      | 'roundRect'
      | 'triangle'
      | 'diamond'
      | 'arrow'
      | 'none';
    fontSize?: number;
    fontWeight?: number;
    fontFamily?: string;
    color?: string;
  };
  verticalAxis?: {
    hideAxisLines?: boolean;
    hideSplitLines?: boolean;
    hideAxisLabels?: boolean;
    hideAxisTicks?: boolean;
    axisName?: string;
    axisNameOffset?: number;
    axisLabelMargin?: number;
    fontSize?: number;
    fontFamily?: string;
    fontWeight?: number;
    color?: string;
    axisColor?: string;
    axisNameFontConfig?: {
      fontFamily?: string;
      fontSize?: number;
      fontWeight?: number;
    };
  };
  horizontalAxis?: {
    hideAxisLines?: boolean;
    hideSplitLines?: boolean;
    hideAxisLabels?: boolean;
    hideAxisTicks?: boolean;
    axisName?: string;
    axisNameOffset?: number;
    axisLabelMargin?: number;
    fontSize?: number;
    fontFamily?: string;
    fontWeight?: number;
    color?: string;
    axisColor?: string;
    axisNameFontConfig?: {
      fontFamily?: string;
      fontSize?: number;
      fontWeight?: number;
    };
  };
};

object

Interactive appearance options for the metric.

Show Appearance Options

{
  "appearanceOptionsPosition": "top-right",
  "dynamicBehaviour": {
    "isEnabled": true,
    "label": "Dynamic"
  },
  "cumulativeBar": {
    "isEnabled": true,
    "label": "Cumulative"
  },
  "stackedBars": {
    "isEnabled": true,
    "label": "Stacked"
  }
}

Internationalization & Configuration

string

default:"en"

Language code for component localization (e.g., "fr", "es", "de").

object

Custom translation dictionary for metric text. Must be passed as JSON.stringify(...). See the dashboard Internationalization section for the full schema.

string

default:"default"

Calendar system to use. Options: default | ind

string

Name of a predefined theme from app settings UI theming.

object

Custom messages for component states. Must be passed as JSON.stringify(...).

Show Available Messages

{
  "tokenExpiry": "Your session has expired. Please refresh the page.",
  "tokenAbsent": "Authentication token is missing. Please log in again."
}

Pre-configured filter values for the metric. Must be passed as JSON.stringify(...). See the dashboard Global Filter Options section for the full schema.

object

Controls the appearance of metric long-description tooltips. Must be passed as JSON.stringify(...).

Show Long Description Config

{
  "width": "300px",
  "fontColor": "#333333"
}

object

Restricts which columns are available to end users for this metric. Must be passed as JSON.stringify(...).

Show Chart Columns Config

{
  "isEnabled": true,
  "dimensions": ["region", "category"],
  "measures": ["revenue", "profit"]
}

Event Callbacks

string

Name of global function to call when metric is minimized.

window.handleMetricMinimize = (metricId) => {
  console.log('Metric minimized:', metricId);
};

<dbn-metric 
  on-minimize="handleMetricMinimize"
  ...other-props
/>

Common Properties

These properties are available for both dashboard and metric components:

Styling & Customization

string

Inline CSS styles for the component.

string

CSS class name for custom styling.

array

Array of colors for chart elements.

["#FF6B6B", "#4ECDC4", "#45B7D1", "#96CEB4", "#FECA57"]

No Data Handling

string

SVG code as string to display when no data is available.

string

SVG code as string to display when no data is found in dashboard.

Date Picker Configuration

array

Array of date picker option labels to hide.

["this month", "yesterday", "last week"]

Usage Examples

Basic Dashboard
Customized Dashboard
Basic Metric
Advanced Metric

<dbn-dashboard 
  token="your-guest-token"
  dashboard-id="your-dashboard-id"
  enable-download-csv
  enable-email-csv
/>

<dbn-dashboard 
  token="your-guest-token"
  dashboard-id="your-dashboard-id"
  options={JSON.stringify({
    disableMetricCreation: false,
    showDashboardActions: true,
    chartColors: ["#FF6B6B", "#4ECDC4", "#45B7D1"],
    dashboardPadding: "16px 20px",
    ctaButtonCustomization: {
      primary: {
        styles: "background-color: #111827; color: #ffffff;",
        hoverStyles: "background-color: #374151;"
      }
    }
  })}
  theme={JSON.stringify({
    button: {
      primary: "#007bff",
      primaryText: "white"
    }
  })}
  custom-messages={JSON.stringify({
    tokenExpiry: "Session expired. Please refresh."
  })}
/>

<dbn-metric
  token="your-guest-token" 
  metric-id="your-metric-id"
  width="600"
  height="400"
  enable-download-csv
  chart-renderer-type="canvas"
/>

<dbn-metric
  token="your-guest-token"
  metric-id="your-metric-id"
  width="800"
  height="500"
  variant="card"
  enable-multi-metric-filters
  metric-filter-position="outside"
  chart-appearance={JSON.stringify({
    chartLegend: {
      show: true,
      fixedPosition: "bottom-center"
    },
    chartTooltip: {
      labelStyle: {
        size: 16,
        family: "Arial",
        weight: 600
      }
    }
  })}
/>

Frequently Asked Questions

How do I pass props dynamically or re-render components on prop changes?

Web components don’t automatically re-render when properties change. Here are several approaches:Method 1: Force Re-render with Key

const [componentKey, setComponentKey] = useState(0);
const [token, setToken] = useState(initialToken);

// When updating props
const updateProps = (newToken) => {
  setToken(newToken);
  setComponentKey(prev => prev + 1); // Force re-render
};

return (
  <dbn-dashboard 
    key={componentKey}
    token={token}
    dashboard-id="your-dashboard-id"
  />
);

Method 2: Loading State Approach

const [isLoading, setIsLoading] = useState(false);
const [token, setToken] = useState(initialToken);

const updateToken = async (newToken) => {
  setIsLoading(true);
  // Brief delay to ensure component unmounts
  await new Promise(resolve => setTimeout(resolve, 100));
  setToken(newToken);
  setIsLoading(false);
};

return (
  <>
    {isLoading ? (
      <div>Loading...</div>
    ) : (
      <dbn-dashboard token={token} dashboard-id="your-dashboard-id" />
    )}
  </>
);

Why are my custom colors not applying to charts?

This usually happens due to incorrect format or timing. Here are common solutions:Ensure Proper Format:

// ✅ Correct - Array of hex colors
const chartColors = ["#FF6B6B", "#4ECDC4", "#45B7D1", "#96CEB4"];

// ❌ Incorrect - Invalid color format
const chartColors = ["red", "blue"]; // Use hex codes instead

Use JSON.stringify for Complex Objects:

<!-- ✅ Correct -->
<dbn-dashboard 
  chart-colors={JSON.stringify(["#FF6B6B", "#4ECDC4"])}
  options={JSON.stringify({
    chartColors: ["#FF6B6B", "#4ECDC4"]
  })}
/>

<!-- ❌ Incorrect -->
<dbn-dashboard chart-colors={["#FF6B6B", "#4ECDC4"]} />

Check CSS Specificity:

/* Your custom colors might be overridden */
.your-dashboard-container {
  --chart-color-1: #FF6B6B !important;
  --chart-color-2: #4ECDC4 !important;
}

How do I handle authentication token expiry?

Set Up Custom Messages:

<dbn-dashboard 
  token={token}
  dashboard-id="your-dashboard-id"
  custom-messages={JSON.stringify({
    tokenExpiry: "Your session has expired. Redirecting to login...",
    tokenAbsent: "Please log in to view this dashboard."
  })}
  handle-server-event="handleAuthError"
/>

Handle Server Events:

// Define globally accessible function
window.handleAuthError = (event) => {
  if (event.type === 'TOKEN_EXPIRED') {
    // Redirect to login or refresh token
    window.location.href = '/login';
  }
};

Automatic Token Refresh:

const useTokenRefresh = () => {
  const [token, setToken] = useState(null);
  
  useEffect(() => {
    const refreshToken = async () => {
      try {
        const response = await fetch('/api/refresh-token');
        const { token: newToken } = await response.json();
        setToken(newToken);
      } catch (error) {
        console.error('Token refresh failed:', error);
      }
    };
    
    // Refresh token every 50 minutes (assuming 1-hour expiry)
    const interval = setInterval(refreshToken, 50 * 60 * 1000);
    refreshToken(); // Initial call
    
    return () => clearInterval(interval);
  }, []);
  
  return token;
};

How do I customize the appearance of filters and date pickers?

Hide Specific Date Picker Options:

<dbn-dashboard 
  hide-date-picker-options={JSON.stringify([
    "yesterday", 
    "last week", 
    "this month"
  ])}
/>

Custom Filter Styling:

<dbn-dashboard 
  theme={JSON.stringify({
    multiSelectFilterDropdown: {
      badgeColor: "#007bff",
      badgeTextColor: "white"
    }
  })}
  admin-theme-options={JSON.stringify({
    dashboard: {
      selectBoxSize: "large",
      selectBoxVariant: "floating",
      selectBoxBorderRadius: "8px",
      selectBoxTextColor: "#333"
    }
  })}
/>

Global Filter Configuration:

const globalFilters = {
  "Region": {
    options: [
      { value: "north", label: "North America" },
      { value: "europe", label: "Europe" },
      { value: "asia", label: "Asia Pacific" }
    ],
    defaultOption: "north"
  },
  "Date Range": {
    defaultOption: { startDate: "2024-01-01", endDate: "2024-12-31" },
    datePresetOptions: [
      {
        type: "last",
        interval: 30,
        timeGrain: "day",
        label: "Last 30 Days"
      }
    ]
  }
};

Why is my dashboard not loading or showing blank?

Common Causes & Solutions:

Invalid Token:

// Check token validity
const validateToken = async (token) => {
  try {
    const response = await fetch('/api/validate-token', {
      headers: { Authorization: `Bearer ${token}` }
    });
    return response.ok;
  } catch (error) {
    console.error('Token validation failed:', error);
    return false;
  }
};

Incorrect Dashboard ID:

// Verify dashboard exists
const checkDashboard = async (dashboardId) => {
  try {
    const response = await fetch(`/api/dashboards/${dashboardId}`);
    return response.ok;
  } catch (error) {
    console.error('Dashboard check failed:', error);
    return false;
  }
};

Missing Import:

// Ensure web components are imported
import '@databrainhq/plugin/web';

// For TypeScript, add declarations
declare global {
  namespace JSX {
    interface IntrinsicElements {
      'dbn-dashboard': any;
      'dbn-metric': any;
    }
  }
}

Network/CORS Issues:

// Check browser console for CORS errors
// Ensure your backend allows requests from your domain

How do I implement multi-tenant access control?

Client-Side Implementation:

const DashboardWithTenancy = ({ userId, tenantId }) => {
  const [token, setToken] = useState(null);
  
  useEffect(() => {
    const fetchTenantToken = async () => {
      const response = await fetch('/api/guest-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ 
          clientId: userId,
          tenantId: tenantId,
          dataAppName: 'your-app-name'
        })
      });
      const { token } = await response.json();
      setToken(token);
    };
    
    fetchTenantToken();
  }, [userId, tenantId]);
  
  if (!token) return <div>Loading...</div>;
  
  return (
    <dbn-dashboard 
      token={token}
      dashboard-id="tenant-specific-dashboard"
    />
  );
};

Backend Token Generation:

// Node.js example
app.post('/api/guest-token', async (req, res) => {
  const { clientId, tenantId, dataAppName } = req.body;
  
  try {
    const response = await fetch('https://api.usedatabrain.com/api/v2/guest-token/create', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.DATABRAIN_API_TOKEN}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        clientId: `${tenantId}_${clientId}`, // Prefix with tenant
        dataAppName: dataAppName
      })
    });
    
    const data = await response.json();
    res.json({ token: data.token });
  } catch (error) {
    res.status(500).json({ error: 'Token generation failed' });
  }
});

How do I optimize performance for large dashboards?

Enable Canvas Rendering:

<dbn-metric 
  chart-renderer-type="canvas"
  token={token}
  metric-id="large-dataset-metric"
/>

Disable Heavy Features:

<dbn-dashboard 
  options={JSON.stringify({
    disableMainLoader: true,
    disableMetricLoader: true,
    shouldFitFullScreen: true,
    disableUnderlyingData: true
  })}
/>

Lazy Loading Implementation:

const LazyDashboard = ({ dashboardId }) => {
  const [isVisible, setIsVisible] = useState(false);
  const ref = useRef();
  
  useEffect(() => {
    const observer = new IntersectionObserver(
      ([entry]) => {
        if (entry.isIntersecting) {
          setIsVisible(true);
          observer.disconnect();
        }
      },
      { threshold: 0.1 }
    );
    
    if (ref.current) observer.observe(ref.current);
    return () => observer.disconnect();
  }, []);
  
  return (
    <div ref={ref}>
      {isVisible ? (
        <dbn-dashboard 
          token={token}
          dashboard-id={dashboardId}
        />
      ) : (
        <div>Loading dashboard...</div>
      )}
    </div>
  );
};

How do I handle different screen sizes and responsive design?

Responsive Width/Height:

const ResponsiveMetric = () => {
  const [dimensions, setDimensions] = useState({ width: 500, height: 300 });
  
  useEffect(() => {
    const handleResize = () => {
      const container = document.getElementById('metric-container');
      if (container) {
        setDimensions({
          width: container.offsetWidth,
          height: Math.min(container.offsetWidth * 0.6, 400)
        });
      }
    };
    
    window.addEventListener('resize', handleResize);
    handleResize(); // Initial call
    
    return () => window.removeEventListener('resize', handleResize);
  }, []);
  
  return (
    <div id="metric-container">
      <dbn-metric 
        token={token}
        metric-id="responsive-metric"
        width={dimensions.width}
        height={dimensions.height}
      />
    </div>
  );
};

CSS Media Queries:

.dashboard-container {
  width: 100%;
  max-width: 1200px;
  margin: 0 auto;
}

@media (max-width: 768px) {
  .dashboard-container {
    padding: 10px;
  }
  
  dbn-dashboard {
    --metric-card-padding: 8px;
    --font-size-small: 12px;
  }
}

@media (max-width: 480px) {
  dbn-dashboard {
    --chart-height: 200px;
    --hide-chart-legend: true;
  }
}

Mobile-Specific Options:

const isMobile = window.innerWidth < 768;

const mobileOptions = {
  hideMetricCardShadow: true,
  shouldFitFullScreen: true,
  chartAppearance: {
    chartLegend: { show: false },
    chartMargin: { marginTop: 5, marginLeft: 5, marginRight: 5, marginBottom: 5 }
  }
};

<dbn-dashboard 
  options={JSON.stringify(isMobile ? mobileOptions : desktopOptions)}
/>

How do I implement custom error handling and logging?

Global Error Handler:

window.databrainErrorHandler = (error) => {
  // Log to your analytics service
  analytics.track('Databrain Error', {
    error: error.message,
    component: error.component,
    timestamp: new Date().toISOString()
  });
  
  // Show user-friendly message
  if (error.type === 'NETWORK_ERROR') {
    showToast('Connection issue. Please check your internet connection.');
  } else if (error.type === 'AUTH_ERROR') {
    redirectToLogin();
  } else {
    showToast('Something went wrong. Please try again.');
  }
};

Component-Level Error Boundaries:

class DashboardErrorBoundary extends React.Component {
  constructor(props) {
    super(props);
    this.state = { hasError: false, error: null };
  }
  
  static getDerivedStateFromError(error) {
    return { hasError: true, error };
  }
  
  componentDidCatch(error, errorInfo) {
    console.error('Dashboard Error:', error, errorInfo);
    // Log to error reporting service
  }
  
  render() {
    if (this.state.hasError) {
      return (
        <div className="error-fallback">
          <h3>Dashboard temporarily unavailable</h3>
          <button onClick={() => this.setState({ hasError: false })}>
            Try Again
          </button>
        </div>
      );
    }
    
    return this.props.children;
  }
}

// Usage
<DashboardErrorBoundary>
  <dbn-dashboard token={token} dashboard-id="dashboard-id" />
</DashboardErrorBoundary>

How do I customize chart tooltips and legends?

Advanced Tooltip Customization:

const tooltipConfig = {
  chartTooltip: {
    labelStyle: {
      size: 16,
      family: "Arial, sans-serif",
      weight: 600,
      color: "#2c3e50"
    },
    valueStyle: {
      size: 14,
      family: "Arial, sans-serif", 
      weight: 400,
      color: "#34495e"
    }
  }
};

Legend Positioning:

const legendConfig = {
  chartLegend: {
    show: true,
    fixedPosition: "bottom-center", // or use enableVariablePosition
    enableVariablePosition: false,
    legendAppearance: "horizontal",
    truncateLegend: 30,
    legendShape: "roundRect",
    fontSize: 12,
    fontWeight: 500,
    fontFamily: "Inter, sans-serif",
    color: "#2c3e50",
    disableLegendScrolling: false
  }
};

Complete Chart Appearance:

<dbn-metric 
  enable-title-click-fullscreen={true}
  chart-appearance={JSON.stringify({
    ...tooltipConfig,
    ...legendConfig,
    chartLabel: {
      position: "top",
      radialChartposition: "outside"
    },
    chartMargin: {
      marginTop: 20,
      marginLeft: 20,
      marginRight: 20,
      marginBottom: 40
    },
    verticalAxis: {
      hideAxisLines: false,
      hideSplitLines: true,
      hideAxisLabels: false,
      axisName: "Revenue ($)",
      axisLabelMargin: 0,
      fontSize: 12,
      fontFamily: "Inter"
    },
    horizontalAxis: {
      hideAxisLines: false,
      hideSplitLines: true,
      hideAxisLabels: false,
      axisName: "Time Period",
      axisLabelMargin: 0,
      fontSize: 12,
      fontFamily: "Inter"
    }
  })}
/>

Migration & Updates

When updating from older versions, note that some property names may have changed. Always refer to this reference for the latest property names and structures.

For dynamic property updates, web components don’t automatically re-render. Consider using a loading state and temporarily hiding/showing the component when updating properties.

Troubleshooting Quick Reference

Component Not Rendering

✅ Check if @databrainhq/plugin/web is imported
✅ Verify token is valid and not expired
✅ Confirm dashboard-id/metric-id exists
✅ Check browser console for errors
✅ Ensure CORS is properly configured

Styling Issues

✅ Use JSON.stringify() for object props
✅ Check CSS specificity conflicts
✅ Verify color format (use hex codes)
✅ Test with !important to identify overrides

Performance Issues

✅ Enable canvas rendering for large datasets
✅ Disable unnecessary features (loaders, underlying data)
✅ Implement lazy loading for multiple components
✅ Use shouldFitFullScreen for better performance

Need More Help?

Check our comprehensive troubleshooting guide for additional solutions

Interactive Demo

​Understanding the Configuration Layers

​Dashboard Component (dbn-dashboard)

​Required Properties

​Display & Layout Options

​Advanced Configuration

​Additional Dashboard Properties

​Per-Metric Chart Settings

​Internationalization

​Event Handling

​Custom Chart Click Action

​Custom Messages

​Custom Chart Settings Reference

​Field Name Mapping

​Metric Component (dbn-metric)

​Required Properties

​Display Properties

​Behavior Options

​Filter Configuration

​Chart Appearance

​Internationalization & Configuration

​Event Callbacks

​Common Properties

​Styling & Customization

​No Data Handling

​Date Picker Configuration

​Usage Examples

​Frequently Asked Questions

​Migration & Updates

​Troubleshooting Quick Reference

Need More Help?

Understanding the Configuration Layers

Dashboard Component (`dbn-dashboard`)

Required Properties

Display & Layout Options

Advanced Configuration

Additional Dashboard Properties

Per-Metric Chart Settings

Internationalization

Event Handling

Custom Chart Click Action

Custom Messages

Custom Chart Settings Reference

Field Name Mapping

Metric Component (`dbn-metric`)

Required Properties

Display Properties

Behavior Options

Filter Configuration

Chart Appearance

Internationalization & Configuration

Event Callbacks

Common Properties

Styling & Customization

No Data Handling

Date Picker Configuration

Usage Examples

Frequently Asked Questions

Migration & Updates

Troubleshooting Quick Reference