> For the complete documentation index, see [llms.txt](https://docs.usestencil.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.usestencil.com/using-stencil/template-variables.md).

# 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 %}