Button Group

Display a segmented button group with distinct values from a database column to use in 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"
/%}

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" /%}

Attributes

id · 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

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 = "last 7 days"
  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:
    • 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