Options

This page contains raw component examples. For a comprehensive, organized reference with detailed explanations, see our Component Options Reference.

Databrain Demo - StackBlitz

StackBlitz

📚 Component Options Reference

View the comprehensive, organized reference guide with detailed explanations, examples, and best practices for all component options.

Dashboard Component

<dbn-dashboard
  token="guest-token"
  dashboard-id="dashboardId"
  is-hide-table-preview
  is-hide-chart-settings
  enable-download-csv
  enable-email-csv
  disable-download-png
  options-icon="kebab-menu-vertical | download"
  enable-multi-metric-filters
  enable-download-all-metrics
  enable-download-all-pdf
  custom-messages={JSON.stringify({
    tokenExpiry: "Some custom message you want to show here.",
    tokenAbsent: "Some custom message you want to show here.",
  })}
  no-data-img="image svg path"
  no-data-found-svg="image svg path"
  handle-server-event="functionName"
  global-filter-options={JSON.stringify({
    "Filter name for a string datatype": {
      options: [
        { value: "James Smith", label: "James" },
        { value: "Olivia Johnson", label: "Olivia" },
        { value: "Emma Brown", label: "Emma" },
      ],
      defaultOption: "James Smith",
    },
    "Filter name for a number datatype": {
      defaultOption: { min: 100, max: 900 },
    },
    "Filter name for a date datatype": {
      defaultOption: { startDate: "2024-01-01", endDate: "2024-12-31" },
      datePresetOptions: [
        {
          type: "this",
          interval: 1,
          timeGrain: "month",
          label: "this month",
          startDate: new Date(),
          endDate: new Date(),
        },
      ],
    },
  })}
  options={JSON.stringify({
    disableDownloadDataNoFilters: true,
    disableDownloadUnderlyingDataNoFilters: true,
    isShowNoDataFoundScreen: true,
    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,
    hideDatePickerOptions: ["this month", "yesterday", "..."],
    chartColors: ["red", "blue", "orange", "..."],
    chartAppearance: {
      chartTooltip: {
        labelStyle: {
          size: 14,
          family: "Inter",
          weight: 400,
          color: "#000000",
        },
        valueStyle: {
          size: 14,
          family: "Inter",
          weight: 400,
          color: "#000000",
        },
        tooltipHeader: {
          size: 14,
          family: "Inter",
          weight: 400,
          color: "#000000",
        },
      },
      chartLabel: {
        position: "hidden",
        radialChartposition: "outside",
      },
      chartMargin: {
        marginTop: 15,
        marginLeft: 15,
        marginRight: 15,
        marginBottom: 15,
      },
      chartLegend: {
        show: true,
        fixedPosition: "top-left",
        enableVariablePosition: false,
        top: 15,
        left: 15,
        disableLegendScrolling: true,
        legendAppearance: "horizontal",
        truncateLegend: 22,
        legendShape: "circle",
        fontSize: 14,
        fontWeight: 400,
        fontFamily: "Inter",
        color: "#000000",
      },
      verticalAxis: {
        hideAxisLines: false,
        hideSplitLines: false,
        hideAxisLabels: false,
        hideAxisTicks: false,
        axisName: "axisName",
        axisNameOffset: 20,
        fontSize: 14,
        fontFamily: "Inter",
        fontWeight: 400,
        color: "#000000",
        axisColor: "#000000",
        axisNameFontConfig: {
          fontFamily: "Inter",
          fontSize: 14,
          fontWeight: 400,
        },
      },
      horizontalAxis: {
        hideAxisLines: false,
        hideSplitLines: false,
        hideAxisLabels: false,
        hideAxisTicks: false,
        axisName: "axisName",
        axisNameOffset: 20,
        fontSize: 14,
        fontFamily: "Inter",
        fontWeight: 400,
        color: "#000000",
        axisColor: "#000000",
        axisNameFontConfig: {
          fontFamily: "Inter",
          fontSize: 14,
          fontWeight: 400,
        },
      },
    },
  })}
  manageMetricsBtnContent={() => {
    return <div>content</div>;
  }}
  long-description-config={JSON.stringify({
    width: "",
    fontColor: "",
  })}
  disable-fullscreen
  admin-theme-options={JSON.stringify({
    general: {
      name: "themeName",
      fontFamily: "font family like sans, roboto etc",
      datePickerFormat: "format",
    },
    dashboard: {
      backgroundColor: "red",
      ctaColor: "blue",
      ctaTextColor: "blue",
      selectBoxSize: "small",
      selectBoxVariant: "floating",
      selectBoxBorderRadius: "20px",
      selectBoxTextColor: "red",
    },
    cardDescription: {
      fontSize: "10px",
      fontWeight: "400",
      color: "red",
    },
    cardTitle: {
      fontSize: "20px",
      fontWeight: "400",
      color: "red",
    },
    chart: {
      palettes: [
        {
          name: "pallete name",
          colors: ["red", "blue", "green"],
        },
      ],
      selected: "selected pallete name",
      chartFontFamily: "roboto",
      chartFontColor: "red",
      chartLetterSpacing: "12px",
      tooltip: {
        header: {
          fontFamily: "roboto",
          fontSize: "12px",
          fontWeight: "bold",
          fontColor: "red",
        },
        label: {
          fontFamily: "roboto",
          fontSize: "12px",
          fontWeight: "bold",
          fontColor: "red",
        },
        value: {
          fontFamily: "roboto",
          fontSize: "12px",
          fontWeight: "bold",
          fontColor: "red",
        },
      },
    },
    cardCustomization: {
      padding: "20px",
      borderRadius: "10px",
      shadow: "0px 10px 10px 0px rgba(13, 13, 13, 0.05)",
      disableShadowOnHover: true,
      disableStroke: true,
      metricStrokeColor: "blue",
    },
  })}
  theme-name="Name of the theme you want to apply from app settings ui theming"
  chart-columns={JSON.stringify([
    {
      isEnabled: true,
      metricId: "comparison_filter89",
      dimensions: ["name"],
      measures: ["count of order_id"],
    },
  ])}
  hide-dashboard-filters={JSON.stringify(["workspace"])}
  theme={JSON.stringify({
    button: {
      primaryText: "white",
      primary: "red",
      secondaryText: "black",
      secondary: "white",
    },
    checkbox: {
      checked: "orange",
      unChecked: "blue",
    },
    switch: {
      enabled: "orange",
      disabled: "blue",
    },
    drillBreadCrumbs: {
      fontFamily: "clash grotesk",
      fontColor: "black",
      activeColor: "red",
    },
    multiSelectFilterDropdown: {
      badgeColor: "blue",
      badgeTextColor: "black",
    },
  })}
  translation-dictionary={JSON.stringify({
    "total sales": {
      en: "total sales",
      fr: "ventes totales",
      es: "ventas totales",
      de: "Gesamtumsatz",
      it: "vendite totali",
      pt: "vendas totais",
      zh: "总销售额",
      ja: "総売上",
      ko: "총 매출",
      hi: "कुल बिक्री",
      ar: "إجمالي المبيعات",
      ru: "общие продажи",
    },
  })}
  language="fr"
  calendar-type="ind"
/>;

Metric Component

<dbn-metric
  token={guest-token}
  metric-id={metricId}
  width={500}
  height={300}
  style={style}
  class-name={className}
  disable-download-data-no-filters // in full screen view defaults to false
  disable-download-underlying-data-no-filters 
  is-hide-table-preview // in full screen view defaults to false
  is-hide-chart-settings // in full screen view defaults to false
  enable-download-csv // in metric card more icon actions defaults to false
  enable-email-csv // in metric card more icon actions defaults to false
  disable-download-png // in full screen mode, the save as png option in download section will be disabled
  options-icon="kebab-menu-vertical | download" // one of the options defaults to kebab-menu-vertical
  enable-multi-metric-filters // in metric card allow multiple metric filters
  custom-messages={JSON.stringify({
      "tokenExpiry": "Some custom message you want to show here.",
      "tokenAbsent": "Some custom message you want to show here."
  })} // optional all keys as well
  hide-metric-card-shadow={false} // optional - false by default
  no-data-img="image svg path" // pass the svg code in form of string to display when no data is there
  variant: 'card' | 'fullscreen' // optional, by default it is card
  on-minimize="functionName" // define function in global object and add the name here
  chart-renderer-type: 'svg' | 'canvas' // optional render type
  metric-filter-position: 'outside' | 'inside' // optional, specify the position for the metric filters
  disable-fullscreen // option to disable the full screen button
  disable-underlying-data={false} // optional - false by default
  disable-metric-card-border // optional - false by default
  isMergedCard // optional - false by default, it is used when you want to show merged metrics together
  hide-date-picker-options: ['this month', 'yesterday', '...'] // array of string which includes the label names for the date picker options that you want to hide
  chart-appearance: {JSON.stringify({
  "chartTooltip": {
    "labelStyle": {
      "size": 14,
      "family": "Inter",
      "weight": 400,
      "color": "#000000"
    },
    "valueStyle": {
      "size": 14,
      "family": "Inter",
      "weight": 400,
      "color": "#000000"
    },
    "tooltipHeader": {
      "size": 14,
      "family": "Inter",
      "weight": 400,
      "color": "#000000"
    }
  },
  "chartLabel": {
    "position": "hidden",
    "radialChartposition": "outside"
  },
  "chartMargin": {
    "marginTop": 15,
    "marginLeft": 15,
    "marginRight": 15,
    "marginBottom": 15
  },
  "chartLegend": {
    "show": true,
    "fixedPosition": "top-left",
    "enableVariablePosition": false,
    "top": 15,
    "left": 15,
    "disableLegendScrolling": true,
    "legendAppearance": "horizontal",
    "truncateLegend": 22,
    "legendShape": "circle",
    "fontSize": 14,
    "fontWeight": 400,
    "fontFamily": "Inter",
    "color": "#000000"
  },
  "verticalAxis": {
    "hideAxisLines": false,
    "hideSplitLines": false,
    "hideAxisLabels": false,
    "hideAxisTicks": false,
    "axisName": "axisName",
    "axisNameOffset": 20,
    "fontSize": 14,
    "fontFamily": "Inter",
    "fontWeight": 400,
    "color": "#000000",
    "axisColor": "#000000",
    "axisNameFontConfig": {
      "fontFamily": "Inter",
      "fontSize": 14,
      "fontWeight": 400
    }
  },
  "horizontalAxis": {
    "hideAxisLines": false,
    "hideSplitLines": false,
    "hideAxisLabels": false,
    "hideAxisTicks": false,
    "axisName": "axisName",
    "axisNameOffset": 20,
    "fontSize": 14,
    "fontFamily": "Inter",
    "fontWeight": 400,
    "color": "#000000",
    "axisColor": "#000000",
    "axisNameFontConfig": {
      "fontFamily": "Inter",
      "fontSize": 14,
      "fontWeight": 400
    }
  }
})}
  appearanceOptions={JSON.stringify({
    "appearanceOptionsPosition": "top-right",
    "dynamicBehaviour": {
      "isEnabled": true,
      "label": "Dynamic"
    },
    "cumulativeBar": {
      "isEnabled": true,
      "label": "Cumulative"
    },
    "stackedBars": {
      "isEnabled": true,
      "label": "Stacked"
    }
  })}
  long-description-config={JSON.stringify({
    "width": "100%",
    "fontColor": "#333"
  })}
  chart-columns ={JSON.stringify({
   "isEnabled": true,
   "dimensions": ["name"],
   "measures": ["count of order_id"]
   })},
  theme-name="Name of the theme you want to apply from app settings ui theming"
  chart-colors={JSON.stringify(["red", "blue", "orange"])} // array of color strings - by default recharts default colors
  metric-filter-options={JSON.stringify({ // note that invalid options will be filtered out
  "Filter name for a string datatype": {
    "options": [
                { "value": "James Smith", "label": "James" },
                { "value": "Olivia Johnson", "label": "Olivia" },
                { "value": "Emma Brown", "label": "Emma" }
              ],
    "defaultOption": "James Smith"
  },
  "Filter name for a number datatype": {
    "options": [{ "value": 1, "label": "user_1" }, { "value": 2, "label": "user_2" }], // should have unique elements
    "defaultOption": 1 // value of the selected option
  },
  "Filter name for a date datatype": {
    "options": [
      {
        "range": "Last",
        "time": "Year",
        "name": "Last 10 Years",
        "count": 10, // required for range = "Last" else ignored
        "fromDate": "2023-01-01", // optional if you don't want date picker for custom range else ignored
        "toDate": "2023-12-31", // optional if you don't want date picker for custom range else ignored
        "minDate": "2020-01-01", // optional for custom range else ignored
        "maxDate": "2024-12-31" // optional for custom range else ignored
      },
      {
        "range": "This",
        "time": "Year",
        "name": "This Year",
        "count": 0, // required for range "Last" else not required
        "minDate": "2024-01-01", // optional for custom range
        "maxDate": "2024-12-31" // optional for custom range
      },
    ],
    "defaultOption": "Last 10 Years" // name of the option
  },
})}
 translation-dictionary = {JSON.stringify({
  "total sales": {
    "en": "total sales",
    "fr": "ventes totales",
    "es": "ventas totales",
    "de": "Gesamtumsatz",
    "it": "vendite totali",
    "pt": "vendas totais",
    "zh": "总销售额",
    "ja": "総売上",
    "ko": "총 매출",
    "hi": "कुल बिक्री",
    "ar": "إجمالي المبيعات",
    "ru": "общие продажи"
  }
})}
language= "fr"
calendar-type='ind' | 'default'
is-disable-card-title // hides metric card title
/>

For the metric-filter-optionsprop, invalid options will be filtered out.

Server Event.

FAQs

How to pass props dynamically or re-render the embedded component on prop change?

As a web component, it does not automatically re-render upon prop changes. A common approach to address this is to force a re-render by displaying a loader and temporarily hiding the web component during prop updates. Instead of directly changing the props, you can set a temporary state to display the loader or hide the metric, then update the prop after a brief delay.

// React example
const [isLoading, setIsLoading] = useState(false);
const [dashboardProps, setDashboardProps] = useState(initialProps);

const updateProps = async (newProps) => {
  setIsLoading(true);
  await new Promise(resolve => setTimeout(resolve, 100));
  setDashboardProps(newProps);
  setIsLoading(false);
};

return isLoading ? <div>Loading...</div> : <dbn-dashboard {...dashboardProps} />;

What's the difference between chart-colors and chartColors in options?

chart-colors is a direct attribute on the component
chartColors is a property within the options object
Both serve the same purpose but chartColors in options takes precedence

<!-- Method 1: Direct attribute -->
<dbn-dashboard chart-colors={JSON.stringify(["#FF6B6B", "#4ECDC4"])} />

<!-- Method 2: Within options object -->
<dbn-dashboard options={JSON.stringify({
  chartColors: ["#FF6B6B", "#4ECDC4"]
})} />

How do I hide specific UI elements?

Use the various disable/hide options available:

const minimalDashboard = {
  hideDashboardName: true,
  hideMetricCardShadow: true,
  disableMetricCreation: true,
  disableLayoutCustomization: true,
  disableManageMetrics: true,
  showDashboardActions: false
};

For metric components:

<dbn-metric 
  disable-fullscreen
  is-hide-chart-settings
  is-hide-table-preview
  disable-underlying-data
  hide-metric-card-shadow
  is-disable-card-title
/>

Why is my JSON.stringify not working correctly?

Common issues with JSON.stringify:

Undefined values are omitted:

// ❌ This will omit undefined properties
const options = { color: undefined, size: 12 };
JSON.stringify(options); // {"size":12}

// ✅ Use null or default values instead
const options = { color: null, size: 12 };

Functions are omitted:

// ❌ Functions are not serialized
const options = { onClick: () => {}, size: 12 };

// ✅ Use string references for callbacks
const options = { onClickHandler: "myGlobalFunction", size: 12 };

Circular references cause errors:

// ❌ This will throw an error
const obj = {};
obj.self = obj;
JSON.stringify(obj); // TypeError: Converting circular structure to JSON

How do I debug component issues?

Enable Debug Mode:

// Add to your global scope
window.databrainDebug = true;

// Check browser console for detailed logs

Common Debugging Steps:

Open browser DevTools → Console
Look for error messages starting with “Databrain:”
Check Network tab for failed API requests
Verify token validity in Application → Local Storage
Test with minimal component configuration

Component Health Check:

// Add this to test basic functionality
const testComponent = () => {
  const testElement = document.querySelector('dbn-dashboard');
  console.log('Component found:', !!testElement);
  console.log('Token present:', !!testElement?.getAttribute('token'));
  console.log('Dashboard ID:', testElement?.getAttribute('dashboard-id'));
};

What are the performance implications of different options?

High Performance Impact:

disableMainLoader: false - Shows loading animations
disableUnderlyingData: false - Loads additional data
chart-renderer-type: "svg" - More CPU intensive than canvas
Complex chartAppearance configurations

Optimization Recommendations:

const performanceOptimized = {
  disableMainLoader: true,
  disableMetricLoader: true, 
  disableUnderlyingData: true,
  shouldFitFullScreen: true
};

For Large Datasets:

<dbn-metric chart-renderer-type="canvas" />

Memory Usage:

Limit simultaneous dashboard instances
Use lazy loading for multiple components
Consider component cleanup on unmount

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

Databrain Demo - StackBlitz

📚 Component Options Reference

Dashboard Component

Metric Component

FAQs

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

Databrain Demo - StackBlitz

📚 Component Options Reference

​Dashboard Component

​Metric Component

​FAQs

Dashboard Component

Metric Component

FAQs