Variable UI Elements¶
Complete reference for all variable input types and their configuration options.
Overview¶
Each variable can optionally specify an input property that determines what UI control is rendered. If not specified, the input type is given a smart default based on the type. You can override the default by explicitly setting input to match your intended use case.

One of every input type below, rendered together in a single variables strip.
A strip with two or more controls also shows a Reset control after the last
one. It returns every filter in that strip to its default. Hidden variables
(visible: false) keep their values.
Input Types¶
select - Single Choice Dropdown¶
Renders a dropdown menu allowing users to select one option from a list.
A menu with 10 or more options opens with a search box that narrows the list as you type. Press Enter to pick the first match.

Value shape: string
Configuration:
variables: region: input: select options: static: [North, South, East, West] # Optional: default: North # Initial selection placeholder: "Select a region..."
Options Source:
- options.static: Array of static values, all strings or all numbers
- options.query: Reference to a query that returns options
- column: Automatically populated from column values
Value type. The browser sends a chosen option back as text, and the value
has to reach SQL with the column's type: BigQuery and Trino refuse to compare
an integer column with a string. A numeric options.static list types the
value as a number by itself. When the options come from a query (or a
column:), the value takes the declared type of the options column: boolean,
number or date, else text. data_type overrides that (a date-typed choice
compares the column as a date, like a date input).
variables: year: input: select options: query: years data_type: number
Select controls render the options you provide. dbt Charts does not add an "All" option to that list automatically. An unset select is already no filter (filter() emits 1=1), so the usual all/no-filter choice is to leave the variable unset. A non-required select's open menu shows an italic clear-selection row above a divider (see the screenshot above) — labeled All unless the variable sets a placeholder:, in which case that text is used instead. It's a clear-selection affordance, not an authored option; picking it unsets the variable rather than sending a literal "All" value to your query. If you author an explicit option for it, give it the same type as the others: a list mixing numbers and words ([2023, 2024, All]) is refused, because the list is what types the value the control sends back.
Example:
variables: priority: column: dundersign.tickets.priority input: select # Options auto-populated from column
multiselect - Multiple Choice Dropdown¶
Renders a dropdown menu allowing users to select multiple options.
A menu with 10 or more options opens with a search box that narrows the list as you type. Press Enter to tick the first match. The search stays in place while you pick, so you can tick several matches in a row.

Value shape: array / string[]
Configuration:
variables: regions: input: multiselect options: static: [North, South, East, West] # Optional: default: [North, South] # Initial selections
Usage in Filters:
When using multiselect variables with the filter() macro, use the IN operator:
variables: priorities: input: multiselect options: static: [low, normal, high, urgent] queries: tickets: sql: | SELECT * FROM dundersign.tickets WHERE {{ filter('priority', priorities, 'IN') }} source: my_postgres
input / text - Text Input¶
Renders a single-line text input field for free-form text entry.

Value shape: string
Configuration:
variables: search_term: input: text # or 'input' placeholder: "Enter search term..." # Optional: default: ""
Example:
variables: product_name: input: text placeholder: "Search products..."
textarea - Multi-line Text Input¶
Renders a multi-line text area for longer text input.

Note: textarea currently renders as the same single-line field as
text; there is no multi-line box in the variables strip yet.
Value shape: string
Configuration:
variables: notes: input: textarea placeholder: "Enter notes..." # Optional: default: ""
number - Numeric Input¶
Renders a numeric input field with optional min/max/step constraints.

Value shape: number
Configuration:
variables: min_revenue: input: number # Optional bounds, enforced when a value is committed: one past min or max # lands on the bound, and one off the step grid lands on the nearest step. min: 0 max: 1000000 step: 100 # Optional hint, shown muted while the field is empty. A default fills the # field, so the two are not used together. placeholder: "Enter minimum revenue"
Optional Properties:
- min: Minimum allowed value
- max: Maximum allowed value
- step: Increment/decrement step size
- placeholder: Hint shown while the field is empty
- default: Value the field starts with
slider - Numeric Slider¶
Renders a range slider for selecting numeric values within a range.

Value shape: number
Configuration:
variables: top_n: input: slider min: 1 max: 100 step: 1 # Optional: default: 10 label: "Top N Results"
Required Properties:
- min: Minimum slider value
- max: Maximum slider value
- step: Slider step size
Example:
variables: limit: input: slider min: 5 max: 50 step: 5 default: 15
datepicker - Single Date Picker¶
Renders a date picker for selecting a single date.

Value shape: date
Configuration:
variables: start_date: input: datepicker # Optional: default: "2024-01-01"
Usage:
queries: sales: sql: | SELECT * FROM dundersign.tickets WHERE {{ filter('created_at', start_date, '>=') }} source: my_postgres
daterange - Date Range Picker¶
Renders a date range picker for selecting start and end dates.

Value shape: date (returns object with start and end properties)
Configuration:
variables: date_range: input: daterange # Optional: default: ["2024-01-01", "2024-12-31"]
Rolling presets: a value can name a window instead of dates. It resolves to dates on every render, so the board and any link to it stay current:
variables: date_range: input: daterange default: last_90_days
A preset name follows a small grammar (N is a positive integer; units are days, weeks, months, quarters, years):
| Name | Window (inclusive) |
|---|---|
today, yesterday |
That day |
last_<N>_<unit> |
Calendar-aligned: the current unit (partial, through today) plus the N−1 units before it. On 2026-10-28, last_12_months is 2025-11-01 to 2026-10-28 and last_4_quarters is 2026-01-01 to 2026-10-28. Weeks start on the board's week start. last_<N>_days is the rolling count: the N days ending today (last_90_days) |
previous_<N>_<unit> |
Complete units only: the N units before the current one, excluding the current partial unit (previous_3_quarters) |
before_previous_<N>_<unit> |
Everything before the start of previous_<N>_<unit>, with no lower bound (before_previous_4_fiscal_quarters) |
this_<unit> |
The current week, month, quarter or year, start to end |
<unit>_to_date |
Start of the current week, month, quarter or year through today (month_to_date) |
Put fiscal_ before quarter or year to use the fiscal calendar (this_fiscal_quarter, fiscal_year_to_date, last_4_fiscal_quarters, previous_1_fiscal_year); it opens in the month set by regional.fiscal_year_start_month (January by default). Weeks start on Monday.
The same names work as a URL parameter (?date_range=last_7_days), with --var date_range=last_7_days, and as a literal in SQL: {{ filter_date_range('order_ts', 'last_30_days') }}. Picking a preset in the control commits its name. "Today" is the date in the board's regional.time_zone, UTC by default. For a naive timestamp column that stores UTC, write {{ filter_date_range('order_ts', date_range, is_naive_utc=true) }} to compare by its date in that zone.
The picker's menu is a list of names. style.variables.presets sets it for every daterange control (in meta.yml or a board's style:); a variable's own presets: replaces it. default: is independent of the menu:
variables: date_range: input: daterange default: last_30_days presets: - last_30_days - previous_3_quarters - this_fiscal_quarter
To show the presets as a row of buttons instead of a menu inside the picker, set style.variables.presets_display: buttons (default menu). It applies to every daterange on the board. Buttons use compact labels (1D, 5D, MTD, 3M, 6M, YTD, 12M, 5Y). Because last_ presets are calendar-aligned, last_1_months reads MTD and last_1_years reads YTD; presets with no compact spelling, such as previous_3_months or the fiscal forms, keep their long label. Each button links by preset name (?span=last_6_months), never by dates, so shared links stay live. The button row draws no label and offers presets only, so there is no calendar for a custom range. The overflow rules are the same as for radio.
style: variables: presets_display: buttons variables: span: input: daterange default: last_6_months presets: - today - last_5_days - last_1_months - last_3_months - last_6_months - year_to_date - last_12_months - last_5_years
Usage:
Use the filter_date_range() macro for date ranges:
queries: sales: sql: | SELECT * FROM dundersign.tickets WHERE {{ filter_date_range('created_at', date_range) }} source: my_postgres
Or access start/end directly:
queries: sales: sql: | SELECT * FROM dundersign.tickets WHERE created_at >= '{{ date_range[0] }}' AND created_at <= '{{ date_range[1] }}' source: my_postgres
checkbox - Boolean Toggle¶
Renders a checkbox for boolean true/false values.

Value shape: boolean
Configuration:
variables: show_details: input: checkbox # Optional: default: false label: "Show Details"
Usage:
Commonly used for conditional rendering:
rows: - visible: show_details rows: - detail_chart # Chart only shown when checkbox is checked
radio - Radio Button Group¶
Renders a group of radio buttons for selecting one option from a small set.

Every option is visible at once, as a row of joined buttons. Each button is a plain link (?view_type=Detailed), so a shared link keeps the choice and the buttons need no script to act. They appear on a live board, once its page loads the controls script. Clicking the selected button clears the variable, unless it is required: true, in which case it does nothing. A variable with no value selects no button; dbt Charts never adds an "All" button. To offer one, write it as an option and handle it in the query.
In a static export (PNG, PDF, a saved SVG) the control shows the selected value only, like every other control.
Only options.static draws a button row. A radio whose options come from a query (options.query or column) draws the same dropdown as a select, because its options are not known until the query has run, after the board's layout is fixed.
The selected button is a light tint of the label color. A theme can fill it solid instead with style.variables.input.selected_background and style.variables.input.selected_color; the stark theme does.
A button row wider than its slot draws as the same dropdown a select uses, and the render reports WARN-VARIABLE-BUTTONS-OVERFLOW. Set style.variables.overflow: wrap to let the button row flow onto further rows instead:
style: variables: overflow: wrap
A radio's options are plain values, and {{ group_by }} in SQL is a bound parameter, so it cannot name a column. To group by the chosen option, map each option to its column with {% if %}:
variables: group_by: input: radio options: static: [Rep, Lead source, Deal type] default: Rep queries: by_group: sql: | SELECT {% if group_by == 'Lead source' %}lead_source {% elif group_by == 'Deal type' %}opportunity_type {% else %}owner_name{% endif %} AS grp, SUM(amount) AS won_amount FROM main.opportunities GROUP BY 1
To place a button row above one chart, wrap the chart in a nested board that declares the variable; the button row draws below the nested board's title. Every control in a nested board's band is style.variables.compact_height tall (24 by default), whatever its type, unless style.variables.input.height is authored on that board or a board above it, and the band sits style.variables.gap below the title or text above it. A board's own band keeps style.variables.input.height.
Value shape: string
Configuration:
variables: view_type: input: radio options: static: [Summary, Detailed, Compact] # Optional: default: Summary
Best For: - Small sets of options (2-5 choices) - When you want all options visible at once - When the selection affects layout or display mode
Common Properties¶
All input types support these optional properties:
label¶
Override the auto-generated label (defaults to variable name):
variables: region: label: "Select Region" input: select
placeholder¶
Set placeholder text for text inputs:
variables: search: input: text placeholder: "Search products..."
default¶
Set the initial value before user interaction:
variables: region: input: select options: static: [North, South, East, West] default: North
Note: If no default is set, the variable starts as null/undefined. When used with the filter() macro, unset returns 1=1 (no filter applied). A non-required select like this one can always get back to that unset state via its menu's clear-selection row (see select - Single Choice Dropdown), without needing an authored option for it.
required¶
Block rendering until the variable has a value:
variables: region: input: select required: true options: static: [North, South, East, West]
Input Type Selection Guide¶
| Use Case | Recommended Input |
|---|---|
| Single selection from many options | select |
| Multiple selections | multiselect |
| Free-form text search | text / input |
| Long text input | textarea |
| Numeric value with constraints | number |
| Numeric value in a range | slider |
| Single date selection | datepicker |
| Date range selection | daterange |
| Boolean toggle | checkbox |
| Small set of mutually exclusive options | radio |
Related¶
- Variables – Basic variable setup and wiring
- Expressions – Using variables in queries and filters
- Advanced Variables – Dependent variables and conditional logic