Getting Started
About Stencil
Transitioning to Stencil
Installing Stencil
Authentication & Tokens
Running Stencil Locally
Advanced Installation Options
Template Files
Templates Directory
Custom Templates
Customize Stencil Checkout
Handlebars and Stencil
Handlebars Helpers
Stencil Object Model
Stencil Objects

Handlebars.js Overview


Handlebars is a minimal templating language that allows you to create dynamic and robust templates for any BigCommerce storefront. A Handlebars template looks just like a regular HTML page, with the addition of Handlebars expressions for all dynamic logic that you embed into the page.

A Handlebars expression begins with: {{ and ends with: }}.

Here is a basic example that accesses the title and body variables:

<div class="entry">
<div class="entry">
  <h1>{{ title }}</h1>
  <div class="body">
    {{ body }}

In production, Handlebars statements run on the server side, generating HTML received by the shopper’s browser.

You can view a full reference page of all the handlebars helpers available to Stencil here, or explore them using navigation on the left hand side.

For a thorough overview of how to use Handlebars inside your templates, review the Handlebars documentation (Handlebars).

Template Logic

With Handlebars, it’s easy to embed logic right into your templates. Handlebars has built-in helpers for widely used logic and iterator functions. You can find a list of all built-in Handlebars helpers here.

Custom Handlebars Helpers

BigCommerce has extended the built-in Handlebars helpers with certain custom Handlebars helpers. For details, please proceed to the reference section.

Stencil Handlebars Resources

For a comprehensive reference to the Stencil data objects that you can manipulate via Handlebars statements, please see the Stencil Object Model Reference.

Rendering Special Characters

By default, Handlebars HTML-escapes values returned by a Handlebars {{ expression }}. So, where a Handlebars expression’s referenced content includes special characters, those characters will render literally on the storefront as HTML entities.

In the example above, assume that the HTML referenced by {{ title }} contains an ampersand and a “straight” apostrophe. You will see the entities & and ’ displayed literally on the storefront, instead of the intended characters & and '. Similar display errors will be triggered by apostrophes, quotation marks, primes, and other extended characters.

The workaround is to place the Handlebars variable in triple braces, like this: {{{ title }}}. Handlebars documentation refers to this technique as a “triple-stash.”