Skip to content

Commit ca2f1df

Browse files
committed
docs(ui): document GlobalFilter.name + widget filterBindings in dashboards guide
Pairs the spec addition with its authoring doc: stable filter names as the page.<name> variable key, per-widget binding overrides / opt-out, and the binding precedence order. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HG5LQnPbQbjAAyofghzz3Z
1 parent 907a91c commit ca2f1df

1 file changed

Lines changed: 32 additions & 1 deletion

File tree

content/docs/ui/dashboards.mdx

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -302,11 +302,42 @@ Add interactive filter controls that apply to all widgets:
302302

303303
```typescript
304304
globalFilters: [
305-
{ field: 'region', label: 'Region', type: 'select' },
305+
{ name: 'region', field: 'region', label: 'Region', type: 'select' },
306306
{ field: 'owner', label: 'Sales Rep', type: 'lookup' },
307307
]
308308
```
309309

310+
Each filter's `name` is its stable identity: the key its value is published
311+
under as a dashboard-level variable (readable in widget expressions as
312+
`page.<name>`) and the key widgets reference in `filterBindings`. It defaults
313+
to `field`; the name `dateRange` is reserved for the built-in date range.
314+
315+
### Per-Widget Filter Bindings
316+
317+
By default a filter applies to its own `field` on every widget (the date
318+
range defaults to `dateRange.field ?? 'created_at'`). When a widget stores
319+
the concept under a different field — or should ignore a filter — declare
320+
`filterBindings` on the widget:
321+
322+
```typescript
323+
widgets: [
324+
// Default binding: dateRange → created_at, region → region.
325+
{ id: 'invoices_by_status', /**/ },
326+
// This widget's own fields differ — map each filter explicitly.
327+
{
328+
id: 'accounts_signed',
329+
filterBindings: { dateRange: 'signed_at', region: 'sales_region' },
330+
/**/
331+
},
332+
// Opt out of a filter with `false`.
333+
{ id: 'total_invoices', filterBindings: { region: false }, /**/ },
334+
]
335+
```
336+
337+
Binding precedence: an explicit `filterBindings` entry (string override or
338+
`false` opt-out) → the filter's legacy `targetWidgets` allow-list → the
339+
filter's own `field`.
340+
310341
## Complete Example
311342

312343
First define the dataset the widgets bind to:

0 commit comments

Comments
 (0)