---
title: Use custom result template helpers
slug: '391'
canonical_url: https://docs.coveo.com/en/391/
collection: javascript-search-framework
source_format: adoc
---
# Use custom result template helpers
This article explains how to create your own custom [result template helpers](https://docs.coveo.com/en/413#result-template-helpers) if the [prebuilt helpers](https://coveo.github.io/search-ui/interfaces/icorehelpers.html) that are available with the [JavaScript Search Framework](https://docs.coveo.com/en/187/) don't meet your needs.

## Creating custom template helpers

Before you can use a custom result template helper, you must register it in the same `script` tag in which you initialize your [search interface](https://docs.coveo.com/en/2741/):

```javascript
document.addEventListener("DOMContentLoaded", () => {
	// ...
	document.addEventListener("afterInitialization", () => {
		Coveo.TemplateHelpers
			 .registerTemplateHelper("<NAME>", (value, options) => {
				// ...Helper function implementation...
		});
	});
	// ...
	Coveo.init(document.body);
})
```

where `<NAME>` is a unique name for your custom helper.

When the helper function is invoked, the `value` parameter is set to the field value to process.
If specified, the `options` argument is a key-value store of customization options to pass to the helper.

> **Note**
>
> The function must return a string or template string.

Once your helper is registered, you can call it using an [HTML template](https://docs.coveo.com/en/413#using-the-html-engine-recommended) or an [Underscore template](https://docs.coveo.com/en/413#using-the-underscore-engine).

In the following HTML template example, the template helper is invoked with the current value of `<FIELD_NAME>` as a first argument, and the `data-helper-options` object as a second argument:

```xml
<div class="CoveoFieldValue"
	data-helper="<NAME>"
	data-field="<FIELD_NAME>"
	data-helper-options="{ 'OptionA': 'ValueA', 'OptionB': 'ValueB' }">
</div>
```

> **Note**
>
> If you configure a helper to return an HTML string, you must set the [`htmlValue`](https://coveo.github.io/search-ui/components/fieldvalue.html#options.htmlvalue) option of the [`FieldValue`](https://coveo.github.io/search-ui/components/fieldvalue.html) component to `true` (that is, `data-html-value="true"`).
> Otherwise, the value returned by the helper renders as text rather than an HTML string.

In an Underscore template, you would use a line of code like the following to invoke your helper:

```erb
<%= <NAME>(raw.<FIELD_NAME>, {optionA: 'Value A', optionB: 'Value B'}) %>
```

## Sample use cases

### Example 1

You want to output a qualitative string value based on the `@temperature` field (expressed in °F).

Register the helper:

```javascript
Coveo.TemplateHelpers.registerTemplateHelper("temperatureDisplay", (temperature) => {
	if (temperature < 32) return "freezing";
	if (temperature < 64) return "cold";
	if (temperature < 77) return "warm";
	if (temperature < 86) return "hot";
	else return "scorching";
})
```

Call your helper:

```xml
<div class="CoveoFieldValue"
	data-field="@temperature"
	data-helper="temperatureDisplay">
</div>
```

### Example 2

You want to include a phone number in result list items.
When end users who are using mobile devices tap on this number, their phone application opens and dials the number.

Register the helper:

```javascript
Coveo.TemplateHelpers.registerTemplateHelper("phoneNumber", function(number) {
	return `<a href="tel:${number}">${number}</a>`
})
```

Call your helper:

```xml
<div class="CoveoFieldValue"
	data-field="@mobilenumber"
	data-helper="phoneNumber"
	data-html-value="true">
</div>
```

### Example 3

You want to output a `<span>` element with a certain width, height, and border radius (for example, `25px` width/height and a `50%` border-radius to output a circle), and use the `@color` value as the `background-color`.

Register the helper:

```javascript
Coveo.TemplateHelpers.registerTemplateHelper("textStylist", (value, options) => {
		let style;
		if (options.shape === 'circle') {
		style = "border-radius:50%;";
		}

		switch(options.size) {
			case "small":
			style += "width:15px;height:15px;";
				break;
			case "medium":
			style += "width:25px;height:25px;";
				break;
			case "large":
			style += "width:35px;height:35px;";
				break;
			default:
				break;
		}

		return `<span style="${style} background-color:'${value}'"></span>`
});
```

Call your helper:

```html
<div class="CoveoFieldValue"
	data-field="@color"
	data-helper="textStylist"
	data-helper-options="{size: 'medium', shape: 'circle'}"
	data-html-value="true">
</div>
```