When to use

Invoke when the user asks to:

• Add a filter, dropdown, date picker, or search box to a page
• Make a page interactive or let users filter the displayed data
• Use DateRange, Dropdown, TextInput, ButtonGroup, or Slider components

Evidence Input Components

Level 1 — What each input does, minimal syntax, and the variable it creates

All inputs expose their value via the inputs object in SQL and markdown. The variable name is whatever you pass to name=.

Dropdown

Lets users pick one or many values from a list. Options can come from a query or be hardcoded.

<Dropdown name=my_filter data={query} value=column_name />

Variable: {inputs.my_filter.value} — single string, or comma-separated list when multiple=true

TextInput

A freeform text box for search or string filtering.

<TextInput name=search_term />

Variable: {inputs.search_term} (no .value suffix needed)

Checkbox

A toggleable boolean. Returns true or false.

<Checkbox name=exclude_flag title="Exclude low values" />

Variable: {inputs.exclude_flag} — boolean true or false

DateInput

A date picker. Can operate in single-date or range mode (via the range prop).

<DateInput name=selected_date data={orders} dates=order_date />

Single-date variable: {inputs.selected_date.value} Range variables: {inputs.selected_date.start} and {inputs.selected_date.end}

DateRange

A dedicated date-range picker with preset options. Always produces start/end values.

<DateRange name=date_window data={orders} dates=order_date />

Variables: {inputs.date_window.start} and {inputs.date_window.end}

Slider

A numeric range slider. Returns the selected number.

<Slider name=min_sales title="Min Sales" min=0 max=10000 defaultValue=500 />

Variable: {inputs.min_sales} (no .value suffix)

ButtonGroup

Single-select button strip. Good for a small, fixed list of options.

<ButtonGroup name=selected_category data={categories} value=category />

Variable: {inputs.selected_category} (no .value suffix)

DimensionGrid

An interactive grid of dimension tables — one per string column in the source query. Produces a SQL condition fragment suitable for direct use in a WHERE clause.

<DimensionGrid data={orders} name=dimension_filter metric='sum(sales)' />

Variable: ${inputs.dimension_filter} — emits a SQL boolean expression like category = 'Toys' and state = 'CA', or true when nothing is selected.

Level 2 — Common props and practical filter examples

How inputs connect to queries

Wrap input variables inside ${} in your SQL code blocks. The query re-runs automatically when the input changes.

Single-value equality (Dropdown / ButtonGroup / TextInput)

select * from orders
where item = '${inputs.selected_item.value}'

LIKE pattern match — useful for TextInput or a wildcard default

select * from orders
where item like '${inputs.search_term}'

Multi-select IN clause (Dropdown with multiple=true) Use IN and omit quotes around ${}:

select * from orders
where category in ${inputs.category_filter.value}

Date range filter (DateRange or DateInput with range)

select * from orders
where order_date between '${inputs.date_window.start}' and '${inputs.date_window.end}'

Single date threshold (DateInput)

select * from orders
where order_date > '${inputs.cutoff_date.value}'

Numeric threshold (Slider)

select * from orders
where sales >= ${inputs.min_sales}

Boolean flag (Checkbox)

select * from orders
where not ${inputs.exclude_low_value}
    or (${inputs.exclude_low_value} and sales >= 10)

DimensionGrid passthrough DimensionGrid outputs a ready-made SQL fragment — use it without quotes:

select * from orders
where ${inputs.dimension_filter}

Common props shared by most inputs

Dropdown — practical examples

Query-populated with a default and title

<Dropdown
    data={categories}
    name=cat_filter
    value=category_name
    title="Category"
    defaultValue="Sinister Toys"
/>

Multi-select with pre-selected defaults

<Dropdown
    data={categories}
    name=cat_filter
    value=category_name
    multiple=true
    defaultValue={['Sinister Toys', 'Odd Equipment']}
/>

Use in ${inputs.cat_filter.value} (no quotes) in your SQL.

"All items" wildcard via DropdownOption + LIKE

<Dropdown name=item_filter data={items} value=item>
    <DropdownOption value="%" valueLabel="All Items" />
</Dropdown>

where item like '${inputs.item_filter.value}'

Hardcoded options

<Dropdown name=status_filter>
    <DropdownOption value="active" valueLabel="Active" />
    <DropdownOption value="inactive" valueLabel="Inactive" />
</Dropdown>

TextInput — fuzzy search

TextInput supports fuzzy (Damerau-Levenshtein) search via a helper syntax:

select * from customers
order by {inputs.name_search.search('customer_name')}
limit 10

This is different from a like filter — it ranks results by similarity rather than filtering them out.

DateInput — preset range defaults

When using range mode, you can give a preset as the default:

<DateInput
    name=date_picker
    range
    defaultValue={'Last 30 Days'}
/>

Available presets: 'Last 7 Days' 'Last 30 Days' 'Last 90 Days' 'Last 3 Months' 'Last 6 Months' 'Last 12 Months' 'Last Month' 'Last Year' 'Month to Date' 'Year to Date' 'All Time'

ButtonGroup — style as tabs

<ButtonGroup name=view_mode data={options} value=option display=tabs />

Hardcoded with a default:

<ButtonGroup name=period>
    <ButtonGroupItem value="daily" valueLabel="Daily" />
    <ButtonGroupItem value="weekly" valueLabel="Weekly" default />
    <ButtonGroupItem value="monthly" valueLabel="Monthly" />
</ButtonGroup>

Level 3 — Full prop reference tables and combining inputs

Dropdown

DropdownOption (for hardcoded options inside <Dropdown>):

TextInput

Checkbox

DateInput

DateRange

Available preset strings for both date components: 'Last 7 Days' 'Last 30 Days' 'Last 90 Days' 'Last 365 Days' 'Last 3 Months' 'Last 6 Months' 'Last 12 Months' 'Last Month' 'Last Year' 'Month to Date' 'Month to Today' 'Year to Date' 'Year to Today' 'All Time'

Slider

ButtonGroup

ButtonGroupItem (for hardcoded options):

DimensionGrid

Combining multiple inputs

All inputs on a page can be used together in a single query. Chain them in your WHERE clause:

<Dropdown name=category data={categories} value=category_name title="Category" />
<DateRange name=date_range defaultValue={'Last 30 Days'} />
<Slider name=min_sales title="Min Sales ($)" min=0 max=50000 step=500 fmt="usd0" />
<TextInput name=search title="Search item name" placeholder="Type to filter..." />

select
    order_date,
    category,
    item,
    sales
from orders
where category = '${inputs.category.value}'
  and order_date between '${inputs.date_range.start}' and '${inputs.date_range.end}'
  and sales >= ${inputs.min_sales}
  and item like '%${inputs.search}%'

Key rules when combining:

• Dropdown single-select and ButtonGroup: use = '${inputs.name.value}' (quoted)
• Dropdown multi-select: use in ${inputs.name.value} (no quotes, no parentheses — Evidence handles them)
• TextInput direct match: quoted '${inputs.name}'; fuzzy: order by {inputs.name.search('col')}
• DateInput / DateRange: always quoted '${inputs.name.start}'
• Slider / Checkbox: never quoted — they emit numbers and booleans
• DimensionGrid: never quoted — it emits a complete SQL expression

Referencing values in markdown text (outside SQL):

Showing {inputs.category.value} orders from {inputs.date_range.start} to {inputs.date_range.end}
with sales above {inputs.min_sales}

Parallelisation

Safe — writes only to .md page files.