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>:
| Prop | Type | What it does |
|---|---|---|
global-filter-options | JSON | Sets the default value, the option list, date presets and visibility of each dashboard filter. |
hide-dashboard-filters | JSON array of filter labels | Removes these filters from the dashboard. |
filterStateFunction | function (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).
| Field | Type | What it does |
|---|---|---|
defaultOption | string, string[], { startDate, endDate, startTime?, endTime?, isTimeFilter? }, { min, max }, or a preset label | The 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. |
datePresetOptions | array of presets | The date presets the date filter offers. |
isHide | boolean | Hides 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 }. Usenullfor an open end. - Date range:
{ "startDate": "2026-01-01", "endDate": "2026-03-31" }. - Date preset: the
labelof one of yourdatePresetOptions.
<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):
| Field | Values |
|---|---|
type | last, this, next or custom |
interval | A number, for example 7 |
timeGrain | day, week, month, quarter or year |
label | The name in the dropdown. Use it as defaultOption. |
startDate, endDate | Dates, for custom |
startTime, endTime, isTimeFilter | Optional, for a time range |
calendarType | ind for a fiscal year from 1 April to 31 March, else default |
isDateRestricted, restrictionDateFrom, restrictionDateTo | Optional 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 }>;
};filterslists each applied filter, in the order the dashboard shows them. Use it to show or log the filters.globalFilterOptionsis 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
Regionon different tables share a value. - It leaves out filters with no value:
null, empty text or an empty array.0andfalsestay. - 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.