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

token

string

required

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

dashboard-id

string

required

Unique identifier for the dashboard to display.

Display & Layout Options

Basic Display Controls

is-hide-table-preview

boolean

default:"false"

Hides the table preview in full screen view.

is-hide-chart-settings

boolean

default:"false"

Hides chart settings in full screen view.

disable-fullscreen

boolean

default:"false"

Disables the full screen option for the dashboard.

enable-title-click-fullscreen

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.

options-icon

string

default:"kebab-menu-vertical"

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

is-sticky-dashboard-filters

boolean

default:"false"

Makes dashboard filters sticky at the top when scrolling.

settings-icon

object

Controls the visibility and configuration of the settings icon.

Settings Icon Configuration

{
  name: 'random',
  iconSvg: 'svg',
}

Download & Export Options

enable-download-csv

boolean

default:"false"

Enables CSV download option in metric card actions.

enable-email-csv

boolean

default:"false"

Enables email CSV option in metric card actions.

disable-download-png

boolean

default:"false"

Disables PNG download option in full screen mode.

enable-download-all-metrics

boolean

default:"false"

Enables download option for all metrics at once.

enable-download-all-pdf

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,
  "disableSaveLayout": false,
  "disableScheduleEmailReports": false,
  "disableManageMetrics": false,
  "disableMainLoader": false,
  "disableMetricLoader": false,
  "hideDashboardName": false,
  "hideMetricCardShadow": false,
  "showDashboardActions": true,
  "disableUnderlyingData": false,
  "shouldFitFullScreen": false,
  "isModifyUrl": false,
  "exportMsgPosition": "bottom"
}

disableDownloadDataNoFilters

boolean

default:"false"

Prevents downloading data when no filters are applied.

disableDownloadUnderlyingDataNoFilters

boolean

default:"false"

Prevents downloading underlying data when no filters are applied.

isShowNoDataFoundScreen

boolean

default:"false"

Shows a custom screen when no data is available.

disableMetricCreation

boolean

default:"false"

Disables the ability to create new metrics.

disableMetricUpdation

boolean

default:"false"

Disables the ability to update existing metrics.

showDashboardActions

boolean

default:"true"

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

shouldFitFullScreen

boolean

default:"false"

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

isModifyUrl

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.

exportMsgPosition

string

default:"bottom"

chartColors

array

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

Show Example

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

chartPaletteOptions

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"]
  }
]

chartAppearance

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,
    },
  },
  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,
    },
  },
}

Global Filter Options

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"
  }
}

Theme Configuration

theme

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"
  }
}

theme-name

string

Name of a predefined theme from app settings UI theming.

Admin Theme Options

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"
  },
  "cardDescription": {
    "fontSize": "12px",
    "fontWeight": "400",
    "color": "#666666"
  },
  "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"
  }
}

general.name

string

Name of the theme.

general.fontFamily

string

Global font family applied to the dashboard.

general.datePickerFormat

string

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

dashboard.backgroundColor

string

Background color of the dashboard container.

dashboard.ctaColor

string

Primary call-to-action button color.

dashboard.ctaTextColor

string

Text color for call-to-action buttons.

dashboard.selectBoxSize

string

default:"medium"

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

dashboard.selectBoxVariant

string

default:"floating"

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

dashboard.selectBoxBorderRadius

string

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

dashboard.selectBoxTextColor

string

Text color for filter select boxes.

dashboard.metricCardColor

string

Background color of individual metric cards.

cardTitle.fontSize

string

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

cardTitle.fontWeight

string

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

cardTitle.color

string

Text color of metric card titles.

cardDescription.fontSize

string

Font size of metric card descriptions.

cardDescription.fontWeight

string

Font weight of metric card descriptions.

cardDescription.color

string

Text color of metric card descriptions.

chart.palettes

array

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

chart.paletteOptions

array

Array of palette name strings available for selection.

chart.selected

string

Name of the currently selected palette.

chart.fontFamily

string

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

chart.fontColor

string

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

chart.letterSpacing

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.

cardCustomization.padding

string

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

cardCustomization.borderRadius

string

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

cardCustomization.shadow

string

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

cardCustomization.disableShadowOnHover

boolean

default:"false"

Disables the shadow effect when hovering over metric cards.

cardCustomization.disableStroke

boolean

default:"false"

Disables the border stroke around metric cards.

cardCustomization.metricStrokeColor

string

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

Additional Dashboard Properties

long-description-config

object

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

Show Long Description Config

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

chart-columns

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

custom-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 }
  }
}

Internationalization

language

string

default:"en"

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

translation-dictionary

object

Custom translation dictionary for component text.

Show Translation Example

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

calendar-type

string

default:"default"

Calendar system to use. Options: default | ind

Event Handling

handle-server-event

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
};

Custom Chart Click Action

chart-click-function

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
};

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

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: {
  show:{ defaultValue: true | false, canEdit: true | false },
  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 },
    },
  },
}

Tooltip Settings

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 },
  },
}

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

token

string

required

Guest token for authentication.

metric-id

string

required

Unique identifier for the metric to display.

Display Properties

width

string|number

default:"500"

Width of the metric component in pixels.

height

string|number

default:"300"

Height of the metric component in pixels.

variant

string

default:"card"

Display variant. Options: card | fullscreen

chart-renderer-type

string

default:"svg"

Chart rendering method. Options: svg | canvas

Behavior Options

Download & Export

enable-download-csv

boolean

default:"false"

Enables CSV download in metric card actions.

enable-email-csv

boolean

default:"false"

Enables email CSV option in metric card actions.

disable-download-png

boolean

default:"false"

Disables PNG download in full screen mode.

UI Controls

disable-fullscreen

boolean

default:"false"

Disables the full screen button.

is-hide-table-preview

boolean

default:"false"

Hides table preview in full screen view.

is-hide-chart-settings

boolean

default:"false"

Hides chart settings in full screen view.

disable-underlying-data

boolean

default:"false"

Disables access to underlying data.

disable-metric-card-border

boolean

default:"false"

Removes border from metric card.

hide-metric-card-shadow

boolean

default:"false"

Removes shadow from metric card.

is-disable-card-title

boolean

default:"false"

Hides the metric card title.

enable-title-click-fullscreen

boolean

default:"false"

Enables fullscreen mode when the metric title is clicked.

options-icon

string

default:"kebab-menu-vertical"

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

disable-download-underlying-data-no-filters

boolean

default:"false"

Prevents downloading underlying data when no filters are applied.

disable-download-data-no-filters

boolean

default:"false"

Prevents downloading data when no filters are applied.

Filter Configuration

enable-multi-metric-filters

boolean

default:"false"

Allows multiple metric filters.

metric-filter-position

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

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;
    };
  };
};

appearance-options

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

language

string

default:"en"

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

translation-dictionary

object

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

calendar-type

string

default:"default"

Calendar system to use. Options: default | ind

theme-name

string

Name of a predefined theme from app settings UI theming.

custom-messages

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.

long-description-config

object

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

Show Long Description Config

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

chart-columns

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

on-minimize

string

Name of global function to call when metric is minimized.

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

Common Properties

These properties are available for both dashboard and metric components:

Styling & Customization

style

string

Inline CSS styles for the component.

class-name

string

CSS class name for custom styling.

chart-colors

array

Array of colors for chart elements.

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

No Data Handling

no-data-img

string

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

no-data-found-svg

string

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

Date Picker Configuration

hide-date-picker-options

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"]
  })}
  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

Embedding Setup

MCP Server

Framework Integration

Component Options

Authentication & Security

Filtering & Personalization

Customization

Events & Interactions

End-User Features

AI Chat Mode

Self-Hosted Deployment

Solution Patterns

Testing & Debugging

Migration & Legacy

Additional Resources

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