Handlebars helpers for custom components

Every built-in helper you can use in a custom component template: text, lists, math, numbers, comparisons and dates, plus how to add your own.

  • Verified Nov 17, 2026
  • Classic builder

On this page
  1. How to use a helper
  2. Text
  3. Lists and objects
  4. Math
  5. Number formatting
  6. Comparisons
  7. Dates
  8. Other helpers
  9. Write your own helper
  10. Example: group records by a field

Helpers change how a value is shown in a custom component template: format a date, add numbers, compare two fields, loop over part of a list. This page lists every helper built into Tadabase, by category, and shows how to add your own.

How to use a helper #

Write the helper's name, then its values, separated by spaces. Text values go in quotes.

html
{{uppercase field_100}}
{{truncate field_100 20 "..."}}

Block helpers wrap part of the template and show it only when a condition is met. {{else}} adds what to show otherwise. Handlebars' own if, unless, each and with work the same way.

html
{{#if field_37}}
  {{multiply field_37 10}}
{{else}}
  No value yet
{{/if}}

To use one helper's result inside another, put the inner helper in parentheses. This adds 5 to field_37, then multiplies the result by 10:

html
{{multiply (add field_37 5) 10}}

The comparison helpers also work in parentheses, where they return true or false: {{#if (gt field_100 8)}} ... {{/if}}.

Text #

HelperWhat it doesExample
lowercaseMakes all letters lowercase.{{lowercase field_100}}: "HELLO World" becomes "hello world"
uppercaseMakes all letters uppercase.{{uppercase field_100}}: "hello" becomes "HELLO"
capitalizeFirstMakes the first character uppercase.{{capitalizeFirst field_100}}: "hello world" becomes "Hello world"
capitalizeEachMakes the first letter of each word uppercase.{{capitalizeEach field_100}}: "hello world" becomes "Hello World"
titleizeTurns spaces, hyphens and underscores into single spaces, then capitalizes each word.{{titleize field_100}}: "new_job-request" becomes "New Job Request"
sentenceCapitalizes the first letter of each sentence and makes the rest lowercase.{{sentence field_100}}: "hELLO. how ARE you?" becomes "Hello. How are you?"
reverseReverses the characters.{{reverse field_100}}: "abc" becomes "cba"
truncateShortens text to a length, counting the optional ending you add.{{truncate field_100 10 "..."}}: "This is a longer text" becomes "This is..."
centerAdds a number of non-breaking spaces on each side. Use triple braces.{{{center field_100 3}}}
newLineToBrTurns line breaks into <br> tags. Use triple braces.{{{newLineToBr field_100}}}
sanitizeReplaces every character that is not a letter or digit with -, or with the character you give.{{sanitize field_100}}: "Q3 report & notes" becomes "Q3-report---notes"
inflectPicks the singular or plural word for a count. Add true to show the count too.{{inflect field_100 "job" "jobs" true}}: 1 gives "1 job", 3 gives "3 jobs"
ordinalizeAdds st, nd, rd or th to a number.{{ordinalize field_100}}: 22 becomes "22nd"
defaultShows a fallback when the value is empty.{{default field_100 "Not set"}}

Lists and objects #

These work on any list, such as records or an Attachments field (obj.field_45).

HelperWhat it doesExample
first, lastThe first or last item. With a number, the first or last that many items.{{#each (first records 3)}} ... {{/each}}
after, beforeAll items after the first N, or all items except the last N.{{#each (after records 1)}} ... {{/each}}
withFirst, withLast, withAfter, withBeforeBlock versions of the four helpers above: the block repeats for each item.{{#withFirst records 3}}{{field_100}}{{/withFirst}}
lengthThe number of items.{{length records}}
lengthEqualShows the block when the list has exactly N items.{{#lengthEqual records 1}}One job{{/lengthEqual}}
any, emptyShows the block when the list has items, or has none.{{#empty records}}No jobs yet{{/empty}}
joinJoins the items into one text, with a space or the separator you give.{{join list ", "}}
inArrayShows the block when the list contains the value.{{#inArray list "Urgent"}} ... {{/inArray}}
isContainsLike inArray, and also works in parentheses.{{#if (isContains list "Urgent")}} ... {{/if}}
isInShows the block when a value equals one of the values listed after it.{{#isIn field_101 "Open" "Pending"}} ... {{/isIn}}
isArrayShows the block when the value has at least one item or key.{{#isArray obj.field_45}} ... {{/isArray}}
eachIndexLoops over a list, giving item and its position index (from 0).{{#eachIndex records}}{{index}}: {{item.field_100}}{{/eachIndex}}
eachProperty, eachKeyLoops over an object, giving each key and value.{{#eachProperty obj.field_47}}{{key}}: {{value}}{{/eachProperty}}
getArrayReads a value from an object by its path. Objects and lists come back as JSON text.{{getArray obj.field_40 "city"}}

Math #

HelperWhat it doesExample
addAdds any number of values. A value that is not a number counts as 0.{{add field_100 field_101 5}}
subtractSubtracts each following value from the first.{{subtract field_100 5}}: 100 becomes 95
multiplyMultiplies any number of values.{{multiply field_100 10}}: 100 becomes 1000
divideDivides the first value by each following value.{{divide field_100 10}}: 100 becomes 10
floor, ceil, roundRounds down, up, or to the nearest whole number.{{round field_100}}: 100.69 becomes 101
mathRuns one operator on two values: +, -, *, /, %, or a comparison (==, !=, <, <=, >, >=) that returns true or false.{{math field_100 "%" 2}}

Number formatting #

HelperWhat it doesExample
toFixedShows exactly N decimal places, rounding if needed (0 if you give none).{{toFixed field_100 2}}: 5.53231 becomes 5.53
toPrecisionRounds to N significant digits (1 if you give none).{{toPrecision field_100 4}}: 555.322 becomes 555.3
toExponentialShows the number in exponential notation with N decimal places (0 if you give none).{{toExponential field_100 2}}: 5 becomes 5.00e+0
toIntReads a whole number from the start of the value.{{toInt field_100}}: "22.7abc" becomes 22
toFloatReads a decimal number from the start of the value, optionally rounded to N places. Shows nothing if the value is not a number.{{toFloat field_100 2}}: "22.256" becomes 22.26
digitGroupingAdds a thousands separator: a comma, or the separator you give. Use it on whole numbers.{{digitGrouping field_100}}: 2222222 becomes 2,222,222

Comparisons #

Each comparison shows its block when the test passes and the {{else}} part when it fails. In parentheses, it returns true or false.

HelperPasses whenExample
isThe two values are equal. The text "5" and the number 5 count as equal.{{#is field_101 "Lead"}}This customer is a lead{{else}}Not a lead yet{{/is}}
isntThe two values are not exactly the same, including their type, or the first is empty.{{#isnt field_101 "Closed"}} ... {{/isnt}}
gt, gteThe first value is greater than, or greater than or equal to, the second.{{#gt field_100 8}} ... {{/gt}}
lt, lteThe first value is less than, or less than or equal to, the second.{{#lte field_100 5}} ... {{/lte}}
orEither of two values has a value.{{#or field_100 field_101}} ... {{/or}}
andBoth values have a value.{{#and field_100 field_101}} ... {{/and}}
orEqualsEither of the first two values is exactly the third.{{#orEquals field_101 field_102 "Open"}} ... {{/orEquals}}
issNot a block: returns the third value when the first two are exactly the same, otherwise the fourth.{{iss field_101 "Open" "Yes" "No"}}

Dates #

HelperWhat it doesExample
formatDateFormats a date with the directives below. Shows nothing when the date is empty.{{formatDate field_34 "%m/%d/%Y"}}
nowThe current date and time, optionally formatted. Supports most directives below, but not the -, ^ or : flags, %G or %%.{{now "%Y-%m-%d"}}
timeagoHow long ago the date was, such as "3 days ago" or "Just now".{{timeago field_34}}
ageWhole years since the date. Add "Y,M" (any of Y, M, D, H, Mi, S) for a text like "2 years 3 months", or "1" for all parts.{{age field_34 "Y,M"}}
dateDiffThe time between two dates, in the parts you list (Y, M, D, H, Mi, S, or "1" for all). When the result has only one part, only its number is shown. Months count as 30 days and years as 365. Use "now" for the current time.{{dateDiff field_34 "now" "D"}}
dateAdd, dateSubAdds or subtracts an amount from a date (or "now"), then formats it. Units: day(s), month(s), year(s), hour(s), minute(s), second(s); a number alone means days. The default format is %Y-%m-%d %H:%M:%S.{{dateAdd field_34 "7 days" "%m/%d/%Y"}}

Format directives for formatDate:

DirectiveShows
%Y, %yYear: 2026, 26
%m, %-mMonth number: 03, 3
%B, %bMonth name: March, Mar
%d, %-dDay of the month: 07, 7
%jDay of the year: 066
%A, %aWeekday: Saturday, Sat
%u, %wWeekday number: Monday is 1 (1 to 7), Sunday is 0 (0 to 6)
%H, %IHour, 24-hour (00 to 23) or 12-hour (01 to 12). Add - to drop the zero: %-I
%M, %S, %LMinutes, seconds, milliseconds
%p, %PAM or PM, am or pm
%z, %:zTime zone offset: +0900, +09:00
%V, %GISO week number and week-based year
%sSeconds since 1 January 1970
%F, %D, %T, %R, %rShortcuts for %Y-%m-%d, %m/%d/%y, %H:%M:%S, %H:%M and %I:%M:%S %p
%^B, %^b, %^A, %^aMonth or weekday name in capitals: MARCH, SAT
%%A % sign

Other helpers #

HelperWhat it doesExample
jsonPrints a value as formatted JSON. Use it while building to see what a field contains.{{json obj.field_44}}
assignSaves a value under a name; read it back with @root.{{assign "lastStatus" field_101}} then {{@root.lastStatus}}
brAdds one or more line breaks.{{br 2}}
log, debugWrite a value, or the current record, to the browser console.{{log field_100}}

The tb_ helpers for links, pagination, search and filter tabs are described in Build your own component with custom code.

Write your own helper #

Register a helper with Handlebars.registerHelper in a <script> tag in your app's custom footer code, under Custom Header/Footer Code in the app settings (see Custom header and footer code). The helper is then available in every custom component in the app.

This helper checks whether a value starts with some text:

html
<script>
  Handlebars.registerHelper('startsWith', function (value, prefix) {
    return typeof value === 'string' && value.indexOf(prefix) === 0;
  });
</script>

Use it in a template inside parentheses:

html
{{#each records}}
  {{#if (startsWith field_43 "113-")}}
    <p>Order {{field_43}}</p>
  {{/if}}
{{/each}}

Example: group records by a field #

A helper can also reshape the records. This one groups them by the value of a field, so the template can show a heading per group, such as a shopping list grouped by category:

html
<script>
  Handlebars.registerHelper('groupBy', function (records, fieldSlug) {
    var groups = {};
    (records || []).forEach(function (record) {
      var key = record[fieldSlug] || 'Other';
      if (!groups[key]) {
        groups[key] = [];
      }
      groups[key].push(record);
    });
    return groups;
  });
</script>
html
{{#each (groupBy records "field_63")}}
  <h2>{{@key}}</h2>
  <ol>
    {{#each this}}
      <li>{{tb_link this tb-id="1" tb-value="Edit"}} {{field_62}}</li>
    {{/each}}
  </ol>
{{/each}}

Replace field_63 with the slug of the field to group by, and click that field once in the Fields list so its value loads.

Was this page helpful?

Something wrong or missing on this page? Tell us.