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

Source: https://tadabase.com/docs/pages/custom-component-helpers  
Status: Verified Nov 17, 2026. Checked against the current product

Helpers change how a value is shown in a [custom component](https://tadabase.com/docs/pages/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}}`.

> **A missing value can stop the template:** Text helpers such as `lowercase` and `truncate` stop the whole template with an error when the field has no value at all, for example a field that is not loaded. If a component shows nothing, open the browser console, and wrap the helper in `{{#if field_100}} ... {{/if}}`.

## Text

| Helper | What it does | Example |
| --- | --- | --- |
| `lowercase` | Makes all letters lowercase. | `{{lowercase field_100}}`: "HELLO World" becomes "hello world" |
| `uppercase` | Makes all letters uppercase. | `{{uppercase field_100}}`: "hello" becomes "HELLO" |
| `capitalizeFirst` | Makes the first character uppercase. | `{{capitalizeFirst field_100}}`: "hello world" becomes "Hello world" |
| `capitalizeEach` | Makes the first letter of each word uppercase. | `{{capitalizeEach field_100}}`: "hello world" becomes "Hello World" |
| `titleize` | Turns spaces, hyphens and underscores into single spaces, then capitalizes each word. | `{{titleize field_100}}`: "new_job-request" becomes "New Job Request" |
| `sentence` | Capitalizes the first letter of each sentence and makes the rest lowercase. | `{{sentence field_100}}`: "hELLO. how ARE you?" becomes "Hello. How are you?" |
| `reverse` | Reverses the characters. | `{{reverse field_100}}`: "abc" becomes "cba" |
| `truncate` | Shortens text to a length, counting the optional ending you add. | `{{truncate field_100 10 "..."}}`: "This is a longer text" becomes "This is..." |
| `center` | Adds a number of non-breaking spaces on each side. Use triple braces. | `{{{center field_100 3}}}` |
| `newLineToBr` | Turns line breaks into `<br>` tags. Use triple braces. | `{{{newLineToBr field_100}}}` |
| `sanitize` | Replaces 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" |
| `inflect` | Picks 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" |
| `ordinalize` | Adds st, nd, rd or th to a number. | `{{ordinalize field_100}}`: 22 becomes "22nd" |
| `default` | Shows 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`).

| Helper | What it does | Example |
| --- | --- | --- |
| `first`, `last` | The first or last item. With a number, the first or last that many items. | `{{#each (first records 3)}} ... {{/each}}` |
| `after`, `before` | All items after the first N, or all items except the last N. | `{{#each (after records 1)}} ... {{/each}}` |
| `withFirst`, `withLast`, `withAfter`, `withBefore` | Block versions of the four helpers above: the block repeats for each item. | `{{#withFirst records 3}}{{field_100}}{{/withFirst}}` |
| `length` | The number of items. | `{{length records}}` |
| `lengthEqual` | Shows the block when the list has exactly N items. | `{{#lengthEqual records 1}}One job{{/lengthEqual}}` |
| `any`, `empty` | Shows the block when the list has items, or has none. | `{{#empty records}}No jobs yet{{/empty}}` |
| `join` | Joins the items into one text, with a space or the separator you give. | `{{join list ", "}}` |
| `inArray` | Shows the block when the list contains the value. | `{{#inArray list "Urgent"}} ... {{/inArray}}` |
| `isContains` | Like `inArray`, and also works in parentheses. | `{{#if (isContains list "Urgent")}} ... {{/if}}` |
| `isIn` | Shows the block when a value equals one of the values listed after it. | `{{#isIn field_101 "Open" "Pending"}} ... {{/isIn}}` |
| `isArray` | Shows the block when the value has at least one item or key. | `{{#isArray obj.field_45}} ... {{/isArray}}` |
| `eachIndex` | Loops over a list, giving `item` and its position `index` (from 0). | `{{#eachIndex records}}{{index}}: {{item.field_100}}{{/eachIndex}}` |
| `eachProperty`, `eachKey` | Loops over an object, giving each `key` and `value`. | `{{#eachProperty obj.field_47}}{{key}}: {{value}}{{/eachProperty}}` |
| `getArray` | Reads a value from an object by its path. Objects and lists come back as JSON text. | `{{getArray obj.field_40 "city"}}` |

## Math

| Helper | What it does | Example |
| --- | --- | --- |
| `add` | Adds any number of values. A value that is not a number counts as 0. | `{{add field_100 field_101 5}}` |
| `subtract` | Subtracts each following value from the first. | `{{subtract field_100 5}}`: 100 becomes 95 |
| `multiply` | Multiplies any number of values. | `{{multiply field_100 10}}`: 100 becomes 1000 |
| `divide` | Divides the first value by each following value. | `{{divide field_100 10}}`: 100 becomes 10 |
| `floor`, `ceil`, `round` | Rounds down, up, or to the nearest whole number. | `{{round field_100}}`: 100.69 becomes 101 |
| `math` | Runs one operator on two values: `+`, `-`, `*`, `/`, `%`, or a comparison (`==`, `!=`, `<`, `<=`, `>`, `>=`) that returns true or false. | `{{math field_100 "%" 2}}` |

## Number formatting

| Helper | What it does | Example |
| --- | --- | --- |
| `toFixed` | Shows exactly N decimal places, rounding if needed (0 if you give none). | `{{toFixed field_100 2}}`: 5.53231 becomes 5.53 |
| `toPrecision` | Rounds to N significant digits (1 if you give none). | `{{toPrecision field_100 4}}`: 555.322 becomes 555.3 |
| `toExponential` | Shows the number in exponential notation with N decimal places (0 if you give none). | `{{toExponential field_100 2}}`: 5 becomes 5.00e+0 |
| `toInt` | Reads a whole number from the start of the value. | `{{toInt field_100}}`: "22.7abc" becomes 22 |
| `toFloat` | Reads 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 |
| `digitGrouping` | Adds 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.

| Helper | Passes when | Example |
| --- | --- | --- |
| `is` | The 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}}` |
| `isnt` | The two values are not exactly the same, including their type, or the first is empty. | `{{#isnt field_101 "Closed"}} ... {{/isnt}}` |
| `gt`, `gte` | The first value is greater than, or greater than or equal to, the second. | `{{#gt field_100 8}} ... {{/gt}}` |
| `lt`, `lte` | The first value is less than, or less than or equal to, the second. | `{{#lte field_100 5}} ... {{/lte}}` |
| `or` | Either of two values has a value. | `{{#or field_100 field_101}} ... {{/or}}` |
| `and` | Both values have a value. | `{{#and field_100 field_101}} ... {{/and}}` |
| `orEquals` | Either of the first two values is exactly the third. | `{{#orEquals field_101 field_102 "Open"}} ... {{/orEquals}}` |
| `iss` | Not a block: returns the third value when the first two are exactly the same, otherwise the fourth. | `{{iss field_101 "Open" "Yes" "No"}}` |

> **Comparing numbers stored as text:** If both values are text, `gt`, `gte`, `lt` and `lte` compare them alphabetically, so "10" comes before "9". Turn a field into a number first: `{{#gt (toFloat field_100) 8}}`. For "not equal", `{{#unless (is field_101 "Closed")}}` treats text and numbers the same way `is` does.

## Dates

| Helper | What it does | Example |
| --- | --- | --- |
| `formatDate` | Formats a date with the directives below. Shows nothing when the date is empty. | `{{formatDate field_34 "%m/%d/%Y"}}` |
| `now` | The current date and time, optionally formatted. Supports most directives below, but not the `-`, `^` or `:` flags, `%G` or `%%`. | `{{now "%Y-%m-%d"}}` |
| `timeago` | How long ago the date was, such as "3 days ago" or "Just now". | `{{timeago field_34}}` |
| `age` | Whole 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"}}` |
| `dateDiff` | The 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`, `dateSub` | Adds 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`:

| Directive | Shows |
| --- | --- |
| `%Y`, `%y` | Year: 2026, 26 |
| `%m`, `%-m` | Month number: 03, 3 |
| `%B`, `%b` | Month name: March, Mar |
| `%d`, `%-d` | Day of the month: 07, 7 |
| `%j` | Day of the year: 066 |
| `%A`, `%a` | Weekday: Saturday, Sat |
| `%u`, `%w` | Weekday number: Monday is 1 (1 to 7), Sunday is 0 (0 to 6) |
| `%H`, `%I` | Hour, 24-hour (00 to 23) or 12-hour (01 to 12). Add `-` to drop the zero: `%-I` |
| `%M`, `%S`, `%L` | Minutes, seconds, milliseconds |
| `%p`, `%P` | AM or PM, am or pm |
| `%z`, `%:z` | Time zone offset: +0900, +09:00 |
| `%V`, `%G` | ISO week number and week-based year |
| `%s` | Seconds since 1 January 1970 |
| `%F`, `%D`, `%T`, `%R`, `%r` | Shortcuts for `%Y-%m-%d`, `%m/%d/%y`, `%H:%M:%S`, `%H:%M` and `%I:%M:%S %p` |
| `%^B`, `%^b`, `%^A`, `%^a` | Month or weekday name in capitals: MARCH, SAT |
| `%%` | A % sign |

## Other helpers

| Helper | What it does | Example |
| --- | --- | --- |
| `json` | Prints a value as formatted JSON. Use it while building to see what a field contains. | `{{json obj.field_44}}` |
| `assign` | Saves a value under a name; read it back with `@root`. | `{{assign "lastStatus" field_101}}` then `{{@root.lastStatus}}` |
| `br` | Adds one or more line breaks. | `{{br 2}}` |
| `log`, `debug` | Write 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](https://tadabase.com/docs/pages/custom-component#links-and-actions).

## 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](https://tadabase.com/docs/settings/custom-header-footer-code)). The helper is then available in every custom component in the app.

> **Warning:** Do not register helpers in the component's **JavaScript** tab: that code runs after the template has rendered, so the helper does not exist yet when the template needs it. Do not reuse the name of a built-in helper either: your helper replaces it everywhere in the app, including in Tadabase's own components.

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.
