Thanks for being patient while we implement your feedback to improve the developer experience.
Stencil Docs
Reference
Handlebars Helpers

Handlebars Helpers Reference

This article is a reference for Stencil supported Handlebars (opens in a new tab) helpers. It includes custom helpers documentation and a list of acceptlisted standard helpers.

Custom helpers

The following table contains BigCommerce's open source Handlebars helpers (opens in a new tab).

HelperCategoryDescription
limitarrayLimits array to second argument.
pluckarrayUses search key to get values from collections.
cdnassetsA URL transformer for content delivery networks.
earlyHintassetsReduces page load time and perceived latency.
moneycurrencyFormats number length, thousands delimiter, and decimal delimiter.
momentdateUse momentjs (opens in a new tab) to format and calculate dates.
getFontLoaderConfigfontsReturns font-loader config as a JSON string.
getFontsCollectionfontsReturns <link> elements for configured fonts.
encodeHtmlEntitieshtmlEncodes HTML entities.
nl2brhtmlConverts newline characters to <br> tags.
prehtmlRenders preformatted text.
resourceHintshtmlPre-fetches Google fonts.
stylesheethtmlRenders a <link> tag for inserting a stylesheet.
langi18nMaps keys to translation files.
langJsoni18nReturns language translation keys as a JSON string.
getContentImageimagesReturns sized image URL from store's /content directory.
getContentImageSrcsetimagesReturns source set of URLs for images in /content.
getImageimagesReturns image URL for specified size.
getImageManagerImageimagesReturns sized image URL for images in /product_images/uploaded_images.
getImageManagerImageSrcsetimagesReturns image srcset for images in /product_images/uploaded_images.
getImageSrcsetimagesReturns single image URL or list of URLs for different sizes.
anylogicRenders block if any params are true.
alllogicRenders block if all params are true.
comparelogicCompares values with JavaScript operators, including typeof.
containslogicRenders block if first param is in second param.
forlogicIterates for range a to b, inclusive of b.
iflogicRenders block if statement is true.
orlogicRenders block if one or more parameters evaluate to true.
unlesslogicRenders block if a statement evaluates to false.
optionmiscReturns the given value of prop from this.options.
getobjectUse property paths (a.b.c) to get a value or nested value from the context.
getObjectobjectUse property paths (a.b.c) to get an object from the context.
concatstringConcatenates two strings.
joinstringJoins an array of string elements into one string.
jsonstringConverts a JavaScript object into a JSON string.
occurrencesstringReturns the number of occurrences of substring within the given string.
replacestringReplaces all instances of the first parameter in the second parameter.
setURLQueryParamstringAppends keys values to a URL.
stripQuerystringstringRemoves a query string.
strReplacestringReplaces some or all occurrences of a target substring within a subject string.
toLowerCasestringConverts a string to lowercase.
truncatestringTruncates a string.
blocktemplateDefines a content block.
dynamicComponenttemplateInserts a dynamic partial in the specified path.
injecttemplateInjects key values into {{jsContext}}.
jsContexttemplateReturns JSON for all data injected by {{inject}}.
partialtemplateOverrides content defined by {{block}}.
regiontemplateSpecifies a widget region.
assignVarvariablesSaves value to a variable.
getVarvariablesReturns a variable value.
decrementVarvariablesDecrements a variable by 1.
incrementVarvariablesIncrements 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}}
        </div>
    </li>
{{/each}}

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. When used in conjunction with the built-in {{each}} helper, returns retrieved values in an array.

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 -->
 
Standard pluck helper example:
// {{pluck items "data.title"}}
results in: '["aa", "bb", "cc"]'

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 (opens in a new tab).

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.

Early Hint and cdn

Early Hints reduce page load time and perceived latency by allowing browsers to download critical assets earlier in the request lifecycle. For more information, see Early Hint.

Parameters
  • resourceHint - (String)
    • Corresponds to the rel attribute in <link>.
    • Value can be any of preload, preconnect, prerender, dns-prefetch.
    • For more information, see rel (opens in a new tab) on MDN Web Docs.
  • as - (String)
    • Corresponds to the as attribute in <link>.

    • Value can be any of style, font, script, document.

    • If an invalid value is provided, as won't be included.

    • This parameter is optional.

    • For more information, see as (opens in a new tab) on MDN Web Docs.

  • crossorigin - (String)
    • Value can be any of no, anonymous, use-credentials.

    • Defaults to no when no value is provided.

    • This parameter is optional.

    • For more information, see crossorigin (opens in a new tab) on MDN Web Docs.

Example

The following script is an example of Early Hints usage in the Cornerstone theme:

<script async src="{{cdn 'assets/dist/theme-bundle.head_async.js' resourceHint='preload' as='script'}}"></script>

You can view more Early Hints usage in Cornerstone's templates/layout/base.html file by visiting the Cornerstone Repository (opens in a new tab).

EarlyHint

{{ earlyHint '{path}' '{rel}' [as='{script|style|font}'] [crossorigin='{no|anonymous|use-credentials}'] }}
 

Retrieves the provided URL and produces an early hint to communicate important web page resources. The server indicates which site assets (such as CSS files, JS scripts, and fonts) a browser needs to render a page fully. When used in conjunction with the {{cdn}} helper, load times can improve by 30%.

Parameters

  • path (String): The URL that hosts the resource being hinted.

  • rel (String): Valid arguments are preload, preconnect, prerender, and dns-prefetch.

  • as (String): Optional. Valid arguments are script, style, font.

  • crossorigin (String): Optional. Valid arguments are no (default), anonymous, and use-credentials.

Examples

{{earlyHint 'https://ajax.googleapis.com/ajax/libs/webfont/1.6.26/webfont.js' 'preload' as='script' crossorigin='anonymous'}}

This example produces an early hint in a Link header that looks like:

<https://ajax.googleapis.com/ajax/libs/webfont/1.6.26/webfont.js>; rel=preload; as=script; crossorigin=anonymous

The following example uses the getFontsCollection and stylesheet helpers. These helpers produce early hints by default, without using the earlyHint helper directly.

<script async src="{{cdn 'assets/dist/theme-bundle.head_async.js' resourceHint='preload' as='script'}}"></script>
 
{{getFontsCollection font-display='block'}}
 
<script async src="{{cdn 'assets/dist/theme-bundle.font.js' resourceHint='preload' as='script'}}"></script>
 
{{{stylesheet '/assets/css/theme.css'}}}

The output displays in a Link header that looks like:

Link: <https://cdn.staging.zone/s-cq2iowdr0q/stencil/94e324f0-d179-013b-2a85-0ac13303cc0f/dist/theme-bundle.head_async.js>; rel=preload; as=script; crossorigin=anonymous, 
<https://fonts.googleapis.com/css?family=Montserrat:700,500,400%7CKarla:400&display=block>; rel=preload; as=style, <https://cdn.staging.zone/s-cq2iowdr0q/stencil/94e324f0-d179-013b-2a85-0ac13303cc0f/dist/theme-bundle.font.js>; rel=preload; as=script
<https://cdn.staging.zone/s-cq2iowdr0q/stencil/94e324f0-d179-013b-2a85-0ac13303cc0f/css/theme-6bec0d40-d17a-013b-e9d8-02ea0e5c37ab.css>; rel=preload; as=style

moment

{{moment date format}}

Use momentjs (opens in a new tab) to format and calculate dates.

Examples

{{moment "5 hours ago" "MM/DD/YYYY HH:mm"}}
<!-- example calculation -->

If you encounter an issue with the last day of the month, use one of the following fixes:

{{moment date format datejs=false}}
<!-- To disable date.js -->
{{moment "January 1, 2022" format="YYYY-MM-DD"}}
<!-- To call moment.js functions -->

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 the Google_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): Acceptlist of allowed named arguments. Allowed arguments: useNamedReferences, decimal, encodeEverything, allowUnsafeSymbols. Specify arg='true' to use. For example, decimal='true'.

Examples

{{encodeHtmlEntities 'foo © bar ≠ baz 𝌆 qux'}}
<!-- => foo &#xA9; bar &#x2260; baz &#x1D306; qux -->
 
{{encodeHtmlEntities 'an ampersand: &'}}
<!-- => an ampersand: &#x26; -->
 
{{encodeHtmlEntities "foo © bar ≠ baz 𝌆 qux" useNamedReferences="true"}}
<!-- Returns a string with HTML entities encoded with named references. -->
<!-- => foo &copy; bar &ne; baz &#x1D306; qux -->
 
{{encodeHtmlEntities "foo © bar ≠ baz 𝌆 qux" decimal="true"}}
<!-- Returns a string with HTML entities encoded with decimal option. -->
<!-- => foo &#169; bar &#8800; baz &#119558; qux -->
 
{{encodeHtmlEntities "foo © bar ≠ baz 𝌆 qux" encodeEverything="true"}}
<!-- Returns a string with HTML entities encoded with encodeEverything option. -->
<!-- => &#x66;&#x6F;&#x6F;&#x20;&#xA9;&#x20;&#x62;&#x61;&#x72;&#x20;&#x2260;&#x20;&#x62;&#x61;&#x7A;&#x20;&#x1D306;&#x20;&#x71;&#x75;&#x78; -->
 
{{encodeHtmlEntities "foo © and & ampersand" allowUnsafeSymbols="true"}}
<!-- Returns a string with HTML entities encoded with allowUnsafeSymbols option. -->
<!-- => foo &#xA9; 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>&quot;&lt;div&gt;&amp;\\&quot;500\\&quot;&lt;/div&gt;&quot;</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.scss" 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 (opens in a new tab).

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 (opens in a new tab).

Parameters

  • stencilImage (String): A Stencil image.
  • size (String): A key in the theme_settings object.
  • defaultImage (String): Optional default image URL to use if the stencilImage is undefined.

Example

{{getImage image "logo"}}

getImageManagerImage

{{getImageManagerImage path width height}}

Returns an Image Manager (opens in a new tab) 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 (opens in a new tab).

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 (opens in a new tab) 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 (opens in a new tab) 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 the theme_settings object.
  • defaultImage (String): Optional default image URL to use if the stencilImage 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 (opens in a new tab). 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 (opens in a new tab). 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 (opens in a new tab), 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

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. (Inclusive)

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}}

option

<!-- context = {options: {a: {b: {c: 'ddd'}}}} -->
 * {{option "a.b.c"}}
 * <!-- results => `ddd` -->

Returns the given value of prop from this.options.

Example

context = {
  "options": {
    "a": {
      "b": {
        "c": "ddd"
       }
    }
  }
}

{{option "a.b.c"}} returns "ddd"

get

{{get (concat “a.b.c.d”) someObject}}

Use property paths (a.b.c) to get a value or nested value from the context. Works as a regular helper or block helper. You can use return values from the concat helper as property paths.

Example

{{#get "posts" blog}}{{/get}}

getObject

{{#with (getObject "a.b.c" someObject)}}...{{/with}}

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.

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 -->

strReplace

{{strReplace subjectString targetSubstring newSubstring occurrenceSelection}}

Replaces some or all occurrences of a target substring within the subject string.

Parameters

  • subjectString (String): The original string to modify.
  • targetSubstring (String): The substring in subjectString to be replaced.
  • newSubstring (String): The substring to insert in place of targetSubstring.
  • occurenceSelection (Integer): Optional. The number of occurrences of targetSubstring to replace with newSubstring. If you pass no argument or the supplied integer is greater than the number of targetSubstring occurrences, newSubstring will replace all instances of targetSubstring. A positive integer n will replace n instances of targetSubstring, starting from the left side of the string. Arguments of zero or less will replace no instances. Non-integer arguments may have unpredictable results.

Example

<!-- Replace all instances -->
{{strReplace "Buy one, get one half price. Limit one per customer." "one" "two"}}
<!-- output: Buy two, get two half price. Limit two per customer. -->
 
{{strReplace "Buy one, get one half price. Limit one per customer." "one" "two" 3}}
<!-- output: Buy two, get two half price. Limit two per customer. -->
 
{{strReplace "Buy one, get one half price. Limit one per customer." "one" "two" 100}}
<!-- output: Buy two, get two half price. Limit two per customer. -->
 
 
<!-- Replace some instances -->
{{strReplace "Buy one, get one half price. Limit one per customer." "one" "two" 2}}
<!-- output: Buy two, get two half price. Limit one per customer. -->
 
 
<!-- Replace no instances -->
{{strReplace "Buy one, get one half price. Limit one per customer." "one" "two" 0}}
<!-- output: Buy one, get one half price. Limit one per customer. -->
 
{{strReplace "Buy one, get one half price. Limit one per customer." "one" "two" -2}}
<!-- output: Buy one, get one half price. Limit one per customer. -->

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}}