Skip to content

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.

A variables strip with one control of every documented input type: select, multiselect, text, textarea, number, slider, datepicker, daterange, checkbox, and radio

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.

The Priority select control and its open option menu, offering an italic All row above low, normal, high, and urgent

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.

The Ticket type multiselect control and its open option menu, an italic All row above task, problem, question, and incident, with problem and incident checked

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.

The Search text input, showing its placeholder text

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.

The Triage notes control, rendered as a single-line text field showing its placeholder

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.

The Minimum age (days) number input, showing its default value of 0

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.

The Rows to show slider, thumb positioned at its default value of 15

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.

The Start date datepicker field, showing 1 Jan 2026

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.

The Date range field, showing 1 Jan to 1 Aug 2026

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.

The Show ticket list checkbox, checked

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.

The View control, a row of buttons with Summary selected

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