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.

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,
  "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.

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

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

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

customSettings: {
  numberFormatter: { defaultValue: '', canEdit: true | false },
  isEnableLabelFormatting: { defaultValue: true | false, canEdit: true | false },
  isEnableCustomLimits: { defaultValue: true | false, canEdit: true | false },
  isEnableDynamicLimits: { defaultValue: true | false, canEdit: true | false },
  isEnableLogScale: { 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 },
  customUppperLimit: { 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 },
  subHeaderShow: { defaultValue: true | false, canEdit: true | false },
  displayText: { defaultValue: '', canEdit: true | false },
  subHeaderAlignment: { defaultValue: 'center', canEdit: true | false },
  isEnableLabelTooltip: { defaultValue: true | false, canEdit: true | false },
  showFullStacked: { defaultValue: true | false, canEdit: true | false },
  isEnableMeasureMode: { defaultValue: true | false, canEdit: true | false },
  cumulativeBar: { defaultValue: true | false, canEdit: true | false },
  enableTitleDesc: { defaultValue: true | false, canEdit: true | false },
  chartTitle: { defaultValue: '', canEdit: true | false },
  chartDesc: { defaultValue: '', canEdit: true | false },
  titlePosition: { defaultValue: 'top', canEdit: true | false },
  labelPrefix: { defaultValue: '', canEdit: true | false },
  labelSuffix: { defaultValue: '', canEdit: true | false },
  barWidth: { defaultValue: 20, canEdit: true | false },
  barRadius: { defaultValue: [0, 0, 0, 0], canEdit: true | false },
  YaxislabelFormatters: {
    defaultValue: [{ upperLimit: 1000, lowerLimit: 0, label: 'Low', color: '#00FF00' }],
    canEdit: true | false,
  },
  singleValConditionalFormatter: {
    defaultValue: [{ type: 'range', min: 0, max: 100, color: '#00FF00' }],
    canEdit: true | false,
  },
  comboAxisSettings: {
    defaultValue: [{ axis: 'left', measures: ['revenue'], chartTypes: [{ axis: 'left', type: 'bar' }] }],
    canEdit: true | false,
  },
  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 },
  },
  chartZoom: {
    isZoomEnabled: { defaultValue: true | false, canEdit: true | false },
    zoomAxis: { defaultValue: 'x', canEdit: true | false },
  },
  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

tableSettings: {
  conditionalFormatting: {
    defaultValue: [{ columnName: 'status', rules: [{ operator: '=', value: 'Active', styles: { backgroundColor: '#00FF00', color: '#000000', isApplyBgColor: true } }] }],
    canEdit: true | false,
  },
  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.

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

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 
  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 ($)",
      fontSize: 12,
      fontFamily: "Inter"
    },
    horizontalAxis: {
      hideAxisLines: false,
      hideSplitLines: true,
      hideAxisLabels: false,
      axisName: "Time Period",
      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

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

​Dashboard Component (dbn-dashboard)

​Required Properties

​Display & Layout Options

​Advanced Configuration

​Per-Metric Chart Settings

​Internationalization

​Event Handling

​Custom Chart Click Action

​Custom Messages

​Custom Chart Settings Reference

​Metric Component (dbn-metric)

​Required Properties

​Display Properties

​Behavior Options

​Filter Configuration

​Chart Appearance

​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?

Dashboard Component (`dbn-dashboard`)

Required Properties

Display & Layout Options

Advanced Configuration

Per-Metric Chart Settings

Internationalization

Event Handling

Custom Chart Click Action

Custom Messages

Custom Chart Settings Reference

Metric Component (`dbn-metric`)

Required Properties

Display Properties

Behavior Options

Filter Configuration

Chart Appearance

Event Callbacks

Common Properties

Styling & Customization

No Data Handling

Date Picker Configuration

Usage Examples

Frequently Asked Questions

Migration & Updates

Troubleshooting Quick Reference