Handlebars Basics

Handlebars is a general-purpose templating language (used well beyond BigCommerce) built around a small set of constructs: output, a handful of built-in block helpers, and partials for reuse. It's deliberately less feature-rich than something like Liquid — logic largely lives in JavaScript, and templates stay focused on layout.

Output

<h1>{{product.title}}</h1>
<p>{{product.price.formatted.without_tax}}</p>

Double braces automatically HTML-escape the output — necessary for safety when displaying user-generated content. To output raw, unescaped HTML deliberately, use triple braces instead:

{{{product.description}}}

Block helpers: #if and #each

{{#if product.out_of_stock}}
  <span class="badge">Sold out</span>
{{else}}
  <span class="badge">In stock</span>
{{/if}}

<ul>
{{#each category.products}}
  <li>{{this.title}} — {{this.price.formatted.without_tax}}</li>
{{/each}}
</ul>

Inside #each, this refers to the current item, and Handlebars also exposes @index, @first, and @last — direct equivalents to Liquid's forloop properties.

#unless and #with

#unless is the inverse of #if, and #with changes the context inside a block to a specific nested object — useful for avoiding repetitive dotted paths:

{{#unless product.instock}}
  <p>Currently unavailable</p>
{{/unless}}

{{#with product.price}}
  <p>{{formatted.without_tax}} (was {{formatted.rrp_without_tax}})</p>
{{/with}}

Partials

A partial is included with {{> name}}, and unlike a plain Handlebars include, you can pass it a specific context object as a second argument:

{{> components/products/product-card this}}

Comments

Handlebars comments use {{! ... }} or the block form {{!-- ... --}} (the block form is safer when the comment text itself might contain }}), and like Liquid's comments, they're stripped entirely and never reach the rendered page:

{{!-- TODO: swap for the new badge component --}}

Helpers Stencil adds

Stencil registers a set of custom Handlebars helpers beyond the language's built-ins — things like {{lang 'common.add_to_cart'}} for translation strings, {{getFontLoaderConfig}} for theme font settings, and comparison helpers like {{#if (eq a b)}} for logic Handlebars doesn't support natively. These aren't part of Handlebars itself; they're BigCommerce-specific additions available only inside a Stencil theme.