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.

Input Types

select - Single Choice Dropdown

Renders a dropdown menu allowing users to select one option from a list.

Data Type: 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 - options.query: Reference to a query that returns options - column: Automatically populated from column values - dimension: Automatically populated from MetricFlow dimension

Example:

variables:
  region:
    column: orders.region
    input: select
    # Options auto-populated from column

multiselect - Multiple Choice Dropdown

Renders a dropdown menu allowing users to select multiple options.

Data Type: 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:

queries:
  sales:
    sql: |
      SELECT * FROM orders
      WHERE {{ filter('region', 'IN', regions) }}
    profile: my_postgres

input / text - Text Input

Renders a single-line text input field for free-form text entry.

Data Type: 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.

Data Type: 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.

Data Type: number

Configuration:

variables:
  min_revenue:
    input: number
    min: 0
    max: 1000000
    step: 100
    # Optional:
    default: 0
    placeholder: "Enter minimum revenue"

Required Properties: - min: Minimum allowed value - max: Maximum allowed value - step: Increment/decrement step size

slider - Numeric Slider

Renders a range slider for selecting numeric values within a range.

Data Type: 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.

Data Type: date

Configuration:

variables:
  start_date:
    input: datepicker
    # Optional:
    default: "2024-01-01"

Usage:

queries:
  sales:
    sql: |
      SELECT * FROM orders
      WHERE {{ filter('order_date', '>=', start_date) }}
    profile: my_postgres

daterange - Date Range Picker

Renders a date range picker for selecting start and end dates.

Data Type: date (returns object with start and end properties)

Configuration:

variables:
  date_range:
    input: daterange
    # Optional:
    default:
      start: "2024-01-01"
      end: "2024-12-31"

Usage:

Use the filter_date_range() macro for date ranges:

queries:
  sales:
    sql: |
      SELECT * FROM orders
      WHERE {{ filter_date_range('order_date', date_range) }}
    profile: my_postgres

Or access start/end directly:

queries:
  sales:
    sql: |
      SELECT * FROM orders
      WHERE order_date >= '{{ date_range.start }}'
        AND order_date <= '{{ date_range.end }}'
    profile: my_postgres

checkbox - Boolean Toggle

Renders a checkbox for boolean true/false values.

Data Type: boolean

Configuration:

variables:
  show_details:
    input: checkbox
    # Optional:
    default: false
    label: "Show Details"

Usage:

Commonly used for conditional rendering:

charts:
  detail_chart:
    include: "{{ show_details }}"
    # 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.

Data Type: 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, this returns 1=1 (no filter applied).

allow_null

Allow the variable to be explicitly set to null/empty:

variables:
  region:
    input: select
    allow_null: 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