# Template Variables

## What is template variables?

Template variables allow you to connect multiple fields together by sharing the same value across different elements in your template.

**The Problem Without Variables:**

When the same value needs to appear in multiple places, you'd have to specify it repeatedly in your modifications:

```json
{
  "modifications": [
    {"id": "header_name", "text": "John Doe"},
    {"id": "body_name", "text": "John Doe"},
    {"id": "footer_name", "text": "John Doe"},
    {"id": "signature", "text": "John Doe"}
  ]
}
```

This creates several issues:

* Repetitive and error-prone
* Risk of inconsistency (typos, different values)
* Hard to maintain when values change
* Verbose API requests

**The Solution With Variables:**

Define the value once and reference it everywhere:

```json
{
  "modifications": [
    {"id": "header_name", "text": "{{user_name}}"},
    {"id": "body_name", "text": "{{user_name}}"},
    {"id": "footer_name", "text": "{{user_name}}"},
    {"id": "signature", "text": "{{user_name}}"}
  ],
  "variables": {
    "user_name": "John Doe"
  }
}
```

## Creating variables

Variables are defined in your template's configuration. Inside the template editor, you'll see a "Variables" button at the top bar.

<figure><img src="/files/yWyV4Xi7MZHOfVr9PXqm" alt=""><figcaption></figcaption></figure>

### Variable types

Variables support three types:

* `string`
* `number`
* `boolean` (False/True)

### Defining variables

You'll need to specify the variable name and they have to be unique. Each variable also requires default value.

<figure><img src="/files/UPJWnNdfoixXjZxfVJgc" alt=""><figcaption></figcaption></figure>

## Using variables

Currently, variables can only be used with the API. Soon, we are extending this to other integrations.

### With API

Apart from the `modifications` field, you can now specify `variables` field to define the value that should be assigned to the variable. If you don't specify it here, the default value will be used.

#### Example of using variables with image generation API

```json
{
  "template": "a2bdf44a-5fba-467d-a4d2-8685b1c4f8f5",
  "modifications": [
    {
      "name": "image_1",
      "src": "/images/image-placeholder.jpg",
      "visible": "{{visibility}}"
    },
    {
      "name": "text_2",
      "text": "Hello {{name}}!",
      "visible": "{{visibility}}"
    }
  ],
  "variables": {
    "visibility": false,
    "name": {
      "type": "string",
      "value": "John Doe"
    }
  }
}
```

The above example shows that we can control both layers' visibility by setting the variable `visibility` to `false`.&#x20;

Also, note that for variable `name`, we are declaring and defining variables right from the API without using the template editor. In this case, the `name` variable is only temporary for the current request.

Without variables, you'll need to set them individually.

Variables are useful for cases where you want to link some fields together. A common use case is to hide and show certain fields together.

## Variable Resolution

Variables are resolved in two places during generation:

1. **Template Resolution**: Variables in the template  itself are replaced with provided values
2. **Modification Resolution**: Variables in the modifications array are replaced with provided values

### Resolution Order

1. Use value from request's `variables` object if provided
2. Fall back to template's default value if defined
3. Return error if variable is required but not provided and has no default

### Type Validation

The system validates that provided values match the declared variable type:

* Text variables must receive string values
* Number variables must receive numeric values (integers or floats)
* Boolean variables must receive boolean values (true/false)

Type mismatches will result in an error.

You can look at the Console of each template to see the expected type for each field.

<figure><img src="/files/hbBHmm7zJ17RfVOqccER" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
`number` variable type refers to either `integer` and `float` in the console page. `array` type is not supported for variables.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.usestencil.com/using-stencil/template-variables.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.