Handlebars.js: Minimal Templating on Steroids

Handlebars expressions are the basic unit of a Handlebars template. You can use them alone in a {{mustache}}, pass them to a Handlebars helper, or use them as values in hash arguments.

Basic Usage

The simplest Handlebars expression is a simple identifier:

<h1>{{title}}</h1>

This expression means "look up the title property in the current context". Block helpers may manipulate the current context, but they do not change the basic meaning of an expression.

Actually, it means "look for a helper named title, then do the above", but we'll get to that soon enough.

Handlebars expressions can also be dot-separated paths.

<h1>{{article.title}}</h1>

This expression means "look up the article property in the current context. Then look up the title property in the result".

Handlebars also supports a deprecated / syntax, so you could write the above template as:

<h1>{{article/title}}</h1>

To reference a property that is not a valid identifier, you can use segment-literal notation:

{{#each articles.[10].[#comments]}}
  <h1>{{subject}}</h1>
  <div>
    {{body}}
  </div>
{{/each}}

You may not include a closing ] in a path-literal, but all other characters are fair game.

Helpers

A Handlebars helper call is a simple identifier, followed by zero or more parameters (separated by space). Each parameter is a Handlebars expression.

{{{link story}}}

In this case, link is the name of a Handlebars helper, and story is a parameter to the helper. Handlebars evaluates parameters in exactly the same way described above in "Basic Usage".

Handlebars.registerHelper('link', function(object) {
  return new Handlebars.SafeString(
    "<a href='" + object.url + "'>" + object.text + "</a>"
  );
});

When returning HTML from a helper, you should return a Handlebars SafeString if you don't want it to be escaped by default.

You can also pass a simple String as a parameter to Handlebars helpers.

{{{link "See more..." story.url}}}

In this case, Handlebars will pass the link helper two parameters: the String "See more..." and the result of evaluating story.url in the current context.

Handlebars.registerHelper('link', function(text, url) {
  return new Handlebars.SafeString(
    "<a href='" + url + "'>" + text + "</a>"
  );
});

You could use the exact same helper with dynamic text based on the value of story.text:

{{{link story.text story.url}}}

Handlebars helpers can also receive an optional sequence of key-value pairs as their final parameter (referred to as hash arguments in the documentation):

{{{link "See more..." href=story.url class="story"}}}

The keys in hash arguments must each be simple identifiers, and the values are Handlebars expressions. This means that values can be simple identifiers, paths, or Strings.

Handlebars.registerHelper('link', function(text, options) {
  var attrs = [];

  for(var prop in options.hash) {
    attrs.push(prop + '="' + options.hash[prop] + '"');
  }

  return new Handlebars.SafeString(
    "<a " + attrs.join(" ") + ">" + text + "</a>"
  );
});

Handlebars provides additional metadata, such as Hash arguments, to helpers as a final parameter.

Handlebars also offers a mechanism for invoking a helper with a block of the template. Block helpers can then invoke that block zero or more times with any context it chooses.

Learn More: Block Helpers