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

# Template paths {#template-paths}

Template and partial root paths are collected from various sources, each
with a distinct priority. Higher-priority sources win over lower-priority ones.
Within a single source, higher numeric keys override lower ones.

-   [Priority order](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:priority-order@main)
-   [Template name resolution](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:template-name-resolution@main)

## Priority order {#template-paths-priority}

| Source | Priority |
| --- | --- |
| Per-content-object TypoScript | 100 |
| `plugin.tx_handlebars.view` | 50 |
| Service container (e.g. `Services.yaml`) | 0 |

### Per-content-object (priority 100) {#template-paths-per-content-object}

Template and partial root paths can be set directly inside a
`HANDLEBARSTEMPLATE` content object. These paths apply only to
that specific rendering, including any nested partial lookups triggered by it.

```typoscript
tt_content.textmedia = HANDLEBARSTEMPLATE
tt_content.textmedia {
    templateRootPaths {
        10 = EXT:my_extension/Resources/Private/Templates
    }
    partialRootPaths {
        10 = EXT:my_extension/Resources/Private/Partials
    }
}
```

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

### TypoScript (priority 50) {#template-paths-typoscript}

Global paths for all renderings on the current page can be configured
under `plugin.tx_handlebars.view`:

```typoscript
plugin.tx_handlebars {
    view {
        templateRootPaths {
            10 = EXT:my_extension/Resources/Private/Templates
        }
        partialRootPaths {
            10 = EXT:my_extension/Resources/Private/Partials
        }
    }
}
```

The `cpsit/handlebars` site set also populates these paths
from the site settings `{$handlebars.view.templateRootPath}` and
`{$handlebars.view.partialRootPath}`.

> [!NOTE]
> When multiple extensions declare paths under the same numeric key, the last
> one loaded wins. Use distinct keys (e.g., 10, 20, 30) to ensure all paths
> are registered.

### Service container (priority 0) {#template-paths-service-container}

The lowest-priority source is the service container. Paths registered here
apply instance-wide, regardless of the current page or content object, and
serve as the global fallback.

**Configuration/Services.yaml**

```yaml
handlebars:
  view:
    templateRootPaths:
      10: EXT:my_extension/Resources/Private/Templates
    partialRootPaths:
      10: EXT:my_extension/Resources/Private/Partials
```

## Template name resolution {#template-paths-resolution}

Once the root paths are collected, template and partial names are resolved
against them. Next to directory-relative names, flat `@`-prefixed names
are supported, see [Referencing templates and partials](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:templates-names@main).