Lodash template Custom Interpolation Delimiters

This article provides an overview of how to structurally override the standard interpolation delimiters in the Lodash _.template utility. By default, Lodash uses ERB-style tags for value insertion, but developers can redefine these patterns across templates or globally through custom regular expressions. Below, you will learn the exact regex properties required to override the default interpolation syntax and how regex capture groups control variable extraction.

Default Delimiters in Lodash

By default, the Lodash _.template function relies on ERB-style template delimiters evaluated in this order:

• Escape (escape): <%- expression %> (HTML-escapes the rendered string)
• Interpolate (interpolate): <%= expression %> (evaluates and renders unescaped string values)
• Evaluate (evaluate): <% expression %> (executes raw JavaScript control flow statements)

The internal regular expression mapped to standard interpolation is:

/<%=\s*([\s\S]+?)\s*%>/g

Overriding Interpolation via interpolate

To override the standard <%= %> interpolation mapping, you must provide a regular expression with a single capturing group containing the expression to be evaluated. This override can be applied globally using _.templateSettings or locally via the options argument of _.template.

Global Configuration

Modifying _.templateSettings.interpolate changes the syntax across all subsequent templates:

import _ from 'lodash';

// Structurally override to use Mustache-style syntax: {{ expression }}
_.templateSettings.interpolate = /{{([\s\S]+?)}}/g;

const compiled = _.template('Hello {{ name }}!');
compiled({ name: 'World' }); // Returns: "Hello World!"

Instance-Level Configuration

Passing an options object with an interpolate property overrides the mapping strictly for that compilation instance:

import _ from 'lodash';

const compiled = _.template('Hello ${ name }!', {
  interpolate: /\${([^\\}]*(?:\\.[^\\}]*)*)}/g
});

compiled({ name: 'World' }); // Returns: "Hello World!"

Regex Structure and Delimiter Precedence

When defining custom regex delimiters, two structural rules dictate how Lodash compiles the template:

1. Capturing Group Requirement: The regular expression assigned to interpolate must contain a capture group (parentheses ()). Lodash extracts the inner source code from the first matched capture group and inserts it directly into the generated template function body.

2. Delimiter Precedence Order: Lodash compiles delimiters by combining escape, interpolate, and evaluate regular expressions into a single composite pattern:

regex = RegExp(
  (escape.source || noMatch) + '|' +
  (interpolate.source || noMatch) + '|' +
  (evaluate.source || noMatch) + '|$',
  'g'
);

Because of this evaluation order, if your custom interpolate regular expression overlaps structurally with the escape regular expression, the escape pattern takes precedence. If you want to replace default interpolation without unintended collisions, you must ensure your custom interpolate regular expression is distinct from _.templateSettings.escape and _.templateSettings.evaluate, or explicitly redefine those properties to avoid pattern conflict.