Skip to Content

Component Options

Set and carry dashboard filters

Set default filter values, hide filters, and keep a viewer's filters when they switch dashboards.

Use three props on <dbn-dashboard>:

PropTypeWhat it does
global-filter-optionsJSONSets the default value, the option list, date presets and visibility of each dashboard filter.
hide-dashboard-filtersJSON array of filter labelsRemoves these filters from the dashboard.
filterStateFunctionfunction (JS property only)Gets the applied filters each time the viewer changes them.

<dbn-metric> also takes global-filter-options.

Set filter defaults

global-filter-options is an object. Each key is a filter label as the dashboard shows it. Each value can have four fields (publicTypes.ts:483-502).

FieldTypeWhat it does
defaultOptionstring, string[], { startDate, endDate, startTime?, endTime?, isTimeFilter? }, { min, max }, or a preset labelThe value the filter has when the dashboard opens.
options[{ value, label }]The list of values the filter offers. It replaces the values the filter loads.
datePresetOptionsarray of presetsThe date presets the date filter offers.
isHidebooleanHides the filter control. Its defaultOption still applies to the cards.

Use the shape that matches the filter type:

  • Single select: a string, for example "APAC".
  • Multi select: an array, for example ["APAC", "EMEA"].
  • Number range: { "min": 0, "max": 100 }. Use null for an open end.
  • Date range: { "startDate": "2026-01-01", "endDate": "2026-03-31" }.
  • Date preset: the label of one of your datePresetOptions.
<dbn-dashboard
  token="GUEST_TOKEN"
  dashboard-id="DASHBOARD_ID"
  global-filter-options='{
    "Region": { "defaultOption": ["APAC", "EMEA"] },
    "Amount": { "defaultOption": { "min": 0, "max": 100 } },
    "Plan": {
      "options": [
        { "value": "free", "label": "Free" },
        { "value": "pro", "label": "Pro" }
      ],
      "defaultOption": "pro"
    },
    "Account": { "defaultOption": "ACME-01", "isHide": true }
  }'
></dbn-dashboard>

The embed matches a key to a filter by its label or column name. It tries an exact match first, then a match that ignores case (helpers/createMetric.ts:3345-3373).

A value set in the guest token’s dashboardAppFilters wins over defaultOption (helpers/createMetric.ts:3440-3465).

Date presets

Each item in datePresetOptions has these fields (publicTypes.ts:465-480, helpers/createMetric.ts:3221-3293):

FieldValues
typelast, this, next or custom
intervalA number, for example 7
timeGrainday, week, month, quarter or year
labelThe name in the dropdown. Use it as defaultOption.
startDate, endDateDates, for custom
startTime, endTime, isTimeFilterOptional, for a time range
calendarTypeind for a fiscal year from 1 April to 31 March, else default
isDateRestricted, restrictionDateFrom, restrictionDateToOptional limits on the dates a viewer can pick
<dbn-dashboard
  token="GUEST_TOKEN"
  dashboard-id="DASHBOARD_ID"
  global-filter-options='{
    "Order date": {
      "datePresetOptions": [
        { "type": "last", "interval": 7, "timeGrain": "day", "label": "Last 7 days" },
        { "type": "this", "interval": 1, "timeGrain": "month", "label": "This month" }
      ],
      "defaultOption": "This month"
    }
  }'
></dbn-dashboard>

Hide filters

Pass the labels of the filters to remove:

<dbn-dashboard
  token="GUEST_TOKEN"
  dashboard-id="DASHBOARD_ID"
  hide-dashboard-filters='["Region", "Account"]'
></dbn-dashboard>

The embed removes each filter whose label is in this list or in the guest token’s params.hideDashboardFilters (containers/Dashboard/EmbededDashboard.tsx:1295-1311). A removed filter does not apply its default. To keep a default but hide the control, use isHide instead.

Carry filters to the next dashboard

filterStateFunction gets an EmbedFilterStateSnapshot each time the applied filters change (containers/Dashboard/dashboardFilterState.ts:82-91, containers/Dashboard/EmbededDashboard.tsx:1674-1685):

type EmbedFilterStateSnapshot = {
  dashboardId?: string;
  filters: { label: string; column?: string; as?: string; value: unknown }[];
  globalFilterOptions: Record<string, { defaultOption: unknown }>;
};
  • filters lists each applied filter, in the order the dashboard shows them. Use it to show or log the filters.
  • globalFilterOptions is ready to pass to the next <dbn-dashboard> as is.

Set the function as a JS property. A web component does not load a new dashboard when you change dashboard-id, so create a new element for each switch (webcomponents.ts:372-380).

import '@databrainhq/plugin/web';

let carried = {};

async function showDashboard(container, token, dashboardId) {
  await customElements.whenDefined('dbn-dashboard');
  const el = document.createElement('dbn-dashboard');
  el.setAttribute('token', token);
  el.setAttribute('dashboard-id', dashboardId);
  el.globalFilterOptions = carried;
  el.filterStateFunction = (snapshot) => {
    carried = snapshot.globalFilterOptions;
  };
  container.replaceChildren(el);
}

To keep your own options or datePresetOptions, merge only defaultOption from the snapshot into your object for each label.

The snapshot follows these rules (containers/Dashboard/dashboardFilterState.ts:118-245):

  • It matches filters across dashboards by label. Two filters called Region on different tables share a value.
  • It leaves out filters with no value: null, empty text or an empty array. 0 and false stay.
  • It keeps the first filter when two have the same label.
  • It turns dates into ISO strings, so you can store the snapshot as JSON.
  • It removes SQL quotes from text values, so a value does not gain quotes on each switch.

The destination dashboard ignores labels it does not have. Your guest token still sets which rows the viewer can see. A carried value cannot widen that.

Next, handle embed events.