Skip to content

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.

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.

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.

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 }
  • value is what the tile receives, and label is 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_of

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

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>_from and <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_to

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

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: datetime
value_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 _to side is the end of its day (23:59:59), so a <= comparison still includes the whole last day. A date control is always sent at the start of its day.
  • Time zone: epoch and epoch_ms are computed in UTC. datetime has no time-zone suffix.
  • Patterns: anything containing % is a Python strftime pattern: %Y year, %m month, %d day, %H:%M:%S time. An invalid pattern is a validation error.
  • Scope: only what data sources receive changes. $controls.<name> in expressions always stays YYYY-MM-DD, so asset filters keep working. The bare preset key (from_control: period) is not formatted.

A dropdown with one value.

- name: region
label: "Region"
type: select
options:
- { value: EU, label: "Europe" }
- { value: US, label: "United States" }
default: EU
options 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: region

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: tabs with multiple: true is 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).

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: metrics

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_amount

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. Read price_min / price_max instead.

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_cancelled

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_to and $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.

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.

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

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: "", [] and null mean “not set”.
  • Subscriptions: their fixed control_values are checked with the same rules when the dashboard is saved.
  • 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.
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" }