Button Group

{% button_group
    id="category_filter"
    data="demo.daily_orders"
    value_column="category"
/%}

{% bar_chart
    data="demo.daily_orders"
    x="date"
    y="sum(total_sales)"
    filters=["category_filter"]
    date_grain="month"
/%}

Examples

Using `filters`

{% button_group
    id="category_filter"
    data="demo.daily_orders"
    value_column="category"
/%}

{% bar_chart
    data="demo.daily_orders"
    x="date"
    y="sum(total_sales)"
    filters=["category_filter"]
    date_grain="month"
/%}

Using `where`

{% button_group
    id="category_filter"
    data="demo.daily_orders"
    value_column="category"
/%}

{% bar_chart
    data="demo.daily_orders"
    x="date"
    y="sum(total_sales)"
    where="category = {{category_filter}}"
    date_grain="month"
/%}

Using Inline SQL

{% button_group
    id="category_filter"
    data="demo.daily_orders"
    value_column="category"
/%}

```sql filtered_orders
select * from demo.daily_orders
where category = {{category_filter}}
```

{% table data="filtered_orders" /%}

Vertical orientation inside a row

{% row %}

{% button_group
    id="category_filter"
    data="demo.daily_orders"
    value_column="category"
    orientation="vertical"
/%}

{% bar_chart
    data="demo.daily_orders"
    x="date"
    y="sum(total_sales)"
    filters=["category_filter"]
    date_grain="month"
/%}

{% /row %}

Attributes

string

required

The id of the button group to be used in a filters prop

data

string

Name of the table to query

filters

array

Array of filter IDs to apply when querying for options

value_column

string

Column name to use as the value for each option, and the column to filter by when this button group’s id is used in the filters prop of a chart

label_column

string

Column name to use as the label for each option

title

string

Text displayed above the button group

info

string

Information tooltip text

initial_value

string | number | array

Initial selected value(s)

multiple

boolean

default:"false"

Allows multiple selections

select_first

boolean

default:"false"

Automatically select the first option when the component loads

orientation

string

default:"horizontal"

Layout direction of the button group. Use “vertical” to stack buttons in a column. Best paired with a sibling element inside a row so the stack sits alongside its target content.Allowed values:

horizontal
vertical

max_height

number

Maximum height in pixels for the button stack when orientation="vertical". Buttons scroll if the list overflows. Ignored when horizontal.

order

string

Column name(s) with optional direction (e.g. “column_name”, “column_name desc”)

where

string

Custom SQL WHERE condition to apply to the query. For date filters, use date_range instead.

date_range

options group

Use date_range to filter data for specific time periods. Accepts predefined ranges (e.g., “last 12 months”), dynamic ranges (e.g., “Last 90 days”), custom date ranges (e.g., “2020-01-01 to 2023-03-01”), or partial ranges (e.g., “from 2020-01-01”, “until 2023-03-01”)Example:

date_range={
  range = "today"
  date = "string"
}

Attributes:

range: string - Time period to filter. Use presets like ‘last 7 days’, dynamic patterns like ‘Last 90 days’, custom ranges like ‘2020-01-01 to 2023-03-01’, or partial ranges like ‘from 2020-01-01’.
- Allowed values:
  - today
  - yesterday
  - last 7 days
  - last 30 days
  - last 3 months
  - last 6 months
  - last 12 months
  - previous week
  - previous month
  - previous quarter
  - previous year
  - this week
  - this month
  - this quarter
  - this year
  - next week
  - next month
  - next quarter
  - next year
  - week to date
  - month to date
  - quarter to date
  - year to date
  - all time
date: string - Date column to filter on. Required when the data has multiple date columns.

Using the Filter Variable

Reference this filter using {{filter_id}}. The value returned depends on where you use it. The examples below show values for three scenarios:

No selection
Single select: “Electronics” selected
Multi select: “Sports” and “Home” selected (when multiple=true)

Context	Default Property	No Selection	Single Select	Multi Select
Inline SQL query	`.selected`	`''`	`'Electronics'`	`('Sports', 'Home')`
`where` attribute	`.selected`	`''`	`'Electronics'`	`('Sports', 'Home')`
Text / Markdown	`.literal`		`Electronics`	`Sports, Home`

Available Properties

You can also access specific properties using {{filter_id.property}}:

.filter

Returns a complete SQL filter expression ready to use in WHERE clauses. Returns true when no value is selected.

{% button_group id="category_filter" data="products" value_column="category" /%}

```sql filtered_products
select * from products
where {{category_filter.filter}}
```

No Selection	Single Select	Multi Select
`true`	`category = 'Electronics'`	`category IN ('Sports', 'Home')`

.selected

Returns the selected value(s) wrapped in quotes, suitable for SQL comparisons. Returns an empty string when no value is selected.

{% button_group id="category_filter" data="products" value_column="category" /%}

```sql products_by_category
select * from products
where category = {{category_filter.selected}}
```

No Selection	Single Select	Multi Select
`''`	`'Electronics'`	`('Sports', 'Home')`

.literal

Returns the raw unescaped selected value(s), useful for display in text or dynamic column selection.

{% button_group id="sort_column" data="products" value_column="column_name" /%}

```sql dynamic_sort
select * from products
order by {{sort_column.literal}}
```

No Selection	Single Select	Multi Select
“	`Electronics`	`Sports, Home`

.label

Returns the display label for the selected option(s). Falls back to the value if no label is defined.

{% button_group id="category_filter" %}
    {% option value="Electronics" label="Electronics" /%}
    {% option value="Sports" label="Sports" /%}
    {% option value="Home" label="Home" /%}
{% /button_group %}

Selected: {{category_filter.label}}

No Selection	Single Select	Multi Select
“	`Electronics`	`Sports, Home`

.fmt

Returns the format string associated with the selected option. For multiple selections, returns the first format.

{% button_group id="metric_selector" %}
    {% option value="revenue" label="Revenue" fmt="usd" /%}
    {% option value="growth_rate" label="Growth Rate" fmt="pct1" /%}
{% /button_group %}

{% big_value data={metrics} value=value fmt={{metric_selector.fmt}} /%}

No Selection	Single Select	Multi Select
“	`usd`	`usd`

Allowed Children

option

Get Started

Core Concepts

Features

CLI

Warehouses

Evidence Warehouse

Components

Examples

Using `filters`

Using `where`

Using Inline SQL

Vertical orientation inside a row

Attributes

Using the Filter Variable

Available Properties

.filter

.selected

.literal

.label

.fmt

Allowed Children

​Examples

​Using filters

​Using where

​Using Inline SQL

​Vertical orientation inside a row

​Attributes

​Using the Filter Variable

​Available Properties

​.filter

​.selected

​.literal

​.label

​.fmt

​Allowed Children

Examples

Using `filters`

Using `where`

Using Inline SQL

Vertical orientation inside a row

Attributes

Using the Filter Variable

Available Properties

.filter

.selected

.literal

.label

.fmt

Allowed Children