---
title: "Quick start"
manual: "Handlebars"
version: "main"
permalink: "https://docs.typo3.org/permalink/cpsit/typo3-handlebars:quick-start@main"
source: "Usage/QuickStart.rst"
rendered: "2026-09-29T09:05:57+00:00"
---

# Quick start {#quick-start}

This page walks through a minimal working example: rendering the `header`
CType with a Handlebars template.

1.  Include the site set

    Add the `cpsit/handlebars` site set to your site configuration
    (see [Site sets](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:site-sets@main)):

    **config/sites/\<my-site>/config.yaml**

    ```yaml
    dependencies:
      - cpsit/handlebars
    ```
1.  Configure template paths

    Declare where your `.hbs` files are located using the site settings
    provided by the site set:

    **config/sites/\<my-site>/settings.yaml**

    ```yaml
    handlebars.view.templateRootPath: 'EXT:my_sitepackage/Resources/Private/Templates/Handlebars'
    handlebars.view.partialRootPath: 'EXT:my_sitepackage/Resources/Private/Partials/Handlebars'
    ```

    > [!NOTE]
    > **See also**
    >
    > [Template paths](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:template-paths@main) — all configuration methods and their priority order.
1.  Create a Handlebars template

    Create the template file at the path declared above. The filename without
    the `.hbs` extension is used as the `templateName`:

    **EXT:my_sitepackage/Resources/Private/Templates/Handlebars/Header.hbs**

    ```handlebars
    <div class="ce-header">
        {{#if header}}
            <h1 class="ce-header__title">{{header}}</h1>
        {{/if}}
        {{#if subheader}}
            <p class="ce-header__subtitle">{{subheader}}</p>
        {{/if}}
    </div>
    ```
1.  Configure the content element

    Point the `header` CType at the template using a `HANDLEBARSTEMPLATE` content object:

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

        variables {
            header = TEXT
            header.field = header

            subheader = TEXT
            subheader.field = subheader
        }
    }
    ```

    Each entry in `variables` is processed as a TYPO3 content
    object against the current content element record. The resulting values
    are passed to the template alongside the automatically injected
    `data` and `current` variables.
1.  Flush caches

    After editing TypoScript, flush the TYPO3 page cache. After editing
    `Services.yaml`, flush and rebuild the service container as well.

## Next steps {#quick-start-next-steps}

-   [HANDLEBARSTEMPLATE content object](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:content-object@main) — complete reference for all
    `HANDLEBARSTEMPLATE` properties
-   [Writing templates](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:templates@main) — template names, partials, layouts and built-in helpers
-   [Data processors](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:data-processors@main) — enrich templates with database queries, menus,
    and custom variable processing
-   [Custom helpers](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:custom-helpers@main) — expose custom PHP logic to templates