Using Handlebars Custom Helpers to Keep Presentation Logic Out of Templates

Why use a custom helper?

Handlebars keeps templates declarative by separating markup from logic. When you need to format values, conditionally render blocks, or reuse small presentation snippets across views, a custom helper lets you encapsulate that logic in JavaScript while keeping the template clean.

Registering and using a helper

First, install or require the Handlebars library in a Node.js environment (no special permissions needed). Register a helper with Handlebars.registerHelper. The helper receives the current context as its first argument and must return a string or a SafeString if you intend to output raw HTML.

const Handlebars = require('handlebars');

// Register a simple helper that upper‑cases a string
Handlebars.registerHelper('upper', function(str) {
  return String(str).toUpperCase();
});

// Template that uses the helper
const source = 'Hello, {{upper name}}!';
const template = Handlebars.compile(source);

// Render with a data context
const context = { name: 'world' };
const result = template(context);
console.log(result); // → Hello, WORLD!

The helper is invoked during rendering; it receives the value of name, converts it to uppercase, and returns the string. Because the return value is a plain string, Handlebars escapes it automatically, preventing XSS.

If you need to output trusted HTML, return a SafeString:

Handlebars.registerHelper('highlight', function(text) {
  const escaped = Handlebars.Utils.escapeExpression(text);
  return new Handlebars.SafeString('' + escaped + '');
});

Using the helper as {{highlight description}} will render the description wrapped in tags without double‑escaping.

Limits and common mistakes

• No async support – helpers run synchronously. If you need data from a database or API, fetch it before rendering and pass it in the context.
• Version sensitivity – the exact signature of options and SafeString handling can differ between Handlebars 4.x and 5.x. Check the release notes for your version.
• Mutating context – changing the input object inside a helper can cause side effects that are hard to trace. Treat arguments as read‑only.
• Global state – relying on variables outside the helper makes it difficult to unit test and leads to unpredictable output when the same template is rendered in different contexts.
• Business logic in helpers – helpers are for presentation only (formatting, looping, conditional blocks). Put data transformation, validation, or fetching logic in the layer that prepares the context.
• Naming collisions – avoid naming a helper the same as a built‑in block helper (if, each, with) unless you intentionally want to override it, as this can break existing templates.

Practical verification: render a template with missing data (e.g., {}) and confirm the helper returns an empty string (or undefined, which Handlebars treats as empty). Then render with a string containing HTML and compare output when the helper returns a plain string versus a SafeString to see the escaping difference.