> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usedatabrain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Component Options Reference

> Comprehensive reference guide for all available options and properties for Databrain web components

<Card title="Interactive Demo" icon="play" href="https://playground.usedatabrain.com">
  Try out the components with different options in DataBrain's playground
</Card>

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

<Warning>
  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.
</Warning>

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

<Info>
  **`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](#field-name-mapping) table below for a cross-reference.
</Info>

<Warning>
  **`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.
</Warning>

***

## Dashboard Component (`dbn-dashboard`)

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

### Required Properties

<ParamField path="token" type="string" required>
  Guest token for authentication. Must be generated from your backend using the Databrain API.
</ParamField>

<ParamField path="dashboard-id" type="string" required>
  Unique identifier for the dashboard to display.
</ParamField>

### Display & Layout Options

<AccordionGroup>
  <Accordion title="Basic Display Controls">
    <ParamField path="is-hide-table-preview" type="boolean" default="false">
      Hides the table preview in full screen view.
    </ParamField>

    <ParamField path="is-hide-chart-settings" type="boolean" default="false">
      Hides chart settings in full screen view.
    </ParamField>

    <ParamField path="disable-fullscreen" type="boolean" default="false">
      Disables the full screen option for the dashboard.
    </ParamField>

    <ParamField path="enable-title-click-fullscreen" type="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.
    </ParamField>

    <ParamField path="options-icon" type="string" default="kebab-menu-vertical">
      Controls which options icon to display. Options: `kebab-menu-vertical` | `download`
    </ParamField>

    <ParamField path="is-sticky-dashboard-filters" type="boolean" default="false">
      Makes dashboard filters sticky at the top when scrolling.
    </ParamField>

    <ParamField path="settings-icon" type="object">
      Controls the visibility and configuration of the settings icon. Must be passed as `JSON.stringify(...)`.

      <Accordion title="Settings Icon Configuration">
        ```javascript theme={"dark"}
        {
          name: 'random',
          iconSvg: 'svg',
          menuPosition: 'bottom-start', // optional; defaults to "bottom-start"
        }
        ```
      </Accordion>

      <ResponseField name="name" type="string">
        Custom label text for the settings button.
      </ResponseField>

      <ResponseField name="iconSvg" type="string">
        Custom SVG markup for the settings button icon.
      </ResponseField>

      <ResponseField name="menuPosition" type="string" default="bottom-start">
        Controls where the settings menu popup is anchored relative to the settings button. Options: `"auto"` | `"auto-start"` | `"auto-end"` | `"top"` | `"bottom"` | `"right"` | `"left"` | `"top-start"` | `"top-end"` | `"bottom-start"` | `"bottom-end"` | `"right-start"` | `"right-end"` | `"left-start"` | `"left-end"`
      </ResponseField>
    </ParamField>
  </Accordion>

  <Accordion title="Download & Export Options">
    <ParamField path="enable-download-csv" type="boolean" default="false">
      Enables CSV download option in metric card actions.
    </ParamField>

    <ParamField path="enable-email-csv" type="boolean" default="false">
      Enables email CSV option in metric card actions.
    </ParamField>

    <ParamField path="disable-download-png" type="boolean" default="false">
      Disables PNG download option in full screen mode.
    </ParamField>

    <ParamField path="enable-download-all-metrics" type="boolean" default="false">
      Enables download option for all metrics at once.
    </ParamField>

    <ParamField path="enable-download-all-pdf" type="boolean" default="false">
      Enables PDF download option for all metrics at once.
    </ParamField>
  </Accordion>
</AccordionGroup>

### Advanced Configuration

<AccordionGroup>
  <Accordion title="Dashboard Options Object">
    The `options` prop accepts a JSON object with the following properties:

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

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

    <ResponseField name="disableDownloadDataNoFilters" type="boolean" default="false">
      Prevents downloading data when no filters are applied.
    </ResponseField>

    <ResponseField name="disableDownloadUnderlyingDataNoFilters" type="boolean" default="false">
      Prevents downloading underlying data when no filters are applied.
    </ResponseField>

    <ResponseField name="isShowNoDataFoundScreen" type="boolean" default="false">
      Shows a custom screen when no data is available.
    </ResponseField>

    <ResponseField name="disableMetricCreation" type="boolean" default="false">
      Disables the ability to create new metrics.
    </ResponseField>

    <ResponseField name="disableMetricUpdation" type="boolean" default="false">
      Disables the ability to update existing metrics.
    </ResponseField>

    <ResponseField name="showDashboardActions" type="boolean" default="true">
      Controls visibility of dashboard actions like create metric, customize layout.
    </ResponseField>

    <ResponseField name="renameBoard" type="string" default="board">
      Renames the dashboard "Board" view-filter UI text (tab label, dropdown label, Add/Save CTA, and modal copy). If the value contains multiple words, only the first word is used.
    </ResponseField>

    <ResponseField name="shouldFitFullScreen" type="boolean" default="false">
      Makes full screen modal take up space equivalent to the dashboard component.
    </ResponseField>

    <ResponseField name="isModifyUrl" type="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.
    </ResponseField>

    <ResponseField name="exportMsgPosition" type="string" default="bottom-right">
      Controls the position of the "Exporting Dashboard" prompt that appears while a dashboard export is in progress. Set to `"hidden"` to suppress the message entirely. Options: `"bottom"` | `"bottom-left"` | `"bottom-right"` | `"center"` | `"top"` | `"top-left"` | `"top-right"` | `"hidden"`
    </ResponseField>

    <ResponseField name="dashboardSpacing" type="object">
      Controls the horizontal and vertical spacing between the metrics on the grid. Optional `hide` field hides the **Adjust Spacing** button from **Customize Layout**.

      <Expandable title="Example">
        ```javascript theme={"dark"}
        "dashboardSpacing": {
          "verticalGap": 30,
          "horizontalGap": 30,
          "hide": true,
        }
        ```
      </Expandable>

      <Expandable title="Notes">
        * When omitted, default layout spacing applies.
        * Applying either of the **verticalGap** or **horizontalGap** sets the other to a default of **10**, unless configured here.
        * This controls the spacing **between** metrics on the grid. For setting outer wrapper padding around the embedded dashboard use **`dashboardPadding`** inside the same `options` object.
      </Expandable>
    </ResponseField>

    <ResponseField name="dashboardPadding" type="string">
      Optional CSS value for the main dashboard embed wrapper padding. Uses the same rules as the standard CSS `padding` shorthand (for example `"16px"`, `"12px 24px"`, `"8px 12px 16px"`). Applied as an inline style on the embed dashboard container.

      <Expandable title="Notes">
        * When omitted, default layout padding from stylesheets applies.
        * This controls outer wrapper padding around the embedded dashboard. For spacing **between** metrics on the grid, use **`dashboardSpacing`** inside the same `options` object.
      </Expandable>
    </ResponseField>

    <ResponseField name="ctaButtonCustomization" type="object">
      Optional styling overrides for dashboard CTA buttons (primary, secondary, and tertiary variants). Injected styles target `.cta-primary`, `.cta-secondary`, and `.cta-tertiary`, so they apply anywhere those classes are used in the embedded experience (for example dashboard action buttons and full-screen metric controls).

      Each variant supports optional string fields — pass fragments of CSS declarations (semicolon-separated), similar to inline style text:

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

      <Expandable title="Nested shape">
        ```typescript theme={"dark"}
        {
          primary?: {
            styles?: string;
            hoverStyles?: string;
            activeStyles?: string;
            disabledStyles?: string;
          };
          secondary?: { /* same fields */ };
          tertiary?: { /* same fields */ };
        }
        ```
      </Expandable>

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

    <ResponseField name="chartColors" type="array">
      Array of color strings for chart styling. Defaults to Recharts default colors.

      <Expandable title="Example">
        ```javascript theme={"dark"}
        ["#FF6B6B", "#4ECDC4", "#45B7D1", "#96CEB4", "#FECA57"]
        ```
      </Expandable>
    </ResponseField>

    <ResponseField name="chartPaletteOptions" type="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.

      <Expandable title="Example">
        ```javascript theme={"dark"}
        [
          {
            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"]
          }
        ]
        ```
      </Expandable>
    </ResponseField>

    <ResponseField name="chartAppearance" type="object">
      Detailed chart styling configuration for tooltips, labels, margins, legends, and axes.

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

  <Accordion title="Global Filter Options">
    Configure global filters for the dashboard:

    <CodeGroup>
      ```javascript String Filter theme={"dark"}
      {
        "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"
        }
      }
      ```

      ```javascript Number Filter   theme={"dark"}
      {
        "Filter name for a number datatype": {
          "defaultOption": {"min": 100, "max": 900}
        }
      }
      ```

      ```javascript Date Filter theme={"dark"}
      {
        "Filter name for a date datatype": {
          "defaultOption": {"startDate": "2024-01-01", "endDate": "2024-12-31"},
          "datePresetOptions": [
            {
              "type": "this",
              "interval": 1,
              "timeGrain": "month",
              "label": "this month",
              "startDate": "2024-01-01",
              "endDate": "2024-01-31"
            }
          ]
        }
      }
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Theme Configuration">
    <ParamField path="theme" type="object">
      Custom theme configuration for component styling.

      <Expandable title="Theme Structure">
        ```javascript theme={"dark"}
        {
          "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"
          }
        }
        ```
      </Expandable>
    </ParamField>

    <ParamField path="theme-name" type="string">
      Name of a predefined theme from app settings UI theming.
    </ParamField>
  </Accordion>

  <Accordion title="Admin Theme Options">
    <ParamField path="admin-theme-options" type="object">
      Advanced UI theming configuration for the dashboard. Controls fonts, backgrounds, CTA colors, card styling, and chart palettes. Must be passed as `JSON.stringify(...)`.

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

      <ResponseField name="general.name" type="string">
        Name of the theme.
      </ResponseField>

      <ResponseField name="general.fontFamily" type="string">
        Global font family applied to the dashboard.
      </ResponseField>

      <ResponseField name="general.datePickerFormat" type="string">
        Date format string for date pickers (e.g. `"DD-MM-YYYY"`, `"MM-DD-YYYY"`, `"YYYY-MM-DD"`).
      </ResponseField>

      <ResponseField name="dashboard.backgroundColor" type="string">
        Background color of the dashboard container.
      </ResponseField>

      <ResponseField name="dashboard.ctaColor" type="string">
        Primary call-to-action button color.
      </ResponseField>

      <ResponseField name="dashboard.ctaTextColor" type="string">
        Text color for call-to-action buttons.
      </ResponseField>

      <ResponseField name="dashboard.selectBoxSize" type="string" default="medium">
        Size of filter select boxes. Options: `"small"` | `"medium"` | `"large"`
      </ResponseField>

      <ResponseField name="dashboard.selectBoxVariant" type="string" default="floating">
        Style variant for filter select boxes. Options: `"floating"` | `"static"`
      </ResponseField>

      <ResponseField name="dashboard.selectBoxBorderRadius" type="string">
        Border radius for filter select boxes (e.g. `"8px"`).
      </ResponseField>

      <ResponseField name="dashboard.selectBoxTextColor" type="string">
        Text color for filter select boxes.
      </ResponseField>

      <ResponseField name="dashboard.metricCardColor" type="string">
        Background color of individual metric cards.
      </ResponseField>

      <ResponseField name="cardTitle.fontSize" type="string">
        Font size of metric card titles (e.g. `"16px"`).
      </ResponseField>

      <ResponseField name="cardTitle.fontWeight" type="string">
        Font weight of metric card titles (e.g. `"600"`).
      </ResponseField>

      <ResponseField name="cardTitle.color" type="string">
        Text color of standard metric card titles (`.dbn-metric-card-title`).
      </ResponseField>

      <ResponseField name="cardTitle.elementColor" type="string">
        Text color for **element** metric titles — titles rendered in the element layout (`.dbn-metric-element-title`). Use when element metrics should differ from `cardTitle.color`. Applied with `!important` when set.

        <Expandable title="Relationship to `cardTitle.color`">
          * **`color`** styles the default card chrome title.
          * **`elementColor`** styles only element-mode titles. Omit either field to fall back to product defaults for that surface.
        </Expandable>
      </ResponseField>

      <ResponseField name="cardDescription.fontSize" type="string">
        Font size of metric card descriptions.
      </ResponseField>

      <ResponseField name="cardDescription.fontWeight" type="string">
        Font weight of metric card descriptions.
      </ResponseField>

      <ResponseField name="cardDescription.color" type="string">
        Text color of standard metric card descriptions (`.dbn-metric-card-description`).
      </ResponseField>

      <ResponseField name="cardDescription.elementColor" type="string">
        Text color for **element** metric descriptions (`.dbn-metric-element-description`). Separate from `cardDescription.color`; applied with `!important` when set.
      </ResponseField>

      <ResponseField name="chart.palettes" type="array">
        Array of custom chart color palettes. Each palette has a `name` and an array of `colors`.
      </ResponseField>

      <ResponseField name="chart.paletteOptions" type="array">
        Array of palette name strings available for selection.
      </ResponseField>

      <ResponseField name="chart.selected" type="string">
        Name of the currently selected palette.
      </ResponseField>

      <ResponseField name="chart.fontFamily" type="string">
        Font family applied to chart axis labels, legend text, and chart titles (e.g. `"Roboto"`).
      </ResponseField>

      <ResponseField name="chart.fontColor" type="string">
        Default text color for chart axis labels, legend text, and chart titles (e.g. `"#333333"`).
      </ResponseField>

      <ResponseField name="chart.letterSpacing" type="string">
        Letter spacing applied to chart text elements (e.g. `"0.5px"`).
      </ResponseField>

      <ResponseField name="chart.tooltip" type="object">
        Global tooltip font configuration with nested `header`, `label`, and `value` objects. Each accepts `fontFamily`, `fontSize`, `fontWeight`, and `fontColor`.
      </ResponseField>

      <Warning>
        **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.
      </Warning>

      <ResponseField name="cardCustomization.padding" type="string">
        Inner padding of metric cards (e.g. `"16px"`).
      </ResponseField>

      <ResponseField name="cardCustomization.borderRadius" type="string">
        Border radius of metric cards (e.g. `"8px"`).
      </ResponseField>

      <ResponseField name="cardCustomization.shadow" type="string">
        Box shadow of metric cards (e.g. `"0 2px 8px rgba(0,0,0,0.1)"`).
      </ResponseField>

      <ResponseField name="cardCustomization.disableShadowOnHover" type="boolean" default="false">
        Disables the shadow effect when hovering over metric cards.
      </ResponseField>

      <ResponseField name="cardCustomization.disableStroke" type="boolean" default="false">
        Disables the border stroke around metric cards.
      </ResponseField>

      <ResponseField name="cardCustomization.metricStrokeColor" type="string">
        Border stroke color for metric cards when stroke is enabled (e.g. `"#E0E0E0"`).
      </ResponseField>
    </ParamField>
  </Accordion>
</AccordionGroup>

### Additional Dashboard Properties

<ParamField path="long-description-config" type="object">
  Controls the appearance of metric long-description tooltips. Must be passed as `JSON.stringify(...)`.

  <Expandable title="Long Description Config">
    ```javascript theme={"dark"}
    {
      "width": "300px",
      "fontColor": "#333333"
    }
    ```
  </Expandable>
</ParamField>

<ParamField path="chart-columns" type="array">
  Restricts which columns are available to end users for each metric. Each entry targets a specific metric. Must be passed as `JSON.stringify(...)`.

  <Expandable title="Chart Columns Config">
    ```javascript theme={"dark"}
    [
      {
        "metricId": "metric-1",
        "isEnabled": true,
        "dimensions": ["region", "category"],
        "measures": ["revenue", "profit"]
      }
    ]
    ```
  </Expandable>
</ParamField>

### Per-Metric Chart Settings

<ParamField path="custom-chart-settings" type="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](#custom-chart-settings-reference) section below for the complete schema.

  <CodeGroup>
    ```javascript Example theme={"dark"}
    {
      labelSettings: {
        XAxisStyle: {
          size: { defaultValue: 12, canEdit: true }
        }
      },
      legendSettings: {
        show: { defaultValue: true, canEdit: false }
      }
    }
    ```

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

***

### Internationalization

<ParamField path="language" type="string" default="en">
  Language code for component localization (e.g., "fr", "es", "de").
</ParamField>

<ParamField path="translation-dictionary" type="object">
  Custom translation dictionary for component text.

  <Expandable title="Translation Example">
    ```javascript theme={"dark"}
    {
      "total sales": {
        "en": "total sales",
        "fr": "ventes totales", 
        "es": "ventas totales",
        "de": "Gesamtumsatz"
      }
    }
    ```
  </Expandable>
</ParamField>

<ParamField path="calendar-type" type="string" default="default">
  Calendar system to use. Options: `default` | `ind`
</ParamField>

### Event Handling

<ParamField path="handle-server-event" type="string">
  Name of a global function to handle server events. Define the function in the global scope.

  <CodeGroup>
    ```javascript Function Definition theme={"dark"}
    // Define globally accessible function
    window.myServerEventHandler = (event) => {
      console.log('Server event:', event);
      // Handle the event
    };
    ```

    ```html Component Usage theme={"dark"}
    <dbn-dashboard 
      handle-server-event="myServerEventHandler"
      ...other-props
    />
    ```
  </CodeGroup>
</ParamField>

### Custom Chart Click Action

<ParamField path="chart-click-function" type="string">
  Name of a global function to call when a user clicks on a chart data point. Define the function in the global scope.

  <CodeGroup>
    ```javascript Function Definition theme={"dark"}
    // Define globally accessible function
    window.myChartClickHandler = (data) => {
      console.log('Chart clicked:', data);
      // Handle the click data
    };
    ```

    ```html Component Usage theme={"dark"}
    <dbn-dashboard 
      chart-click-function="myChartClickHandler"
      ...other-props
    />
    ```
  </CodeGroup>

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

  <Note>
    When Pass Complete Data is not enabled, the clicked value is directly passed instead of the data object.
  </Note>
</ParamField>

### Custom Messages

<ParamField path="custom-messages" type="object">
  Custom messages for various component states.

  <Expandable title="Available Messages">
    ```javascript theme={"dark"}
    {
      "tokenExpiry": "Your session has expired. Please refresh the page.",
      "tokenAbsent": "Authentication token is missing. Please log in again."
    }
    ```
  </Expandable>
</ParamField>

***

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

<Warning>
  `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](#understanding-the-configuration-layers).
</Warning>

### 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` |

<AccordionGroup>
  <Accordion title="Margins">
    ```javascript theme={"dark"}
    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 },
    }
    ```
  </Accordion>

  <Accordion title="Chart Colors">
    ```javascript theme={"dark"}
    chartColors: { defaultValue: ['#FF0000', '#FF7F00', '#FFFF00', '#00FF00', '#0000FF', '#4B0082', '#8B00FF', '#FF1493', '#00FFFF'], canEdit: true | false }
    ```
  </Accordion>

  <Accordion title="Legend Settings">
    ```javascript theme={"dark"}
    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 },
    }
    ```
  </Accordion>

  <Accordion title="Label Settings">
    ```javascript theme={"dark"}
    labelSettings: {
      position: { defaultValue: 'left' | 'right' | 'top' | 'bottom' | 'inside' | 'outside' | 'hidden', canEdit: true | false },
      truncateLabel: { defaultValue: true | false, canEdit: true | false },
      truncateLabelValue: { defaultValue: 10, canEdit: true | false },
      showLabelLine: { defaultValue: true | false, canEdit: true | false },
      isEnableValueSummation: { defaultValue: false, canEdit: true | false },
      showDimension: { defaultValue: true | false, canEdit: true | false },
      isDynamicPosition: { defaultValue: true | false, canEdit: true | false },
      showActualValue: { defaultValue: true | false, canEdit: true | false },
      XAxisStyle: {
        size: { defaultValue: 12, canEdit: true | false },
        family: { defaultValue: 'Inter', canEdit: true | false },
        weight: { defaultValue: 400, canEdit: true | false },
        color: { defaultValue: '#000000', canEdit: true | false },
        axisName: { defaultValue: '', canEdit: true | false },
        axisPadding: { defaultValue: 0, canEdit: true | false },
        axisMargin: { defaultValue: 0, canEdit: true | false },
        axisNameFontConfig: {
          fontFamily: { defaultValue: 'Inter', canEdit: true | false },
          fontSize: { defaultValue: 12, canEdit: true | false },
          fontWeight: { defaultValue: 400, canEdit: true | false },
        },
      },
      YAxisStyle: {
        size: { defaultValue: 12, canEdit: true | false },
        family: { defaultValue: 'Inter', canEdit: true | false },
        weight: { defaultValue: 400, canEdit: true | false },
        color: { defaultValue: '#000000', canEdit: true | false },
        axisName: { defaultValue: '', canEdit: true | false },
        axisPadding: { defaultValue: 0, canEdit: true | false },
        axisMargin: { defaultValue: 0, canEdit: true | false },
        axisNameFontConfig: {
          fontFamily: { defaultValue: 'Inter', canEdit: true | false },
          fontSize: { defaultValue: 12, canEdit: true | false },
          fontWeight: { defaultValue: 400, canEdit: true | false },
        },
      },
    }
    ```
  </Accordion>

  <Accordion title="Tooltip Settings">
    ```javascript theme={"dark"}
    tooltipSettings: {
      labelStyle: {
        size: { defaultValue: 12, canEdit: true | false },
        family: { defaultValue: 'Inter', canEdit: true | false },
        weight: { defaultValue: 400, canEdit: true | false },
        color: { defaultValue: '#000000', canEdit: true | false },
      },
      valueStyle: {
        size: { defaultValue: 12, canEdit: true | false },
        family: { defaultValue: 'Inter', canEdit: true | false },
        weight: { defaultValue: 400, canEdit: true | false },
        color: { defaultValue: '#000000', canEdit: true | false },
      },
      tooltipHeader: {
        size: { defaultValue: 14, canEdit: true | false },
        family: { defaultValue: 'Inter', canEdit: true | false },
        weight: { defaultValue: 600, canEdit: true | false },
        color: { defaultValue: '#000000', canEdit: true | false },
      },
      tooltipCard: {
        bgColor: {defaultValue: '#FFFFFF', canEdit: true | false },
        borderColor: {defaultValue: '#FFFFFF', canEdit: true | false },
      }
    }
    ```
  </Accordion>

  <Accordion title="Axis Settings">
    ```javascript theme={"dark"}
    axisSettings: {
      axis: { defaultValue: 'left' | 'right', canEdit: true | false },
    }
    ```
  </Accordion>

  <Accordion title="Custom Settings - Axis & Grid">
    ```javascript theme={"dark"}
    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 },
    }
    ```
  </Accordion>

  <Accordion title="Custom Settings - Formatting">
    ```javascript theme={"dark"}
    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,
      },
    }
    ```
  </Accordion>

  <Accordion title="Custom Settings - Title & Sub-header">
    ```javascript theme={"dark"}
    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 },
    }
    ```
  </Accordion>

  <Accordion title="Custom Settings - Single Value / KPI">
    ```javascript theme={"dark"}
    customSettings: {
      singleValConditionalFormatter: {
        defaultValue: [{ type: 'range', min: 0, max: 100, color: '#00FF00' }],
        canEdit: true | false,
      },
    }
    ```
  </Accordion>

  <Accordion title="Custom Settings - Bar & Column Charts">
    ```javascript theme={"dark"}
    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 },
    }
    ```
  </Accordion>

  <Accordion title="Custom Settings - Combo Charts">
    ```javascript theme={"dark"}
    customSettings: {
      comboAxisSettings: {
        defaultValue: [{ axis: 'left', measures: ['revenue'], chartTypes: [{ axis: 'left', type: 'bar' }] }],
        canEdit: true | false,
      },
    }
    ```
  </Accordion>

  <Accordion title="Custom Settings - Zoom, Sort & Behavior">
    ```javascript theme={"dark"}
    customSettings: {
      isEnableMeasureMode: { defaultValue: true | false, canEdit: true | false },
      chartZoom: {
        isZoomEnabled: { defaultValue: true | false, canEdit: true | false },
        zoomAxis: { defaultValue: 'x', canEdit: true | false },
      },
    }
    ```
  </Accordion>

  <Accordion title="Custom Settings - Markers">
    ```javascript theme={"dark"}
    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 },
      },
    }
    ```
  </Accordion>

  <Accordion title="Custom Settings - Linear Gauge V2">
    ```javascript theme={"dark"}
    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 },
        },
      },
    }
    ```
  </Accordion>

  <Accordion title="Table Settings - Conditional Formatting">
    ```javascript theme={"dark"}
    tableSettings: {
      conditionalFormatting: {
        defaultValue: [{ columnName: 'status', rules: [{ operator: '=', value: 'Active', styles: { backgroundColor: '#00FF00', color: '#000000', isApplyBgColor: true } }] }],
        canEdit: true | false,
      },
    }
    ```
  </Accordion>

  <Accordion title="Table Settings - Number & Time Formatting">
    ```javascript theme={"dark"}
    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 },
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Metric Component (`dbn-metric`)

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

### Required Properties

<ParamField path="token" type="string" required>
  Guest token for authentication.
</ParamField>

<ParamField path="metric-id" type="string" required>
  Unique identifier for the metric to display.
</ParamField>

### Display Properties

<ParamField path="width" type="string|number" default="500">
  Width of the metric component in pixels.
</ParamField>

<ParamField path="height" type="string|number" default="300">
  Height of the metric component in pixels.
</ParamField>

<ParamField path="variant" type="string" default="card">
  Display variant. Options: `card` | `fullscreen`
</ParamField>

<ParamField path="chart-renderer-type" type="string" default="svg">
  Chart rendering method. Options: `svg` | `canvas`
</ParamField>

### Behavior Options

<AccordionGroup>
  <Accordion title="Download & Export">
    <ParamField path="enable-download-csv" type="boolean" default="false">
      Enables CSV download in metric card actions.
    </ParamField>

    <ParamField path="enable-email-csv" type="boolean" default="false">
      Enables email CSV option in metric card actions.
    </ParamField>

    <ParamField path="disable-download-png" type="boolean" default="false">
      Disables PNG download in full screen mode.
    </ParamField>
  </Accordion>

  <Accordion title="UI Controls">
    <ParamField path="disable-fullscreen" type="boolean" default="false">
      Disables the full screen button.
    </ParamField>

    <ParamField path="is-hide-table-preview" type="boolean" default="false">
      Hides table preview in full screen view.
    </ParamField>

    <ParamField path="is-hide-chart-settings" type="boolean" default="false">
      Hides chart settings in full screen view.
    </ParamField>

    <ParamField path="disable-underlying-data" type="boolean" default="false">
      Disables access to underlying data.
    </ParamField>

    <ParamField path="disable-metric-card-border" type="boolean" default="false">
      Removes border from metric card.
    </ParamField>

    <ParamField path="hide-metric-card-shadow" type="boolean" default="false">
      Removes shadow from metric card.
    </ParamField>

    <ParamField path="is-disable-card-title" type="boolean" default="false">
      Hides the metric card title.
    </ParamField>

    <ParamField path="enable-title-click-fullscreen" type="boolean" default="false">
      Enables fullscreen mode when the metric title is clicked.
    </ParamField>

    <ParamField path="options-icon" type="string" default="kebab-menu-vertical">
      Controls which options icon to display. Options: `kebab-menu-vertical` | `download`
    </ParamField>

    <ParamField path="disable-download-underlying-data-no-filters" type="boolean" default="false">
      Prevents downloading underlying data when no filters are applied.
    </ParamField>

    <ParamField path="disable-download-data-no-filters" type="boolean" default="false">
      Prevents downloading data when no filters are applied.
    </ParamField>
  </Accordion>
</AccordionGroup>

### Filter Configuration

<ParamField path="enable-multi-metric-filters" type="boolean" default="false">
  Allows multiple metric filters.
</ParamField>

<ParamField path="metric-filter-position" type="string" default="inside">
  Position of metric filters. Options: `inside` | `outside`
</ParamField>

<ParamField path="metric-filter-options" type="object">
  Configuration for metric-specific filters.

  <Expandable title="Filter Configuration">
    ```javascript theme={"dark"}
    {
      "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"
      }
    }
    ```
  </Expandable>
</ParamField>

### Chart Appearance

<ParamField path="chart-appearance" type="object">
  Detailed chart styling configuration.

  <Expandable title="Chart Appearance Options">
    ```javascript theme={"dark"}
    {
      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;
        };
      };
    };
    ```
  </Expandable>
</ParamField>

<ParamField path="appearance-options" type="object">
  Interactive appearance options for the metric.

  <Expandable title="Appearance Options">
    ```javascript theme={"dark"}
    {
      "appearanceOptionsPosition": "top-right",
      "dynamicBehaviour": {
        "isEnabled": true,
        "label": "Dynamic"
      },
      "cumulativeBar": {
        "isEnabled": true,
        "label": "Cumulative"
      },
      "stackedBars": {
        "isEnabled": true,
        "label": "Stacked"
      }
    }
    ```
  </Expandable>
</ParamField>

### Internationalization & Configuration

<ParamField path="language" type="string" default="en">
  Language code for component localization (e.g., `"fr"`, `"es"`, `"de"`).
</ParamField>

<ParamField path="translation-dictionary" type="object">
  Custom translation dictionary for metric text. Must be passed as `JSON.stringify(...)`. See the dashboard [Internationalization](#internationalization) section for the full schema.
</ParamField>

<ParamField path="calendar-type" type="string" default="default">
  Calendar system to use. Options: `default` | `ind`
</ParamField>

<ParamField path="theme-name" type="string">
  Name of a predefined theme from app settings UI theming.
</ParamField>

<ParamField path="custom-messages" type="object">
  Custom messages for component states. Must be passed as `JSON.stringify(...)`.

  <Expandable title="Available Messages">
    ```javascript theme={"dark"}
    {
      "tokenExpiry": "Your session has expired. Please refresh the page.",
      "tokenAbsent": "Authentication token is missing. Please log in again."
    }
    ```
  </Expandable>
</ParamField>

<ParamField path="global-filter-options" type="object">
  Pre-configured filter values for the metric. Must be passed as `JSON.stringify(...)`. See the dashboard [Global Filter Options](#global-filter-options) section for the full schema.
</ParamField>

<ParamField path="long-description-config" type="object">
  Controls the appearance of metric long-description tooltips. Must be passed as `JSON.stringify(...)`.

  <Expandable title="Long Description Config">
    ```javascript theme={"dark"}
    {
      "width": "300px",
      "fontColor": "#333333"
    }
    ```
  </Expandable>
</ParamField>

<ParamField path="chart-columns" type="object">
  Restricts which columns are available to end users for this metric. Must be passed as `JSON.stringify(...)`.

  <Expandable title="Chart Columns Config">
    ```javascript theme={"dark"}
    {
      "isEnabled": true,
      "dimensions": ["region", "category"],
      "measures": ["revenue", "profit"]
    }
    ```
  </Expandable>
</ParamField>

### Event Callbacks

<ParamField path="on-minimize" type="string">
  Name of global function to call when metric is minimized.

  <CodeGroup>
    ```javascript Function Definition theme={"dark"}
    window.handleMetricMinimize = (metricId) => {
      console.log('Metric minimized:', metricId);
    };
    ```

    ```html Component Usage theme={"dark"}
    <dbn-metric 
      on-minimize="handleMetricMinimize"
      ...other-props
    />
    ```
  </CodeGroup>
</ParamField>

***

## Common Properties

These properties are available for both dashboard and metric components:

### Styling & Customization

<ParamField path="style" type="string">
  Inline CSS styles for the component.
</ParamField>

<ParamField path="class-name" type="string">
  CSS class name for custom styling.
</ParamField>

<ParamField path="chart-colors" type="array">
  Array of colors for chart elements.

  <CodeGroup>
    ```javascript Example Colors theme={"dark"}
    ["#FF6B6B", "#4ECDC4", "#45B7D1", "#96CEB4", "#FECA57"]
    ```
  </CodeGroup>
</ParamField>

### No Data Handling

<ParamField path="no-data-img" type="string">
  SVG code as string to display when no data is available.
</ParamField>

<ParamField path="no-data-found-svg" type="string">
  SVG code as string to display when no data is found in dashboard.
</ParamField>

### Date Picker Configuration

<ParamField path="hide-date-picker-options" type="array">
  Array of date picker option labels to hide.

  <CodeGroup>
    ```javascript Example theme={"dark"}
    ["this month", "yesterday", "last week"]
    ```
  </CodeGroup>
</ParamField>

***

## Usage Examples

<Tabs>
  <Tab title="Basic Dashboard">
    ```html theme={"dark"}
    <dbn-dashboard 
      token="your-guest-token"
      dashboard-id="your-dashboard-id"
      enable-download-csv
      enable-email-csv
    />
    ```
  </Tab>

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

  <Tab title="Basic Metric">
    ```html theme={"dark"}
    <dbn-metric
      token="your-guest-token" 
      metric-id="your-metric-id"
      width="600"
      height="400"
      enable-download-csv
      chart-renderer-type="canvas"
    />
    ```
  </Tab>

  <Tab title="Advanced Metric">
    ```html theme={"dark"}
    <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
          }
        }
      })}
    />
    ```
  </Tab>
</Tabs>

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="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**

    ```javascript theme={"dark"}
    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**

    ```javascript theme={"dark"}
    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" />
        )}
      </>
    );
    ```
  </Accordion>

  <Accordion title="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:**

    ```javascript theme={"dark"}
    // ✅ 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:**

    ```html theme={"dark"}
    <!-- ✅ 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:**

    ```css theme={"dark"}
    /* Your custom colors might be overridden */
    .your-dashboard-container {
      --chart-color-1: #FF6B6B !important;
      --chart-color-2: #4ECDC4 !important;
    }
    ```
  </Accordion>

  <Accordion title="How do I handle authentication token expiry?">
    **Set Up Custom Messages:**

    ```html theme={"dark"}
    <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:**

    ```javascript theme={"dark"}
    // 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:**

    ```javascript theme={"dark"}
    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;
    };
    ```
  </Accordion>

  <Accordion title="How do I customize the appearance of filters and date pickers?">
    **Hide Specific Date Picker Options:**

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

    **Custom Filter Styling:**

    ```html theme={"dark"}
    <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:**

    ```javascript theme={"dark"}
    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"
          }
        ]
      }
    };
    ```
  </Accordion>

  <Accordion title="Why is my dashboard not loading or showing blank?">
    **Common Causes & Solutions:**

    1. **Invalid Token:**

    ```javascript theme={"dark"}
    // 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;
      }
    };
    ```

    2. **Incorrect Dashboard ID:**

    ```javascript theme={"dark"}
    // 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;
      }
    };
    ```

    3. **Missing Import:**

    ```javascript theme={"dark"}
    // 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;
        }
      }
    }
    ```

    4. **Network/CORS Issues:**

    ```javascript theme={"dark"}
    // Check browser console for CORS errors
    // Ensure your backend allows requests from your domain
    ```
  </Accordion>

  <Accordion title="How do I implement multi-tenant access control?">
    **Client-Side Implementation:**

    ```javascript theme={"dark"}
    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:**

    ```javascript theme={"dark"}
    // 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' });
      }
    });
    ```
  </Accordion>

  <Accordion title="How do I optimize performance for large dashboards?">
    **Enable Canvas Rendering:**

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

    **Disable Heavy Features:**

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

    **Lazy Loading Implementation:**

    ```javascript theme={"dark"}
    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>
      );
    };
    ```
  </Accordion>

  <Accordion title="How do I handle different screen sizes and responsive design?">
    **Responsive Width/Height:**

    ```javascript theme={"dark"}
    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:**

    ```css theme={"dark"}
    .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:**

    ```javascript theme={"dark"}
    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)}
    />
    ```
  </Accordion>

  <Accordion title="How do I implement custom error handling and logging?">
    **Global Error Handler:**

    ```javascript theme={"dark"}
    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:**

    ```javascript theme={"dark"}
    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>
    ```
  </Accordion>

  <Accordion title="How do I customize chart tooltips and legends?">
    **Advanced Tooltip Customization:**

    ```javascript theme={"dark"}
    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:**

    ```javascript theme={"dark"}
    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:**

    ```html theme={"dark"}
    <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"
        }
      })}
    />
    ```
  </Accordion>
</AccordionGroup>

***

## Migration & Updates

<Warning>
  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.
</Warning>

<Info>
  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.
</Info>

## Troubleshooting Quick Reference

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="Styling Issues">
    * ✅ Use `JSON.stringify()` for object props
    * ✅ Check CSS specificity conflicts
    * ✅ Verify color format (use hex codes)
    * ✅ Test with `!important` to identify overrides
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

<Card title="Need More Help?" icon="question" href="/developer-docs/testing/troubleshooting">
  Check our comprehensive troubleshooting guide for additional solutions
</Card>
