---
title: "Variables"
manual: "Handlebars"
version: "main"
permalink: "https://docs.typo3.org/permalink/cpsit/typo3-handlebars:variables@main"
source: "Configuration/Variables.rst"
rendered: "2026-09-29T09:05:57+00:00"
---

# Variables {#variables}

Template variables are available at two scopes: globally for every rendering,
and locally for a single content object rendering.

-   [Global variables](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:global-variables@main)
-   [Per-rendering variables](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:per-rendering-variables@main)

## Global variables {#variables-global}

Global variables are merged into every template rendering automatically.
They can be defined through TypoScript or the service container.

### Via TypoScript {#variables-global-typoscript}

Use `plugin.tx_handlebars.variables` to define variables available
on every page where the TypoScript is active. This is best suited for
**dynamic** variables that depend on the current request context, since the
underlying provider can only resolve them once a request is available (see
the tip below):

```typoscript
plugin.tx_handlebars {
    variables {
        pageTitle = TEXT
        pageTitle.data = page:title

        campaign = TEXT
        campaign.field = campaign
    }
}
```

### Via service container {#variables-global-service-container}

Variables can also be defined instance-wide through `Services.yaml`.
These apply regardless of TypoScript configuration:

**Configuration/Services.yaml**

```yaml
handlebars:
  variables:
    publicPath: /assets
    apiEndpoint: https://api.example.com
```

> [!NOTE]
> When the same key is defined in both sources, the TypoScript value takes
> precedence.

> [!TIP]
> Prefer the service container for **static** variables. The underlying
> `GlobalVariableProvider` is always cacheable, so its variables are
> resolved once and reused across renderings.
>
> `plugin.tx_handlebars.variables` is backed by
> `TypoScriptVariableProvider`, which cannot resolve variables until a
> request with a `ContentObjectRenderer` attached is available — this
> may not yet be the case during early bootstrapping. Because of this, it
> reports itself as non-cacheable until a request has been resolved, which
> disables caching of the merged variable set for that rendering. Reserve
> `plugin.tx_handlebars.variables` for **dynamic** variables
> that genuinely depend on the current request context, for example a
> `TEXT` content object reading a GET parameter or the current
> page record.

## Per-rendering variables {#variables-per-rendering}

Variables scoped to a single rendering are declared in the
`variables` property of a `HANDLEBARSTEMPLATE`
content object. Each entry is processed as a standard content object
against the current record's data:

```typoscript
tt_content.header = HANDLEBARSTEMPLATE
tt_content.header {
    templateName = Header

    variables {
        header = TEXT
        header.field = header

        subheader = TEXT
        subheader.field = subheader

        link = TEXT
        link.typolink.parameter.field = header_link
    }
}
```

Entries with no sub-configuration are treated as **simple variables** and
passed to the template as-is, without invoking `ContentObjectRenderer`:

```typoscript
variables {
    # Content object — field value is rendered via cObjGetSingle
    header = TEXT
    header.field = header

    # Simple variables — values are passed through directly
    cssClass = my-element
    theme = dark
}
```

Two variables are always injected automatically and cannot be overridden
(this reflects the same behavior as in `FLUIDTEMPLATE`):

-   **`data`**

    The full data array of the current content element record.

-   **`current`**

    The value of the current field (`$cObj->currentValKey`).

> [!WARNING]
> Declaring `data` or `current` in
> `variables` is not allowed and raises an exception.

> [!NOTE]
> **See also**
>
> [HANDLEBARSTEMPLATE content object](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:content-object@main) for the complete `HANDLEBARSTEMPLATE`
> property reference, including `settings` and
> `dataProcessing`.