Dropdown

{% dropdown
    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`

{% dropdown
    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`

{% dropdown
    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

{% dropdown
    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

string

required

The id of the dropdown 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 dropdown options

value_column

string

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

label_column

string

Column name to use as the label for each option

options

array

List of options to display in the dropdown

title

string

Text displayed above the dropdown

info

string

Information tooltip text

info_link

string

URL to link the info text to (can only be used with info)

info_link_title

string

Create a custom link title for the info link, placed after the info text (can only be used with info_link)

icon

string

Icon to display in the dropdown triggerAllowed values:

trending-up
trending-down
clock
calendar
check
x
info
alert-circle
help-circle
eye
eye-off
user
users
settings
cog
plus
minus
up
down
right
left
star
heart
search
file
file-text
home
mail
filter
share
bell
trash
credit-card
globe
key
croissant
map
rotate
rewind
bank
receipt
activity
chart-column
chart-pie
chart-no-axes-combined
goal
rocket
trophy
apple
cookie
donut
beef
cake
soup
utensils
milk
nut
pyramid
triangle
arrow-down
arrow-left
arrow-right
arrow-up
chevron-down
chevron-left
chevron-right
chevron-up
chevrons-down
chevrons-left
chevrons-right
chevrons-up
menu
external-link
check-circle
x-circle
edit
trash-2
copy
save
download
upload
send
refresh
redo
undo
folder
folder-open
image
file-image
user-plus
user-minus
user-check
lock
unlock
log-in
log-out
message-square
message-circle
phone
phone-call
bell-off
video
video-off
play
pause
stop
skip-back
skip-forward
volume
volume-1
volume-2
volume-off
volume-x
bookmark
tag
link
unlink
share-2
alert-triangle
loader
more-vertical
more-horizontal
grid
list
maximize
minimize
zoom-in
zoom-out
thumbs-up
thumbs-down
shopping-cart
dollar-sign
camera
printer
monitor
smartphone
laptop
calculator
cloud-sun-rain
sun-snow
thermometer-sun
thermometer-snowflake
cloudy
cloud-rain-wind
cloud-rain
wind
sun
cloud-snow
thermometer
cloud-drizzle
cloud-sun
cloud
cloud-lightning
snowflake
flame
atom
fuel
magnet
factory
tree-deciduous
waypoints
plug
dam
battery

initial_value

string | array

Initial selected value(s)

select_first

boolean

default:"false"

Automatically select the first option when the component loads

placeholder

string

Placeholder text displayed when no value is selected

boolean

default:"true"

Includes a search input within the dropdown menu

multiple

boolean

default:"false"

Allows multiple selections

clear

boolean

default:"true"

Includes a clear button to unselect the selected value(s)

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.

width

number

Set the width of this component (in percent) relative to the page width

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.

{% dropdown 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.

{% dropdown 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.

{% dropdown 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.

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

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.

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

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

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

Get Started

Core Concepts

Data Sources

Components

Examples

Using `filters`

Using `where`

Using Inline SQL

Attributes

Using the Filter Variable

Available Properties

.filter

.selected

.literal

.label

.fmt

Allowed Children

Get Started

Core Concepts

Data Sources

Components

​Examples

​Using filters

​Using where

​Using Inline SQL

​Attributes

​Using the Filter Variable

​Available Properties

​.filter

​.selected

​.literal

​.label

​.fmt

​Allowed Children

Examples

Using `filters`

Using `where`

Using Inline SQL

Attributes

Using the Filter Variable

Available Properties

.filter

.selected

.literal

.label

.fmt

Allowed Children