Dashboard Controls
Dashboard Controls
Section titled “Dashboard Controls”Controls are the filter widgets at the top of a dashboard. A viewer changes them, and the tiles that read them re-run with the new values.
A control’s value reaches tiles in two ways:
1. tile param via from_control → connector {{placeholder}} → rows (data_processor tiles)2. $controls.<name> inside any tile expression — filter, metric… (every data tile, incl. assets)See Data & Expressions for params, Control values in expressions below for $controls, and the Dashboard Syntax Reference for the overall document structure.
Control types at a glance
Section titled “Control types at a glance”| Type | Viewer sees | Value a tile receives | Extra keys |
|---|---|---|---|
date |
A date picker | "2026-10-13" |
value_format |
date_range_preset |
A row of tabs (Last 7 days, This month…), optional Custom tab | Preset key, or {from, to} |
options, allow_custom, value_format |
select |
A dropdown, or a row of tabs with display: tabs |
One option value | options, display |
select + multiple: true |
Removable tags plus a searchable dropdown | A list of option values | options, multiple |
number |
A number input | A number | min, max, step |
number_range |
Min – Max number inputs | {min, max} |
min, max, step |
toggle |
An on/off switch | true / false |
— |
multi_select is still accepted as a legacy alias of select + multiple: true. There is no free-text control.
Common fields
Section titled “Common fields”Every control has these fields:
| Field | Required | Description |
|---|---|---|
name |
Yes | Unique identifier within the dashboard. Tiles reference it in from_control, so keep it a stable slug of letters, digits and underscores. |
type |
Yes | One of the types above. |
label |
No | Text shown above the widget. Without it the viewer shows name, which reads as a raw slug, so set it on every control. |
default |
No | Value the control starts with on first load. The shape depends on the type, as shown in each section below. Without a default, tiles that read the control wait until the viewer picks a value. |
Keys that belong to one type are rejected on any other type:
| Key | Only valid on |
|---|---|
options |
select, date_range_preset |
multiple |
select |
allow_custom |
date_range_preset |
display |
select (single value only) |
value_format |
date, date_range_preset |
min, max, step |
number, number_range |
Renaming a control in Dashboard Studio updates every tile from_control and subscription control_values that points at it. When you hand-edit YAML, update those references yourself.
Options
Section titled “Options”select and date_range_preset take an options list. Each option is { value, label }:
options: - { value: growth, label: "Growth & Web" } # full form - { value: systems } # label falls back to the value - security # bare scalar — same as { value: security }valueis what the tile receives, andlabelis what the viewer sees.- Values may be strings or numbers. Duplicate values are not allowed.
- Prefer the full form so viewers see readable text.
A single date picker.
- name: as_of label: "As of" type: date default: today # or an ISO date, e.g. "2026-01-01"| Value | ISO date string, "YYYY-MM-DD" |
| Default | today (resolved each time the dashboard loads) or a fixed ISO date |
| Applies | When the viewer clicks Apply |
params: - name: report_date from_control: as_ofThe data source receives the date as YYYY-MM-DD unless you set value_format.
For a from–to range, use one date_range_preset with allow_custom: true rather than two date controls. You get one widget, and the server checks that the start is not after the end.
date_range_preset
Section titled “date_range_preset”A row of preset tabs, with an optional Custom tab for any from–to range. The value expands server-side into two dates before any tile runs.
- name: period label: "Period" type: date_range_preset allow_custom: true # optional — adds a "Custom" tab with from/to dates options: - { value: last_7_days, label: "Last 7 days" } - { value: last_30_days, label: "Last 30 days" } - { value: this_month, label: "This month" } default: last_30_days| Field | Required | Description |
|---|---|---|
options |
Yes, unless allow_custom: true |
The presets offered as tabs. Each value must be a known preset key (below). |
allow_custom |
No | true adds a Custom tab with from/to date inputs. |
value_format |
No | How <name>_from / <name>_to are sent to data sources. See Date format sent to data sources. |
default |
No | One of the control’s own option values. |
Known preset keys:
| Key | Range |
|---|---|
last_7_days |
7 days ago → today |
last_30_days |
30 days ago → today |
this_month |
1st of this month → today |
last_month |
The whole previous month |
this_quarter |
1st day of this quarter → today |
last_quarter |
The whole previous quarter |
this_year |
1 January → today |
next_7_days |
Today → 7 days from now |
next_30_days |
Today → 30 days from now |
next_60_days |
Today → 60 days from now |
next_90_days |
Today → 90 days from now |
The next_* presets look forward, for expiries, renewals and due dates.
Value and derived keys:
- A preset sends its key, e.g.
"last_30_days". A custom range sends{ "from": "2026-01-01", "to": "2026-01-31" }. - Either way, the server expands it into two derived keys,
<name>_fromand<name>_to(ISO dates), before params are resolved. - Tiles usually read the derived keys:
params: - name: start_date from_control: period_from - name: end_date from_control: period_toIn the viewer:
- Clicking a preset tab applies it immediately, without Apply. Clicking the active tab clears it.
- The Custom tab shows two date inputs and waits for Apply. Apply stays disabled until both dates are set and the start is not after the end.
When the API has its own presets: some APIs take a period name rather than dates, e.g. date_preset=last_14d. Use a select with display: tabs for those. It looks the same to the viewer, and the option value is sent to the API exactly as written.
Date format sent to data sources
Section titled “Date format sent to data sources”value_format on a date or date_range_preset control sets how the date reaches a data source through from_control.
- name: period type: date_range_preset options: [last_7_days, last_30_days] value_format: datetimevalue_format |
period_from |
period_to |
|---|---|---|
date (default) |
2026-10-01 |
2026-10-16 |
datetime |
2026-10-01T00:00:00 |
2026-10-16T23:59:59 |
epoch |
1790812800 |
1792195199 |
epoch_ms |
1790812800000 |
1792195199999 |
strftime pattern, e.g. "%d/%m/%Y" |
01/10/2026 |
16/10/2026 |
- End of day: the
_toside is the end of its day (23:59:59), so a<=comparison still includes the whole last day. Adatecontrol is always sent at the start of its day. - Time zone:
epochandepoch_msare computed in UTC.datetimehas no time-zone suffix. - Patterns: anything containing
%is a Python strftime pattern:%Yyear,%mmonth,%dday,%H:%M:%Stime. An invalid pattern is a validation error. - Scope: only what data sources receive changes.
$controls.<name>in expressions always staysYYYY-MM-DD, so asset filters keep working. The bare preset key (from_control: period) is not formatted.
select
Section titled “select”A dropdown with one value.
- name: region label: "Region" type: select options: - { value: EU, label: "Europe" } - { value: US, label: "United States" } default: EUoptions |
Required, non-empty |
| Value | One option value. A numeric option stays a number even though the browser sends "2". |
| Default | One of the control’s own option values |
| Applies | When the viewer clicks Apply. Choosing “— any —” leaves it empty. |
params: - name: region from_control: regionTabs instead of a dropdown
Section titled “Tabs instead of a dropdown”display: tabs shows every option as a tab, the same row a date_range_preset uses.
- name: window label: "Period" type: select display: tabs # dropdown (default) | tabs options: - { value: last_7d, label: "7 days" } - { value: last_14d, label: "14 days" } - { value: last_30d, label: "30 days" } default: last_14d- Clicking a tab applies it immediately, without Apply. Clicking the active tab clears it.
- Only for a single-value select.
display: tabswithmultiple: trueis a validation error. - Best for up to about 7 short options. Validate warns above that.
- The value is sent as written, so this suits APIs with their own period names (
last_14d,30daysAgo,LAST_30_DAYS).
select with multiple: true
Section titled “select with multiple: true”Several values, shown as removable tags plus a searchable dropdown. Typing filters the list, Enter adds the first match, and Backspace on an empty search removes the last tag.
- name: metrics label: "Metrics" type: select multiple: true options: - { value: temperature_2m_max, label: "Max temp" } - { value: precipitation_sum, label: "Rain" } default: [temperature_2m_max, precipitation_sum]| Value | A list of option values, e.g. ["temperature_2m_max", "precipitation_sum"] |
| Default | A YAML list; every element must be one of the options |
| Applies | When the viewer clicks Apply |
How the list reaches the connector depends on where the placeholder sits in the data source:
| Placeholder in the data source | What the connector receives |
|---|---|
"ids": {{ids}} in a JSON body |
A real JSON array, ["a", "b"] |
?metrics={{metrics:csv}} in a URL |
a,b (comma-separated), the form most HTTP APIs expect |
?metrics={{metrics}} in a URL, no :csv |
['a', 'b']. This is kept for Odoo-style Python domains, but most APIs reject it. |
params: - name: metrics # the param name has no :csv — that hint lives only in the data source from_control: metricsnumber
Section titled “number”A single number, with optional bounds.
- name: min_amount label: "Min. amount" type: number min: 0 max: 1000000 step: 1000 default: 10000| Field | Required | Description |
|---|---|---|
min, max |
No | Inclusive bounds. The server rejects values outside them, and min must not exceed max. |
step |
No | Input increment; must be positive. |
default |
No | A number within min/max. |
The value is a number. A whole number is sent as an integer, so "250" arrives as 250.
params: - name: amount_gte from_control: min_amountnumber_range
Section titled “number_range”A min–max pair. Like a date range, the value expands server-side into two derived keys.
- name: price label: "Price" type: number_range min: 0 max: 5000 default: { min: 100, max: 2000 }min, max, step |
Same as number. They bound both sides. |
| Value | { "min": 100, "max": 2000 }. Either side may be empty. |
| Default | { min, max }, either side optional |
| Derived keys | <name>_min and <name>_max |
params: - name: price_gte from_control: price_min - name: price_lte from_control: price_max- A side the viewer leaves empty is not set at all, so the param reading it is skipped rather than sent empty.
- Apply stays disabled while min is greater than max.
- A tile cannot read the control’s bare name (
price), because that value is an object no connector param can use. Readprice_min/price_maxinstead.
toggle
Section titled “toggle”An on/off switch.
- name: include_cancelled label: "Include cancelled" type: toggle default: false| Value | true or false. In a URL it becomes the text true/false. |
| Default | true or false. Without one, the switch shows as off but sends nothing until it is flipped. |
| Applies | Immediately on click, without Apply |
params: - name: include_cancelled from_control: include_cancelledControl values in expressions
Section titled “Control values in expressions”Every JSONata expression in a tile can read the dashboard’s control values as $controls.<name>. This includes filter, row_path, stat metrics, chart and column paths, and summary_card fields. It is the way to filter an asset tile by a control, because asset tiles have no params.
controls: - name: period label: "Expiring within" type: date_range_preset options: [next_30_days, next_60_days, next_90_days] default: next_30_days
tiles: - id: expiring_soon type: table source: { type: asset, category: contract } filter: "$toMillis(properties.expires_at) < $toMillis($controls.period_to) + 86400000" columns: - { label: "Contract", path: "name" } - { label: "Expires", path: "properties.expires_at", type: relative }- Derived keys: these are available too, e.g.
$controls.period_from/$controls.period_toand$controls.price_min/$controls.price_max. - Comparing dates: convert both sides to milliseconds with
$toMillis(...), as above. Comparing date strings directly breaks on same-day timestamps. - Safety: values are passed into the expression as data, never pasted into its text. They are already validated against the control’s type and options.
- Validation: a
$controls.<name>that isn’t a control on the dashboard is a validation error. - Unset controls: a tile that reads a control with no value and no default is held back until the viewer picks one. Give such controls a
default.
Defaults and first load
Section titled “Defaults and first load”default fills a control before the dashboard’s first render.
- With a default: tiles reading the control run straight away.
- Without one: a tile whose param reads the control is held back. It shows “Fill dashboard controls (…) to view this tile” instead of calling the connector with a missing value.
- When to set one: on every control that feeds a required connector param. Otherwise the dashboard loads with empty tiles until the viewer picks something.
- When to leave it out: only when you deliberately want the viewer to choose first.
| Type | Default shape |
|---|---|
date |
today or "YYYY-MM-DD" |
date_range_preset |
One of its own option values |
select |
One of its own option values |
select + multiple |
A list of its own option values |
number |
A number within min/max |
number_range |
{ min, max } |
toggle |
true / false |
Defaults are validated when the dashboard is saved, with the same rules as a live value.
Derived range keys
Section titled “Derived range keys”| Control type | Derived keys a tile can read |
|---|---|
date_range_preset |
<name>_from, <name>_to (ISO dates) |
number_range |
<name>_min, <name>_max (numbers) |
The validator accepts these as from_control targets. Dashboard Studio’s params picker lists them, e.g. “Period → from (period_from)”.
Server-side validation
Section titled “Server-side validation”The viewer’s widgets only offer legal values, but the tile-execute API accepts any JSON. So every value is checked on the server before any connector is called:
| Type | Rule |
|---|---|
select |
Must be one of the control’s options |
select + multiple |
Must be a list, and every item must be one of the options |
date_range_preset |
A key that is one of the control’s own options, or (with allow_custom) {from, to} ISO dates with from ≤ to |
date |
An ISO date |
number |
A number (not a boolean) within min/max |
number_range |
{min, max} numbers within bounds, min ≤ max |
toggle |
true/false (or the strings "true"/"false") |
- Illegal values: a request carrying one fails with HTTP 400, and the tile shows the error.
- Unknown keys: keys that aren’t a control on the dashboard are dropped and never reach a connector.
- Empty values:
"",[]andnullmean “not set”. - Subscriptions: their fixed
control_valuesare checked with the same rules when the dashboard is saved.
Viewer behaviour
Section titled “Viewer behaviour”- Apply: most controls update a draft and wait for Apply. Preset tabs, select tabs and toggles apply on click.
- Clear: resets every control and re-runs the tiles.
- Validation messages: Apply is disabled while a custom date range or number range is incomplete or inverted, and the problem is shown under the controls.
Complete example
Section titled “Complete example”controls: - { name: period, label: "Period", type: date_range_preset, allow_custom: true, options: [last_7_days, last_30_days, this_month], default: last_7_days } - { name: as_of, label: "As of", type: date, default: today } - { name: region, label: "Region", type: select, options: [EU, US, APAC], default: EU } - { name: teams, label: "Teams", type: select, multiple: true, options: [web, data, platform], default: [web, data] } - { name: top_n, label: "Show top", type: number, min: 1, max: 50, default: 10 } - { name: cost, label: "Cost", type: number_range, min: 0, default: { min: 0, max: 5000 } } - { name: active_only, label: "Active only", type: toggle, default: true }
tiles: - id: servers type: table label: "Servers" data_processor: source_name: "Server Inventory API" params: - { name: from, from_control: period_from } - { name: to, from_control: period_to } - { name: snapshot_date, from_control: as_of } - { name: region, from_control: region } - { name: teams, from_control: teams } # data source: ?teams={{teams:csv}} - { name: limit, from_control: top_n } - { name: cost_gte, from_control: cost_min } - { name: cost_lte, from_control: cost_max } - { name: active, from_control: active_only } row_path: "data" columns: - { label: "Server", path: "name" }