> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evidence.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Variables

> Create reusable values for use in markdown and SQL.

## Defining Variables

### In Frontmatter

Variables can be defined in [YAML](https://quickref.me/yaml.html) frontmatter at the top of your document:

```markdown theme={null}
---
company:
  name: Acme Corp
  industry: Manufacturing
  employees: 121
category: Home
---
```

These live in the same frontmatter block as a page's [settings](/features/page-settings) — any key that isn't a reserved page setting is treated as a variable.

### In Inputs

Some components create variables that can be used elsewhere in your markdown, for example the [dropdown](/components/dropdown) component.

When you add an input component, it creates a variable using the `id` attribute:

```markdown theme={null}
{% dropdown
  id="category_dropdown" <!-- [!code ++] -->
  data="demo.daily_orders"
  value_column="category"
/%}
```

All available filters for your page can be found in the **Filters** tab in the sidebar.

## Built-in Variables

Some variables are automatically available based on the logged-in user:

| Variable                   | Example                                     |
| -------------------------- | ------------------------------------------- |
| `{{ $user.first_name }}`   | Edward                                      |
| `{{ $user.last_name }}`    | Tufte                                       |
| `{{ $user.email }}`        | [edward@tufte.com](mailto:edward@tufte.com) |
| `{{ $organization.name }}` | Beautiful Evidence                          |

## Using Variables

Reference variables using double curly braces `{{ my_variable }}`. Variables defined in frontmatter use the `$` prefix: `{{ $my_variable }}`.

### In Markdown

Use variables inline in your text content:

#### From Frontmatter

```markdown theme={null}
# {{ $company.name }} Dashboard

{{ $company.name }} has {{ $company.employees }} employees.
```

#### From Inputs

```markdown theme={null}
# {{ category_dropdown }} Performance
```

### In Component Attributes

Reference variables in component attributes with curly braces `{{}}`:

#### From Frontmatter

```markdown theme={null}
{% line_chart
  data="demo.daily_orders"
  title="Revenue for {{ $company.name }}" <!-- [!code ++] -->
  x="date"
  y="sum(total_sales)"
/%}
```

Frontmatter variables also support direct assignment, useful for passing arrays and objects.

```markdown theme={null}
{% line_chart
  data="demo.daily_orders"
  title=$company.name <!-- [!code ++] -->
  x="date"
  y="sum(total_sales)"
/%}
```

#### From Inputs

```markdown theme={null}
{% line_chart
  data="demo.daily_orders"
  title="Sales for {{ category_dropdown }}" <!-- [!code ++] -->
  x="date"
  y="sum(total_sales)"
/%}
```

Note that not all attributes support input variables.

### In SQL

#### From Frontmatter

````markdown theme={null}
```sql home_sales
select * from demo.daily_orders
where category = '{{ $category }}' -- [!code ++]
```
````

#### From Inputs

Use variables in SQL queries for dynamic filtering:

````markdown theme={null}
```sql home_sales
select * from demo.daily_orders
where category = {{ category_dropdown }} -- [!code ++]
```
````

## Advanced Usage

### Fallback Values

Add fallback values using pipes `|`:

````markdown theme={null}
```sql category_analysis
select * from demo.daily_orders
where category = {{ category_dropdown | 'Electronics' }} -- [!code ++]
```
````

### Conditional Blocks

Conditional blocks `[[...]]` will only be included if **all** variables within it resolve to non-empty values:

````markdown theme={null}
```sql category_analysis
select * from demo.order_details
where transaction_amount > 500
[[ and category = {{ category_dropdown }} ]] -- [!code ++]
```
````

### Context-Aware Defaults

Input component variables automatically use context-aware defaults, so you can reference them directly without specifying a property:

* **In SQL contexts** (SQL queries, `where` clauses): Uses `.selected` (includes quotes)
* **In text contexts** (titles, markdown text): Uses `.literal` (excludes quotes)

````markdown theme={null}
```sql category_analysis
select * from demo.daily_orders
where category = {{ category_dropdown }} -- [!code ++]
```
````

```markdown theme={null}
{% line_chart
  data="category_analysis"
  title="Sales for {{ category_dropdown }}" <!-- [!code ++] -->
/%}
```

### Explicit Property Reference

You can explicitly specify which property to use. Each filter component offers different properties. For example, the [dropdown component](/components/dropdown) offers `.selected`, `.literal`, and `.filter` properties:

````markdown theme={null}
```sql category_analysis
select * from demo.daily_orders
where category = {{ category_dropdown.selected }} -- [!code ++]
```
````

### Nested Access

Use dot notation to access nested properties in frontmatter variables, and square brackets to access array indices:

```markdown theme={null}
{{ $company.name }} # Acme
{{ $targets.revenue }} # 1000000
{{ $colors[0] }} # red
```

### Data Types

Variables can be:

* **Strings**: `name: John Doe`
* **Numbers**: `age: 30`
* **Booleans**: `active: true`
* **Arrays**: `colors: [red, green, blue]`
* **Objects**: `company: { name: Acme, industry: Manufacturing }`