Handlebars Helpers Reference

This page lists the custom Handlebars helpers available for use in templates, grouped by type, along with a description of what each one does and a worked example.

Content & Strings

concat

Concatenates any number of arguments into a single string.

{{concat "Hello, " "World" "!"}}

> Hello, World!

format

Formats a value according to a given type. Currently supports "number", using Intl.NumberFormat with an optional options object (e.g. locale, minimum/maximum fraction digits). Defaults to the pt-PT locale when none is specified.

{{format "number" 1234.5}}

> 1 234,5

{{format "number" 1234.5 '{"locale":"en-US"}'}}

> 1,234.5

includes

Checks whether arg1 contains arg2. Works with strings and arrays (single-element arrays are unwrapped before comparison). Pass true as the third argument for a case-insensitive comparison. Returns false if either argument is null.

{{includes "Hello World" "World"}}

> true

{{includes "Hello World" "world" true}}

> true

markdown

Converts a Markdown-formatted string into HTML. If no text is provided, it returns an empty string.

{{markdown "**Important:** please review."}}

> <p><strong>Important:</strong> please review.</p>

pasteInRm

Builds a JSON payload used to auto-paste field values into RecordM instances. It accepts an alternating list of field name/value pairs (key1 value1 key2 value2 ...) and returns a stringified JSON object describing the fields and the auto-paste-if-empty option. Returns an empty string if no pairs are given.

{{pasteInRm "name" "John Doe" "age" 30}}

> {"opts":{"auto-paste-if-empty":true},"fields":[{"value":"John Doe","fieldDefinition":{"name":"name"}},{"value":30,"fieldDefinition":{"name":"age"}}]}

replace

Replaces the first occurrence of oldValue with newValue inside a string. Returns an empty string if word is not a string.

{{replace "Hello World" "World" "Handlebars"}}

> Hello Handlebars

startsWith

Checks whether arg1 (a string) starts with arg2.

{{#if (startsWith "Mr. Smith" "Mr.")}}
  Formal greeting
{{/if}}

> Formal greeting

Lists & Arrays

createVar

Sets varsObject[varName] = value, allowing a value to be stored on a shared object for later reuse within a template. Does not return a value itself.

{{createVar myVars "total" 42}}
{{myVars.total}}

> 42

every

Iterates over the keys/values of an object or array, evaluating a JavaScript expression (evalCode) for each entry, and returns true only if all entries satisfy the expression, otherwise false. Inside evalCode, key and val refer to the current entry's key and value.

{{every users "val.age >= 18"}}

> true

Given users = [{"age": 20}, {"age": 25}]

filter

Iterates over the keys/values of an object or array, evaluating a JavaScript expression (evalCode) for each entry, and returns a new object/array containing only the entries for which the expression is truthy. Inside evalCode, key and val refer to the current entry's key and value. Returns an empty array if nothing matches.

{{filter users "val.age >= 18"}}

> [{"age": 20}, {"age": 30}]

Given users = [{"age": 15}, {"age": 20}, {"age": 30}]

listFilter

Filters a list of objects, keeping only those whose field matches value (works for both direct values and array-type field values, comparing as strings). If first is "true", only the first match is returned. Returns null if nothing matches.

{{listFilter tickets "status" "open"}}

> [{"status": "open"}]

Given tickets = [{"status": "open"}, {"status": "closed"}]

{{listFilter tickets "status" "open" "true"}}

> [{"status": "open"}]

listSort

Sorts an array, optionally by a given field, in ascending ("asc") or descending (default) order.

{{listSort tickets "priority" "asc"}}

> [{"priority": 1}, {"priority": 2}, {"priority": 3}]

Given tickets = [{"priority": 3}, {"priority": 1}, {"priority": 2}]

lookupWithDefault

Looks up key on obj and returns its value, or defaultValue if the value is falsy/missing.

{{lookupWithDefault user "nickname" "N/A"}}

> N/A

Given user = {"name": "John"} (no nickname)

some

Iterates over the keys/values of an object or array, evaluating a JavaScript expression (evalCode) for each entry, and returns true as soon as any entry satisfies the expression, otherwise false. Inside evalCode, key and val refer to the current entry's key and value.

{{some users "val.age < 18"}}

> true

Given users = [{"age": 20}, {"age": 15}]

times

Block helper that repeats its content n times, providing the current iteration index (starting at 1) to the block.

{{#times 3}}
  Item {{this}}
{{/times}}

> Item 1 Item 2 Item 3

Logic & Comparison

and

Returns the logical AND of two arguments.

{{#if (and isActive isVerified)}}
  Account approved
{{/if}}

> Account approved

Given isActive = true and isVerified = true

eq

Checks whether two values are equal. If both arguments are arrays, it compares their first elements as arrays; otherwise it performs a loose (==) comparison.

{{#if (eq status "open")}}
  Ticket is open
{{/if}}

> Ticket is open

Given status = "open"

greaterOrEq

Block helper. Renders the block if arg1 >= arg2 (numeric comparison), otherwise renders the inverse block.

{{#greaterOrEq 75 70}}
  Pass
{{else}}
  Fail
{{/greaterOrEq}}

> Pass

greaterThan

Returns true if arg1 > arg2 (numeric comparison; arg1 defaults to 0 if falsy).

{{#if (greaterThan 75 70)}}
  Above threshold
{{/if}}

> Above threshold

lesserOrEq

Block helper. Renders the block if arg1 <= arg2 (numeric comparison), otherwise renders the inverse block.

{{#lesserOrEq 40 50}}
  Low
{{else}}
  High
{{/lesserOrEq}}

> Low

lessThan

Returns true if arg1 < arg2 (numeric comparison; arg1 defaults to 0 if falsy).

{{#if (lessThan 40 50)}}
  Below threshold
{{/if}}

> Below threshold

not

Returns the logical negation of its argument.

{{#if (not isHidden)}}
  Visible
{{/if}}

> Visible

Given isHidden = false

or

Returns the logical OR of two arguments.

{{#if (or hasAdminRole hasEditorRole)}}
  Can edit
{{/if}}

> Can edit

Given hasAdminRole = false and hasEditorRole = true

Math

add

Adds two numeric values together. arg1 defaults to 0 if falsy.

{{add 5 3}}

> 8

div

Divides a by b, returning a decimal result. Returns 0 if either argument is falsy or zero.

{{div 10 4}}

> 2.5

max

Returns the larger of two numbers.

{{max 10 20}}

> 20

min

Returns the smaller of two numbers.

{{min 10 20}}

> 10

multiply

Multiplies arg1 by arg2. Both default to 0 if falsy.

{{multiply 6 7}}

> 42

subtract

Subtracts arg2 from arg1. Both default to 0 if falsy.

{{subtract 10 4}}

> 6

Dates & Time

compareDates

Compares two dates (accepting date strings or timestamps), ignoring time of day. Returns -1 if the first date is earlier, 1 if later, or 0 if they fall on the same day.

{{compareDates "2024-01-01" "2024-01-02"}}

> -1

compareDateTimes

Same as compareDates, but also takes hours and minutes into account when determining equality.

{{compareDateTimes "2024-01-01T10:00:00" "2024-01-01T09:00:00"}}

> 1

dateInfo

Given a date string and a keyword, returns a derived date value. Supported keywords: LastDateOfYear, FirstDateOfYear, LastDateOfMonth, FirstDateOfMonth, MonthText, FullDateText, WeekDayText, FullYear, MonthIndexAt1, FirstEpochOfYear, LastEpochOfYear, FirstEpochOfMonth, LastEpochOfMonth, FirstEpochOfDay, LastEpochOfDay. Returns an empty string if no date string is given, or undefined for an unrecognized keyword.

{{dateInfo "2024-03-15" "FirstDateOfMonth"}}

> 2024-03-01T00:00:00.000Z

Exact time depends on the server's timezone.

{{dateInfo "2024-03-15" "MonthText"}}

> Mar

dateInfoTimestamp

Given a Unix timestamp and a keyword, returns a formatted date/time string. Supported keywords: FullDateTime, FullDate, FullTime, FullWithWeekDay, WeekDay. Returns "No date." if no timestamp is given or the keyword is unrecognized.

{{dateInfoTimestamp 1710500000000 "FullDate"}}

> 15/03/2024

Exact format depends on the browser's locale and timezone.

nextPage

Advances a date or number forward by a given step size, useful for pagination/navigation controls. For dates, size is a string like "1d", "2w", "1m", or "1y" (days/weeks/months/years). For numbers, size is added directly. An optional limit caps the result so it doesn't go past a given date or number.

{{nextPage "2024-01-15" "1m"}}

> 2024-02-15T00:00:00.000Z

{{nextPage 10 10 100}}

> 20

prevPage

Same as nextPage, but moves backward instead of forward.

{{prevPage "2024-01-15" "1m"}}

> 2023-12-15T00:00:00.000Z

{{prevPage 10 10 0}}

> 0

today

Returns the current date/time as an ISO 8601 string.

{{today}}

> 2026-08-07T09:15:00.000Z

todayTimestamp

Returns the current date/time as a Unix timestamp in milliseconds.

{{todayTimestamp}}

> 1786100514408

Environment & Context

isNaked

Returns true if the application is currently running in "naked" mode.

{{#if (isNaked)}}
  Simplified UI
{{/if}}

> Simplified UI

Shown when the app is running in naked mode.

screenMd

Returns true if the current viewport width is 768px or less.

{{#if (screenMd)}}
  Show mobile menu
{{/if}}

> Show mobile menu

Shown when the viewport is 768px or narrower.

screenSm

Returns true if the current viewport width is 640px or less.

{{#if (screenSm)}}
    Show compact layout
{{/if}}

> Show compact layout

Shown when the viewport is 640px or narrower.