Handlebars Helpers Reference
On this page
This article is a reference for Stencil supported Handlebars helpers. It includes custom helpers documentation and a list of whitelisted standard helpers.
Custom helpers
The following table contains BigCommerce’s open source Handlebars helpers.
Helper | Category | Description |
---|---|---|
limit | array | Limits array to second argument. |
pluck | array | Uses search key to get values from collections. |
cdn | assets | A URL transformer for content delivery networks. |
money | currency | Formats number length, thousands delimiter, and decimal delimiter. |
getFontLoaderConfig | fonts | Returns font-loader config as a JSON string. |
getFontsCollection | fonts | Returns <link> elements for configured fonts. |
encodeHtmlEntities | html | Encodes HTML entities. |
nl2br | html | Converts newline characters to <br> tags. |
pre | html | Renders preformatted text. |
resourceHints | html | Pre-fetches Google fonts. |
stylesheet | html | Renders a <link> tag for inserting a stylesheet. |
lang | i18n | Maps keys to translation files. |
langJson | i18n | Returns language translation keys as a JSON string. |
getContentImage | images | Returns sized image URL from store’s /content directory. |
getContentImageSrcset | images | Returns source set of URLs for images in /content . |
getImage | images | Returns image URL for specified size. |
getImageManagerImage | images | Returns sized image URL for images in /product_images/uploaded_images . |
getImageManagerImageSrcset | images | Returns image srcset for images in /product_images/uploaded_images . |
getImageSrcset | images | Returns single image URL or list of URLs for different sizes. |
any | logic | Renders block if any params are true. |
all | logic | Renders block if all params are true. |
compare | logic | Compares values with JavaScript operators, including typeof . |
contains | logic | Renders block if first param is in second param. |
for | logic | Iterates for range a to b . |
if | logic | Renders block if statement is true. |
or | logic | Renders block if one or more parameters evaluate to true. |
unless | logic | Renders block if a statement evaluates to false. |
concat | string | Concatenates two strings. |
join | string | Joins an array of string elements into one string. |
json | string | Converts a JavaScript object into a JSON string. |
occurrences | string | Returns the number of occurrences of substring within the given string. |
replace | string | Replaces all instances of the first parameter in the second parameter. |
setURLQueryParam | string | Appends keys values to a URL. |
stripQuerystring | string | Removes a query string. |
toLowerCase | string | Converts a string to lowercase. |
truncate | string | Truncates a string. |
block | template | Defines a content block. |
dynamicComponent | template | Inserts a dynamic partial in the specified path. |
inject | template | Injects key values into {{jsContext}} . |
jsContext | template | Returns JSON for all data injected by {{inject}} . |
partial | template | Overrides content defined by {{block}} . |
region | template | Specifies a widget region. |
assignVar | variables | Saves value to a variable. |
getVar | variables | Returns a variable value. |
decrementVar | variables | Decrements a variable by 1. |
incrementVar | variables | Increments a variable by 1. |
{{limit}}
{{limit data limit}}
Limits the number of items returned from an array; returns a new array.
Parameters
data
{Array}: Collection.limit
{Number}: Index specifying the number of items to exclude.
Example
Assume that {{cart.items}}
returns 10 items. You can use this helper to limit that behavior to only the first four items.
<!-- context = {var: 'This is longer than the chosen limit'} -->
{{limit var 10}}
<!-- => This is lo -->
<!-- context = {var: 'This is longer than the chosen limit'} -->
{{limit var 10}}
<!-- results in: 'This is lo' -->
{{#each (limit cart.items 4)}}
<li class="previewCartItem">
<div class="previewCartItem-image">
{{#if type '==' 'GiftCertificate'}}
<img src="{{cdn ../../theme_settings.default_image_gift_certificate}}" alt="GiftCertificate" title="GiftCertificate">
{{else}}
{{> components/common/responsive-img
image=image
fallback_size=../../theme_settings.productthumb_size
lazyload=../../theme_settings.lazyload_mode
default_image=../../theme_settings.default_image_product
}}
{{/if}}
...
{{pluck}}
{{pluck limit collection path}}
Retrieves corresponding values from some or all elements in a collection using specified search key(s). Returns retrieved values in a comma-separated string.
Parameters
limit
,limit-value
: Optional parameters to limit the number of results returned.collection
{Object|Array}: Collection.path
{String}: The string to search for.
Examples
{{pluck ([limit] <collection> [<limit-value>]) '<path>'}}
If each category in categories
contains an image object, use dot notation to access the image’s children:
categories: [
{ "id": 1, "name": "Bakeware", "image": { "data": "http://...", "alt": "Bakeware image"} },
{ "id": 2, "name": "Cookware", "image": { "data": "http://...", "alt": "Cookware image"} },
{ "id": 3, "name": "Cutlery", "image": { "data": "http://...", "alt": "Cutlery image"} }
]
{{pluck (limit categories 2) 'image.data'}}
<!-- Returns a comma-separated list of image URLs. -->
users: [
{ "user": "barney", "age": 36, "image": { "url": "barney.jpg" } },
{ "user": "fred", "age": 40, "image": { "url": "fred.jpg" } }
]
{{pluck users "age"}}
<!-- => 36,40 -->
{{pluck users "image.url"}}'
<!-- => barney.jpg,fred.jpg -->
{{cdn}}
{{cdn assetPath}}
A URL transformer for content delivery networks.
Parameters
assetPath
{String}: Path to the file containing static assets.
Example
{{cdn "assets/img/image.jpg"}}
<!-- => https://cdn.bcapp/3dsf74g/stencil/123/img/image.jpg -->
To reference static assets staged locally outside your <theme-name>
directory and uploaded using WebDAV, place the webdav:
prefix before each corresponding assetPath
parameter. For example, the following link:
<img src="{{cdn 'webdav:img/image.jpg'}}">
will be transformed to a result like this:
<img src="https://cdn.bcapp/3dsf74g/content/img/image.jpg">
In this example, the image.jpg
file was uploaded to the WebDAV /content/
directory making /content
the WebDAV root directory. Because our presumed local directory is assets/
, we can omit that path when referencing its contained files or subdirectories.
CDN custom endpoints
You can define custom CDN endpoints to use with the {{cdn}}
helper. This way you can include large, high-resolution image assets in themes without exceeding BigCommerce’s 50 MB limit when bundling the theme for upload to BigCommerce.
You could use a local version of the image in development and a version on a CDN such as Imgix in production. To do so, define custom CDN endpoints in your theme’s config.json
file.
For example:
{
"name": "Cornerstone",
"version": "1.3.5",
"settings": {
"homepage_new_products_count": 12,
"homepage_featured_products_count": 8,
"cdn": {
"customcdn": "https://bigcommerce.customcdn.net"
}
}
}
After defining the endpoint, you can use the short name in the same way as you would use a webdav:
protocol:
<img src="{{cdn 'customcdn:img/image.jpg'}}" />
In local development, that helper would return:
<img src="/assets/cdn/customcdn/img/image.jpg"/>
Whereas in production, it would return:
<img src="https://bigcommerce.customcdn.net/img/image.jpg" />
As highlighted above, the helper is configured to rewrite local URLs to an assets/cdn/
subfolder. The stencil bundle
command will exclude this local assets/cdn/
subfolder from the bundle that it creates. This filtering circumvents the 50 MB size limit on the resulting ZIP file.
{{money}}
{{money value n s c}}
Formats number length, thousands delimiter, and decimal delimiter.
Parameters
value
{Number}: The number to format.n
{Integer}: Length of decimal.s
{Mixed}: Thousands delimiter.c
{Mixed}: Decimal delimiter.
Example
{{money 1000 2 ',' '.'}}
{{getFontLoaderConfig}}
{{getFontLoaderConfig fontConfig}}
Returns font-loader config as a JSON string.
Parameters
fontConfig
{String}: Font config in theGoogle_FontName_Weight
format.
Example
{{getFontLoaderConfig 'Google_Karla_700'}}
<!-- => Karla:700 -->
{{getFontsCollection}}
{{getFontsCollection}}
Returns <link>
elements for configured fonts.
Example
{{getFontsCollection}}
<!-- => <link href="https://fonts.googleapis.com/css?family=Open+Sans:,400italic,700|Karla:700|Lora:400|Volkron:|Droid:400,700|Crimson+Text:400,700&display=swap" rel="stylesheet"> -->
{{encodeHtmlEntities}}
{{encodeHtmlEntities string args}}
Returns a string with HTML entities encoded. You may optionally pass additional encoding arguments.
Parameters
string
{String}: String to encode with HTML entities.args
{Boolean}: Whitelist of allowed named arguments. Allowed arguments:useNamedReferences
,decimal
,encodeEverything
,allowUnsafeSymbols
. Specifyarg='true'
to use. For example,decimal='true'
.
Examples
{{encodeHtmlEntities 'foo © bar ≠ baz 𝌆 qux'}}
<!-- => foo © bar ≠ baz 𝌆 qux -->
{{encodeHtmlEntities 'an ampersand: &'}}
<!-- => an ampersand: & -->
{{encodeHtmlEntities "foo © bar ≠ baz 𝌆 qux" useNamedReferences="true"}}
<!-- Returns a string with HTML entities encoded with named references. -->
<!-- => foo © bar ≠ baz 𝌆 qux -->
{{encodeHtmlEntities "foo © bar ≠ baz 𝌆 qux" decimal="true"}}
<!-- Returns a string with HTML entities encoded with decimal option. -->
<!-- => foo © bar ≠ baz 𝌆 qux -->
{{encodeHtmlEntities "foo © bar ≠ baz 𝌆 qux" encodeEverything="true"}}
<!-- Returns a string with HTML entities encoded with encodeEverything option. -->
<!-- => foo © bar ≠ baz 𝌆 qux -->
{{encodeHtmlEntities "foo © and & ampersand" allowUnsafeSymbols="true"}}
<!-- Returns a string with HTML entities encoded with allowUnsafeSymbols option. -->
<!-- => foo © and & ampersand -->
{{nl2br}}
{{nl2br text}}
Converts newline characters to <br>
tags.
Parameters
text
{String}: Text to convert.
Example
{{nl2br settings.address}}
<!-- => <br>685 Market St<br>San Francisco<br>94105<br>CA<br> -->
{{pre}}
{{pre value}}
Renders preformatted text. This helper will escape text.
Parameters
value
{String}: Text to format.
Example
<!-- context = {var: {}} -->
{{pre var}}
<!-- => <pre>{}</pre> -->
<!-- context = {var: "<div>&\"500\"</div>"} -->
{{pre var}}
<!-- => <pre>"<div>&\\"500\\"</div>"</pre> -->
{{resourceHints}}
{{resourceHints}}
Pre-fetches Google fonts. Outputs a formatted <link>
tag for DNS-prefetch.
Example
{{resourceHints}}
<!-- => <link rel="dns-prefetch preconnect" href="https://fonts.googleapis.com" crossorigin><link rel="dns-prefetch preconnect" href="https://fonts.gstatic.com" crossorigin> -->
{{stylesheet}}
{{stylesheet assetPath}}
Renders a link tag to insert a stylesheet into a theme; returns an HTML string. (This is required if you want Theme Editor to rewrite the stylesheet file when a merchant customizes their theme.)
Parameters
assetPath
(String}): Filepath to the theme’s CSS stylesheet file.options
: You can append optional parameters as key/value pairs.
Example
{{stylesheet "assets/css/style.css" class="myStylesheet"}}
{{lang}}
{{lang translationKey}}
Maps keys to translation files based on the locale indicated by the visitor’s browser.
Parameters
translationKey
{String}options
: You can append optional parameters as key/value pairs.
Examples
<label class="form-label" for="search_query_adv">
{{lang 'forms.search.query' }}
<small>{{lang 'common.required' }}</small>
</label>
<!-- context = {name: 'BigCommerce'} -->
{{lang 'powered_by' name=name}}
<!-- => Powered By BigCommerce -->
{{langJson}}
{{langJson keyFilter}}
Returns language translation keys as a JSON string.
Parameters
keyFilter
{String}: The language translation keys to render for the storefront locale/language.
Example
{{langJson 'validation_messages'}}
<!-- This will load validation messages in JSON format for the storefront locale/language. -->
{{getContentImage}}
{{getContentImage path width height}}
Returns a URL for an image uploaded to /dav/content/
. To learn more about uploading files to your store’s server, see WebDAV.
Parameters
path
{String}: Image path relative to/dav/content/
.width
{Integer}: Width in pixels.height
{Integer}: Height in pixels.
Example
<!-- Original image URL returned if no size or invalid size is passed in -->
{{getContentImage "asset.jpg"}}
<!-- => https://cdn.bcapp/3dsf74g/images/stencil/original/content/asset.jpg -->
{{getContentImage "asset.jpg" width="a" height="a"}}
<!-- => https://cdn.bcapp/3dsf74g/images/stencil/original/content/asset.jpg -->
<!-- Sized image URL returned if valid height and/or width passed in -->
{{getContentImage "asset.jpg" width=123 height=321}}
<!-- => https://cdn.bcapp/3dsf74g/images/stencil/123x321/content/asset.jpg -->
{{getContentImage "asset.jpg" width=123}}
<!-- => https://cdn.bcapp/3dsf74g/images/stencil/123w/content/folder/asset.jpg -->
{{getContentImageSrcset}}
{{getContentImageSrcset path}}
Returns a srcset
for an image uploaded to /dav/content/
.
Parameters
path
{String}: Image path relative to/dav/content/
.
Example
{{getContentImageSrcset "asset.jpg"}}
<!-- => https://cdn.bcapp/3dsf74g/images/stencil/80w/content/asset.jpg 80w, https://cdn.bcapp/3dsf74g/images/stencil/160w/content/asset.jpg 160w, https://cdn.bcapp/3dsf74g/images/stencil/320w/content/asset.jpg 320w, https://cdn.bcapp/3dsf74g/images/stencil/640w/content/asset.jpg 640w, https://cdn.bcapp/3dsf74g/images/stencil/960w/content/asset.jpg 960w, https://cdn.bcapp/3dsf74g/images/stencil/1280w/content/asset.jpg 1280w, https://cdn.bcapp/3dsf74g/images/stencil/1920w/content/asset.jpg 1920w, https://cdn.bcapp/3dsf74g/images/stencil/2560w/content/asset.jpg 2560w -->
{{getContentImageSrcset "folder/asset.jpg" width=123}}
<!-- => https://cdn.bcapp/3dsf74g/images/stencil/80w/content/folder/asset.jpg 80w, https://cdn.bcapp/3dsf74g/images/stencil/160w/content/folder/asset.jpg 160w, https://cdn.bcapp/3dsf74g/images/stencil/320w/content/folder/asset.jpg 320w, https://cdn.bcapp/3dsf74g/images/stencil/640w/content/folder/asset.jpg 640w, https://cdn.bcapp/3dsf74g/images/stencil/960w/content/folder/asset.jpg 960w, https://cdn.bcapp/3dsf74g/images/stencil/1280w/content/folder/asset.jpg 1280w, https://cdn.bcapp/3dsf74g/images/stencil/1920w/content/folder/asset.jpg 1920w, https://cdn.bcapp/3dsf74g/images/stencil/2560w/content/folder/asset.jpg 2560w -->
{{getImage}}
{{getImage stencilImage size}}
Returns <img>
tag src
value for images of a specified size. Values for the size parameter are defined in the settings
array in config.json
.
Parameters
stencilImage
{String}: A Stencil image.size
{String}: A key in thetheme_settings
object.defaultImage
{String}: Optional default image URL to use if thestencilImage
is undefined.
Example
{{getImage image "logo"}}
{{getImageManagerImage}}
{{getImageManagerImage path width height}}
Returns an Image Manager image URL for an image uploaded to /dav/product_images/uploaded_images
. To learn more about uploading files to your store’s server, see WebDAV.
Parameters
path
{String}: Image path relative to/dav/product_images/uploaded_images
.width
{Integer}: Width in pixels.height
{Integer}: Height in pixels.
Example
<!-- Original image URL returned if no size or invalid size is passed in -->
{{getImageManagerImage "asset.jpg"}}
<!-- => https://cdn.bcapp/3dsf74g/images/stencil/original/image-manager/asset.jpg -->
<!-- height must be accompanied by width -->
{{getImageManagerImage "folder/asset.jpg" height=123}}
<!-- => https://cdn.bcapp/3dsf74g/images/stencil/original/image-manager/folder/asset.jpg -->
<!-- Sized image URL returned if valid height and/or width passed in -->
{{getImageManagerImage "asset.jpg" width=123}}
<!-- => https://cdn.bcapp/3dsf74g/images/stencil/123w/image-manager/asset.jpg -->
{{getImageManagerImage "folder/asset.jpg" width=123 height=321}}
<!-- => https://cdn.bcapp/3dsf74g/images/stencil/123x321/image-manager/folder/asset.jpg -->
{{getImageManagerImageSrcset}}
{{getImageManagerImageSrcset path}}
Returns an Image Manager image srcset
for an image uploaded to /dav/product_images/uploaded_images
.
Parameters
path
{String}: Image path relative to/dav/product_images/uploaded_images
.
Example
{{getImageManagerImageSrcset "asset.jpg"}}
<!-- =>
https://cdn.bcapp/3dsf74g/images/stencil/80w/image-manager/asset.jpg 80w, https://cdn.bcapp/3dsf74g/images/stencil/160w/image-manager/asset.jpg 160w, https://cdn.bcapp/3dsf74g/images/stencil/320w/image-manager/asset.jpg 320w, https://cdn.bcapp/3dsf74g/images/stencil/640w/image-manager/asset.jpg 640w, https://cdn.bcapp/3dsf74g/images/stencil/960w/image-manager/asset.jpg 960w, https://cdn.bcapp/3dsf74g/images/stencil/1280w/image-manager/asset.jpg 1280w, https://cdn.bcapp/3dsf74g/images/stencil/1920w/image-manager/asset.jpg 1920w, https://cdn.bcapp/3dsf74g/images/stencil/2560w/image-manager/asset.jpg 2560w -->
{{getImageManagerImageSrcset "folder/asset.jpg" width=123}}
<!-- =>
https://cdn.bcapp/3dsf74g/images/stencil/80w/image-manager/folder/asset.jpg 80w, https://cdn.bcapp/3dsf74g/images/stencil/160w/image-manager/folder/asset.jpg 160w, https://cdn.bcapp/3dsf74g/images/stencil/320w/image-manager/folder/asset.jpg 320w, https://cdn.bcapp/3dsf74g/images/stencil/640w/image-manager/folder/asset.jpg 640w, https://cdn.bcapp/3dsf74g/images/stencil/960w/image-manager/folder/asset.jpg 960w, https://cdn.bcapp/3dsf74g/images/stencil/1280w/image-manager/folder/asset.jpg 1280w, https://cdn.bcapp/3dsf74g/images/stencil/1920w/image-manager/folder/asset.jpg 1920w, https://cdn.bcapp/3dsf74g/images/stencil/2560w/image-manager/folder/asset.jpg 2560w -->
{{getImageSrcset}}
{{getImageSrcset stencilImage size}}
The getImageSrcset
helper is a replacement for getImage
which allows you to generate either a single image URL (for an <img>
src
) or a list of image sizes for srcset
. Using the srcset attribute, you can specify a list of image sizes for the browser to choose from based on the expected size of the image on the page, the device’s pixel density, and other factors.
Parameters
stencilImage
{String}: A Stencil image.size
{String}: A key in thetheme_settings
object.defaultImage
{String}: Optional default image URL to use if thestencilImage
is undefined.
You can specify what sizes you want as named arguments on the helper.
Example
Default sizes
By specifying use_default_sizes=true
on the helper, a srcset
string will be constructed with a set of sizes chosen by BigCommerce to be optimal for most uses.
{{getImageSrcset image use_default_sizes=true}}
{{getImageSrcset image "https://place-hold.it/500x300" use_default_sizes=true}}
Default sizes:
'80w': '80w',
'160w': '160w',
'320w': '320w',
'640w': '640w',
'960w': '960w',
'1280w': '1280w',
'1920w': '1920w',
'2560w': '2560w',
Single 1x size
{{getImageSrcset image 1x=theme_settings.zoom_size}}
{{getImageSrcset image 1x="1280x800"}}
{{getImageSrcset image 1x="1280w"}}
By specifying a single size as 1x
, you can choose any image resolution. You can reference a value from the theme_settings
object (similar to getImage
), or you can specify your own size inline. getImageSrcset
does not require theme_settings
keys to be wrapped in quotes; they should be referenced directly.
Pixel density
{{getImageSrcset image 1x="1280w" 2x="2560w"}}
{{getImageSrcset image 1x="800w" 1.5x="1200w" 2x="1600w"}}
{{getImageSrcset image 1x="640x640" 2x="1280x1280"}}
By specifying several sizes using the pixel density descriptor, you can generate a srcset
of different image resolutions for different pixel density screens as described in Resolution switching: Same size, different resolutions. For example, you can specify a 2x
image for Retina screens, and a 1x
image for normal screens.
As above, you can reference theme_settings
keys or specify your own size inline.
Inherent width
<img src="{{getImage image 'default'}}" srcset="{{getImageSrcset image 100w='100w' 200w='200w' 300w='300w'}}" />
<!-- =>
<img src="https://cdn11.bigcommerce.com/s-abc123/images/stencil/640x640/products/86/286/ablebrewingsystem4_1024x1024__07155.1456436672.jpg?c=2" srcset="https://cdn11.bigcommerce.com/s-abc123/images/stencil/100w/products/86/286/ablebrewingsystem4_1024x1024__07155.1456436672.jpg?c=2 100w, https://cdn11.bigcommerce.com/s-abc123/images/stencil/200w/products/86/286/ablebrewingsystem4_1024x1024__07155.1456436672.jpg?c=2 200w,https://cdn11.bigcommerce.com/s-abc123/images/stencil/300w/products/86/286/ablebrewingsystem4_1024x1024__07155.1456436672.jpg?c=2 300w" /> -->
<img src="{{getImageSrcSet image 1x='1000x1000'}}" srcset="{{getImageSrcset image 1x='1000x1000' 2x='2000x2000'}}" />
<!-- =>
<img src="https://cdn11.bigcommerce.com/s-abc123/images/stencil/640x640/products/86/286/ablebrewingsystem4_1024x1024__07155.1456436672.jpg?c=2" srcset="https://cdn11.bigcommerce.com/s-abc123/images/stencil/100w/products/86/286/ablebrewingsystem4_1024x1024__07155.1456436672.jpg?c=2 100w, https://cdn11.bigcommerce.com/s-abc123/images/stencil/200w/products/86/286/ablebrewingsystem4_1024x1024__07155.1456436672.jpg?c=2 200w,https://cdn11.bigcommerce.com/s-abc123/images/stencil/300w/products/86/286/ablebrewingsystem4_1024x1024__07155.1456436672.jpg?c=2 300w" /> -->
By specifying several sizes using the inherent width descriptor, you can generate a srcset
of different image resolutions based on width, which can in turn be selected by the browser based on the expected size of the image when the page is painted. It is recommended to use this together with a sizes
attribute on the <img>
element as described in Resolution switching: Different sizes. In Cornerstone, this is handled automatically via JavaScript.
As above, you can reference theme_settings
keys or specify your own size inline.
{{any}}
{{any arg}}
Renders block if one or more parameters are true.
Parameters
arg
{String|Number|Array|Object}
Example
{{#any items selected=true}}
<!-- block to display if any items have selected=true -->
{{/any}}
A usage example is templates/components/category/shop-by-price.html
, a category page in Stencil’s Cornerstone base theme that does not have faceted search turned on. Shoppers will see Shop by price filters instead of product filters.
In this component, the {{any}}
helper is used to determine whether a shopper has selected one of the filters, and whether a “reset” button needs to be displayed:
{{#any shop_by_price selected=true}}
<li class="navList-item">
<a href="{{category_url}}" class="navList-action">
{{lang 'category.reset'}}
</a>
</li>
{{/any}}
{{all}}
{{all arg}}
Renders block if all parameters are true.
Parameters
arg
{String|Number|Array|Object}
Example
{{#all items theme_settings.optionA theme_settings.optionB}}
<!-- block to display if all items evaluate to true -->
{{/all}}
{{#all product.custom_fields theme_settings.show_custom_fields_tabs}}
<li class="tab">
<a class="tab-title" href="#tab-{{dashcase (lowercase (sanitize theme_settings.pdp-custom-fields-tab-label))}}">{{sanitize theme_settings.pdp-custom-fields-tab-label}}</a>
</li>
{{/all}}
{{compare}}
{{compare a operator b}}
Compares values with JavaScript operators. Renders block if comparison of the first and third parameters returns true.
Parameters
-
a
{} -
operator
{}: The operator to use. Operators must be enclosed in quotes: “>”, “=”, “<=”, and so on.==
===
!=
!===
<
>
<=
>=
typeof
-
b
{} -
options
{Object}: Options object. -
returns
{String}: Block, or if specified the inverse block is rendered if falsy.
{{contains}}
{{contains collection value}}
Renders block if collection
has the given value
, using strict equality (===
) for comparison, otherwise the inverse block is rendered (if specified). If a startIndex
is specified and is negative, it is used as the offset from the end of the collection.
Parameters
collection
{Array|Object|String}: The collection to iterate over.value
{String|Number|Array|Object}: The value to check for.
Example
<!-- array = ['a', 'b', 'c'] -->
{{#contains array "d"}}
This will not be rendered.
{{else}}
This will be rendered.
{{/contains}}
{{for}}
{{for a b}}
Repeats block for a specified range from index a
to index b
. To protect against infinite loops, this helper is limited to 100 iterations.
Parameters
a
{Number}: Starting number.b
{Number}: Ending number.
Example
{{#for 1 12}}
{{lang (concat 'common.short_months.' $index)}}
{{/for}}
{{if}}
{{if arg}}
Renders if
block when if-statement evaluates to true; otherwise renders else
block.
Parameters
arg
{String|Number|Array|Object}
Example
{{#if page_type '===' 'account_order'}}
<li class="navBar-item is-active">
<a class="navBar-action" href="{{urls.account.orders.all}}">{{lang 'account.nav.orders'}}</a>
</li>
{{else}}
<li class="navBar-item is-active">{{lang 'account.nav.orders'}}</li>
{{/if}}
{{or}}
{{or arg}}
Renders block if one or more parameters evaluates to true.
Parameters
arg
{String|Number|Array|Object}: Parameters can be of mixed types.
Example
{{#or 1 0 0 0 0 0 0}}
<!-- 1 evaluates to true, so block is rendered-->
{{/or}}
{{#or options configurable_fields}}
<a href="#" data-item-edit="{{id}}">{{lang 'cart.checkout.change'}}</a>
{{/or}}
{{unless}}
{{unless arg}}
Renders a block if a statement is false; does not support operators for comparison expressions.
Parameters
arg
{String|Number|Array|Object}
Example
{{#each category_results}}
<li class="category-suggestion">
{{#each this}}
<a href="{{url}}">{{name}}</a>
{{#unless @last}} > {{/unless}}
{{/each}}
</li>
{{/each}}
{{concat}}
{{concat value otherValue}}
Concatenates two strings.
Parameters
value
{String}otherValue
{String}
Example
{{concat 'hello' 'world'}}
<!-- => helloworld -->
{{join}}
{{join values separator}}
Joins an array of string elements into a single string.
Parameters
values
{Array}separator
{String}limit=<number>
: An optional limit.
Example
<!-- context = {
list: ['Mario', 'Chris', 'Mick', 'Hau', 'Cody']
} -->
{{join list " "}}
<!-- => 'Mario Chris Mick Hau Cody' -->
{{join list ", "}}
<!-- => 'Mario, Chris, Mick, Hau, Cody' -->
{{json}}
{{json object}}
Converts a JavaScript object into a JSON string.
Parameters
object
{Object}: A JavaScript object.
Example
<!-- context = {
object: { a: 1, b: "hello" }
} -->
{{json object}}
<!-- => '{"a":1,"b":"hello"}' -->
{{occurrences}}
{{occurrences str substring}}
Returns the number of occurrences of substring within the given string.
Parameters
str
{String}substring
{String}
Example
{{occurrences "foo bar foo bar baz" "foo"}}
<!-- => 2 -->
{{replace}}
{{replace firstParam secondParam string}}
Replaces all instances of the first parameter in the second parameter with the child block.
Parameters
firstParam
{?}secondParam
{?}string
{String}
Example
<!-- Replace all instances of `%%Syndicate%%` in `page.content` with `{{> components/page/rss_feed}}`. -->
{{#replace '%%Syndicate%%' page.content}}
{{> components/page/rss_feed}}
{{else}}
<p>{{{page.content}}}</p>
{{/replace}}
{{setURLQueryParam}}
{{setURLQueryParam url key value}}
Appends key values to a URL.
Parameters
url
{String}: The URL of the query parameter.key
{String}: The query parameter key.value
{Number}: The query parameter value of the stated key.
Example
{{setURLQueryParam "http://example.com/image.jpg" "c" "2"}}
<!-- results in: http://example.com/image.jpg?c=2 -->
{{stripQuerystring}}
{{stripQuerystring url}}
Strips query string from a URL.
Parameters
url
{String}: The URL containing the query parameter.
Example
{{stripQuerystring "http://example.com?tests=true"}}
<!-- results in: http://example.com -->
{{toLowerCase}}
{{toLowerCase string}}
Converts a string to lowercase.
Parameters
string
{String}: String you want to convert.
Example
{{toLowerCase 'I Love PIZZA'}}
<!-- => i love pizza -->
{{truncate}}
{{truncate string length}}
Truncates a string.
Parameters
string
{String}: The string you want to truncate.length
{Number}: The desired length of the returned truncated string.
Example
{{truncate "This will be truncated to only the first part of the sentence." 22}}
<!-- results in: 'This will be truncated' -->
{{block}}
{{block string}}
Defines a block of content. You can overwrite it using the partial helper.
Parameters
string
{String}
Example
<div class="container">
{{#block "page"}} {{/block}}
</div>
{{dynamicComponent}}
{{dynamicComponent path}}
Inserts a dynamic partial in the specified path.
Parameters
path
{String}: The path to insert a dynamic component in.
Example
{{#each forms.create_account.address_fields }}
{{{dynamicComponent 'components/common/forms'}}}
{{/each}}
{{inject}}
{{inject value object}}
Injects key values into the jsContext helper.
Parameters
value
{String}: The value to inject.object
{Object}
Example
{{inject "myProductName" product.title}}
<script>
var jsContext = JSON.parse({{jsContext}});
console.log(jsContext.myProductName);
// results in: "BigCommerce Coffee Mug"
</script>
{{inject 'productSize' theme_settings.product_size}}
<!-- Returns a JSON representation of an object of all the keys injected. -->
{{jsContext}}
{{jsContext}}
Returns a JSON representation of the data injected by the inject helper.
{{partial}}
{{partial string}}
Overrides content defined by the block helper.
Parameters
string
{String}
Example
{{#partial "head"}}
{{#if pagination.category.previous}}
<link rel="prev" href="{{pagination.category.previous}}">
{{/if}}
{{#if pagination.category.next}}
<link rel="next" href="{{pagination.category.next}}">
{{/if}}
{{/partial}}
{{region}}
{{region name}}
Specifies a widget region.
Parameters
name
{String}: The name of the region.
Example
<!-- context = {
banner-top: "hello world"
} -->
{{region name="banner-top"}}
<!-- => <div data-content-region="banner-top">hello world</div> -->
{{assignVar}}
{{assignVar key value}}
Assigns a variable for later use in the template.
Parameters
key
{String}value
{String|Number}
Example
{{assignVar "foo" 10}}
{{getVar}}
{{getVar key}}
Returns the variable set by assignVar.
Parameters
key
{String}
Example
{{getVar "foo"}}
{{decrementVar}}
{{decrementVar key}}
Decrements the variable set by assignVar by 1.
Parameters
key
{String}
Example
{{decrementVar "foo"}}
{{incrementVar}}
{{incrementVar key}}
Increments the variable set by assignVar by 1.
Parameters
key
{String}
Example
{{incrementVar "foo"}}
Standard helpers
Note
The information presented in this section was borrowed from helpers/handlebars-helpers.
The following table contains whitelisted standard Handlebars helpers available to all Stencil themes. Each helper is linked to its GitHub documentation including parameters and examples.
Helper | Category | Description |
---|---|---|
after | array | Returns all of the items in an array after the specified index. |
arrayify | array | Casts the given value to an array. |
before | array | Returns all of the items in the collection before the specified count. |
eachIndex | array | |
filter | array | Block helper that filters the given array and renders the block for values that evaluate to true , otherwise the inverse block is returned. |
first | array | Returns the first item or first n items of an array. |
forEach | array | Iterates over each item in an array and exposes the current item in the array as context to the inner block. |
inArray | array | Block helper that renders the block if an array has the given value . |
isArray | array | Returns true if value is an es5 array. |
last | array | Returns the last item, or last n items of an array or string. |
length | array | Returns the length of the given string or array. |
lengthEqual | array | Returns true if the the length of the given value is equal to the given length . |
map | array | Returns a new array created by calling function on each element of the given array. |
some | array | Block helper that returns the block if the callback returns true for some value in the given array. |
sort | array | Sorts the given array. If an array of objects is passed, you may optionally pass a key to sort on as the second argument. |
sortBy | array | Sorts an array. If an array of objects is passed, you may optionally pass a key to sort on as the second argument. |
withAfter | array | Uses the items in the array after the specified index as context inside a block. |
withBefore | array | Uses the items in the array before the specified index as context inside a block. |
withFirst | array | Uses the first item in a collection inside a handlebars block expression. |
withLast | array | Uses the last item or n items in an array as context inside a block. |
withSort | array | Block helper that sorts a collection and exposes the sorted collection as context inside the block. |
isEmpty | collection | Inline, subexpression, or block helper that returns true (or the block) if the given collection is empty, or false (or the inverse block, if supplied) if the collection is not empty. |
iterate | collection | Block helper that iterates over an array or object. If an array is given, .forEach is called, or if an object is given, .forOwn is called, otherwise the inverse block is returned. |
and | comparison | Helper that renders the block if both of the given values are truthy. If an inverse block is specified it will be rendered when falsy. |
default | comparison | Returns the first value that is not undefined, otherwise the default value is returned. |
eq | comparison | Block helper that renders a block if a is equal to b . If an inverse block is specified it will be rendered when falsy. |
gt | comparison | Block helper that renders a block if a is greater than b . If an inverse block is specified, it will be rendered when falsy. |
gte | comparison | Block helper that renders a block if a is greater than or equal to b . If an inverse block is specified it will be rendered when falsy. |
has | comparison | Block helper that renders a block if value has pattern. If an inverse block is specified it will be rendered when falsy. |
ifEven | comparison | Returns true if the given value is an even number. |
ifNth | comparison | Conditionally renders a block if the remainder is zero when a operand is divided by b . If an inverse block is specified it will be rendered when the remainder is not zero. |
ifOdd | comparison | Block helper that renders a block if value is an odd number. If an inverse block is specified it will be rendered when falsy. |
is | comparison | Block helper that renders a block if a is equal to b . If an inverse block is specified it will be rendered when falsy. Similar to eq but does not do strict equality. |
isnt | comparison | Block helper that renders a block if a is not equal to b . If an inverse block is specified it will be rendered when falsy. Similar to unlessEq but does not use strict equality for comparisons. |
lt | comparison | Block helper that renders a block if a is less than b . If an inverse block is specified it will be rendered when falsy. |
lte | comparison | Block helper that renders a block if a is less than or equal to b . If an inverse block is specified it will be rendered when falsy. |
neither | comparison | Block helper that renders a block if neither of the given values are truthy. If an inverse block is specified it will be rendered when falsy. |
unlessEq | comparison | Block helper that always renders the inverse block unless a is equal to b . |
unlessGt | comparison | Block helper that always renders the inverse block unless a is greater than b . |
unlessLt | comparison | Block helper that always renders the inverse block unless a is less than b . |
unlessGteq | comparison | Block helper that always renders the inverse block unless a is greater than or equal to b . |
unlessLteq | comparison | Block helper that always renders the inverse block unless a is less than or equal to b . |
moment | date | Use moment as a helper. |
sanitize | html | Strips HTML tags from a string, so that only the text nodes are preserved. |
ul | html | Block helper for creating unordered lists (<ul></ul> ). |
ol | html | Block helper for creating ordered lists (<ol></ol> ). |
thumbnailImage | html | Returns a <figure> with a thumbnail linked to a full picture. |
inflect | inflection | Returns either the singular or plural inflection of a word based on the given count. |
ordinalize | inflection | Returns an ordinalized number as a string. |
markdown | markdown | Block helper that converts a string of inline markdown to HTML. |
add | math | Returns the sum of a plus b . |
avg | math | Returns the average of all numbers in the given array. |
ceil | math | Returns the Math.ceil() of the given value. |
divide | math | Divides a by b . |
floor | math | Returns the Math.floor() of the given value. |
multiply | math | Returns the product of a times b . |
random | math | Generates a random number between two values. |
round | math | Rounds the given number. |
subtract | math | Returns the product of a minus b . |
sum | math | Returns the sum of all numbers in the given array. |
option | misc | Returns the given value of prop from this.options . |
noop | misc | Block helper that renders the block without taking any arguments. |
withHash | misc | Block helper that builds the context for the block from the options hash. |
addCommas | number | Adds commas to numbers. |
phoneNumber | number | Converts a string or number to a formatted phone number. |
toAbbr | number | Abbreviates numbers to the given number of precision. This is for general numbers, not size in bytes. |
toExponential | number | Returns a string representing the given number in exponential notation. |
toFixed | number | Formats the given number using fixed-point notation. |
toFloat | number | |
toInt | number | |
toPrecision | number | Returns a string representing the Number object to the specified precision. |
extend | object | Extends the context with the properties of other objects. A shallow merge is performed to avoid mutating the context. |
forIn | object | Block helper that iterates over the properties of an object exposing each key and value on the context. |
forOwn | object | Block helper that iterates over the own properties of an object, exposing each key and value on the context. |
toPath | object | Takes arguments and, if they are string or number, converts them to a dot-delineated object property path. |
get | object | Use property paths (a.b.c ) to get a value or nested value from the context. Works as a regular helper or block helper. |
getObject | object | Use property paths (a.b.c ) to get an object from the context. Differs from the get helper in that this helper will return the actual object including the given property key. This helper does not work as a block helper. |
hasOwn | object | Returns true if key is an own, enumerable property of the given context object. |
isObject | object | Returns true if value is an object. |
JSONparse | object | Parses the given string using JSON.parse . |
JSONstringify | object | Stringifies an object using JSON.stringify . |
merge | object | Deeply merges the properties of the given objects with the context object. |
pick | object | Picks properties from the context object. |
camelcase | string | camelCase the characters in the given string. |
capitalize | string | Capitalizes the first word in a sentence. |
capitalizeAll | string | Capitalizes all words in a string. |
center | string | Centers a string using non-breaking spaces. |
chop | string | Like trim, but removes both extraneous whitespace and non-word characters from the beginning and end of a string. |
dashcase | string | Replaces non-word characters and periods with hyphens. |
dotcase | string | dot.case the characters in a string. |
ellipsis | string | Truncates a string to the specified length, and appends it with an elipsis, … . |
hyphenate | string | Replaces spaces in a string with hyphens. |
isString | string | Returns true if value is a string. |
lowercase | string | Lowercase all characters in the given string. |
occurrences | string | Returns the number of occurrences of substring within the given string. |
pascalcase | string | PascalCase the characters in a string. |
pathcase | string | path/case the characters in a string. |
plusify | string | Replaces spaces in the given string with pluses. |
reverse | string | Reverses a string. |
sentence | string | Sentence case the given string. |
snakecase | string | snake_case the characters in the given string. |
split | string | Splits a string by the given character. |
startsWith | string | Tests whether a string begins with the given prefix. |
titleize | string | Title case the given string. |
trim | string | Removes extraneous whitespace from the beginning and end of a string. |
uppercase | string | Uppercase all of the characters in the given string. If used as a block helper it will uppercase the entire block. This helper does not support inverse blocks. |
encodeURI | url | Encodes a Uniform Resource Identifier (URI) component by replacing each instance of certain characters by one, two, three, or four escape sequences representing the UTF-8 encoding of the character. |
decodeURI | url | Decodes a Uniform Resource Identifier (URI) component. |
urlResolve | url | Takes a base URL and a href URL and resolves them as a browser would for an anchor tag. |
urlParse | url | Parses a URL string into an object. |
stripProtocol | url | Strips protocol from a URL. Useful for displaying media that may have an ‘http’ protocol on secure connections. |
Contributing to helpers
BigCommerce’s custom Handlebars helpers are open source. To contribute, make a pull request to bigcommerce/paper-handlebars.