Skip to navigation Skip to main content
Eleventy
Eleventy Documentation
Blog
Help Eleventy: Fill out Survey Awesome!
Versions
Stable
3.0.0
Toggle Menu
Compare ×4000 file build
Eleventy 1.93s
Gatsby 29.05s

Handlebars

Template Languages:
Contents

Eleventy Short Name File Extension npm Package
hbs .hbs handlebars.js

You can override a .hbs file’s template engine. Read more at Changing a Template’s Rendering Engine.

Installation

The haml templating language was moved out of Eleventy core in v3 and now requires a plugin installation.

npm install @11ty/eleventy-plugin-handlebars

Add to your configuration file (ESM version shown):

eleventy.config.js
import handlebarsPlugin from "@11ty/eleventy-plugin-handlebars";

export default function (eleventyConfig) {
	eleventyConfig.addPlugin(handlebarsPlugin);
}
const handlebarsPlugin = require("@11ty/eleventy-plugin-handlebars");

module.exports = function (eleventyConfig) {
	eleventyConfig.addPlugin(handlebarsPlugin);
}

Use more options:

eleventy.config.js
import handlebars from "handlebars";
import handlebarsPlugin from "@11ty/eleventy-plugin-handlebars";

export default function (eleventyConfig) {
	eleventyConfig.addPlugin(handlebarsPlugin, {
		// Override the `ejs` library instance
		eleventyLibraryOverride: handlebars,
	});
}
const handlebars = require("handlebars");
const handlebarsPlugin = require("@11ty/eleventy-plugin-handlebars");

module.exports = function (eleventyConfig) {
	eleventyConfig.addPlugin(handlebarsPlugin, {
		// Override the `ejs` library instance
		eleventyLibraryOverride: handlebars,
	});
}

Supported Features

Feature Syntax
✅ Partials {{> user}} looks for _includes/user.hbs. Does not process front matter in the include file.
🚫 Partials (Relative Path) Not yet supported: {{> ./user}} looks for user.hbs in the template’s current directory.
✅ Helpers (Custom Tags) {{ helperName myObject }} Handlebars calls them Helpers, but Eleventy calls them Shortcodes. Read more about Shortcodes or Custom Tags.
✅ Filters {{ filterName myObject }} Read more about Filters.
✅ Shortcodes {{{ uppercase name }}} Read more about Shortcodes.

Helpers

Helpers are used to transform or modify content.

Both Eleventy Universal Filters and Universal shortcodes are exposed as Helpers in Handlebars templates.

Read more about Handlebars Helpers syntax

Filters

WARNING:
Asynchronous filters are not supported by Handlebars. Read more at this Handlebars issue.

A note about Universal Filters

Universal filters have always been funneled into Handlebars helpers. However, shortcodes (Paired/Single) match better with the semantic footprint of Handlebars Helpers.

Moving forward for Handlebars content, using Universal Shortcodes are preferred to Universal Filters. We will continue to support funneling Universal filters to Handlebars helpers. This will not affect your template content as the syntax for Handlebars filters/helpers/shortcodes will continue to be the same. They’re all just helpers.

Shortcodes

Shortcodes are basically reusable bits of content. Handlebars makes use of existing synchronous Universal shortcodes.

WARNING:
Asynchronous shortcodes are not supported by Handlebars. Read more at this Handlebars issue.
eleventy.config.js
export default function(eleventyConfig) {
  eleventyConfig.addShortcode("user", function(name, twitterUsername) {
    return `<div class="user">
<div class="user_name">${name}</div>
<div class="user_twitter">@${twitterUsername}</div>
</div>`;
  });
};
module.exports = function(eleventyConfig) {
  eleventyConfig.addShortcode("user", function(name, twitterUsername) {
    return `<div class="user">
<div class="user_name">${name}</div>
<div class="user_twitter">@${twitterUsername}</div>
</div>`;
  });
};

Usage

{{{ user "Zach Leatherman" "zachleat" }}}
INFO:
Note that if you return HTML in your Handlebars shortcode, you need to use the Handlebars triple-stash syntax (three opening and three closing curly brackets) to avoid double-escaped HTML.
Outputs
<div class="user">
	<div class="user_name">Zach Leatherman</div>
	<div class="user_twitter">@zachleat</div>
</div>

Paired Shortcode

WARNING:
Asynchronous shortcodes are not supported by Handlebars. Read more at this Handlebars issue.
eleventy.config.js
export default function(eleventyConfig) {
  eleventyConfig.addPairedShortcode("user", function(bioContent, name, twitterUsername) {
    return `<div class="user">
<div class="user_name">${name}</div>
<div class="user_twitter">@${twitterUsername}</div>
<div class="user_bio">${bioContent}</div>
</div>`;
  });
};
module.exports = function(eleventyConfig) {
  eleventyConfig.addPairedShortcode("user", function(bioContent, name, twitterUsername) {
    return `<div class="user">
<div class="user_name">${name}</div>
<div class="user_twitter">@${twitterUsername}</div>
<div class="user_bio">${bioContent}</div>
</div>`;
  });
};

Usage

Note that you can put any Handlebars tags or content inside the {{ user }} shortcode! Yes, even other shortcodes!

{{# user "Zach Leatherman" "zachleat" }}Zach likes to take long walks on Nebraska beaches.{{/ user }}
INFO:
While unpaired shortcodes and helpers required that you use the Handlebars triple-stash syntax (three opening and three closing curly brackets) to avoid double-escaped HTML, paired Handlebars shortcodes do not have this requirement.
Outputs
<div class="user">
	<div class="user_name">Zach Leatherman</div>
	<div class="user_twitter">@zachleat</div>
	<div class="user_bio">Zach likes to take long walks on Nebraska beaches.</div>
</div>

Other pages in Template Languages: