Lodash _.templateSettings.imports

Beginner
5 min read
Updated: Nov 2026
5 examples
Template

Definition

An object of free variables imported into every _.template() compile. By default it includes _ (Lodash) so helpers work inside tags without being passed as data. Part of Lodash Properties (stable in 4.x — not deprecated). Warning: never compile untrusted template strings; import only trusted helpers. Lodash plans to remove _.template in v5.

Set the property globally, or override it per call with options passed to _.template().

Syntax

Use _.templateSettings.imports. Start with this line.

Lodash
_.templateSettings.imports
CallWhat it does
_.templateSettings.importsPrimary setting.
_.templateSettings.imports = /.../gAssign a custom RegExp or value before compiling.

Prefer the full Lodash build when using _.template() and _.templateSettings.

Library declarations
Lodash
_.templateSettings.imports

Parameters

ParameterDescription
_.templateSettings.importsOptional. (Object) Default free variables for compiles
imports._Optional. (Function/Object) Lodash reference in templates
options.importsOptional. (Object) Per-compile free variables
Data objectOptional. (Object) Passed at render time — separate from imports

Return Value

Return ValueDescription
*Object of free variables

Lodash Examples

Example 1 — Default _ Import

Full builds expose Lodash as _ inside templates automatically.

Lodash
var compiled = _.template(
  '<% _.forEach(users, function(user) { %>' +
    '<li><%- user %></li>' +
  '<% }); %>'
);
compiled({ 'users': ['fred', 'barney'] });
// → '<li>fred</li><li>barney</li>'
Try It Yourself

How It Works

  1. Import. _ comes from templateSettings.imports._.
  2. Evaluate. _.forEach runs inside <% %> tags.
  3. Data. users is passed at render time.
  4. Escape. Each name prints with <%- user %>.

Example 2 — Official: Import as jq

Pass a custom library under any name via options.imports.

Lodash
// Official shape (needs jQuery on the page):
// var text = '<% jq.each(users, function(user) { %><li><%- user %></li><% }); %>';
// var compiled = _.template(text, { 'imports': { 'jq': jQuery } });

// Same idea with a tiny each helper:
var jq = {
  each: function (arr, fn) {
    for (var i = 0; i < arr.length; i++) fn(arr[i]);
  }
};
var text = '<% jq.each(users, function(user) { %><li><%- user %></li><% }); %>';
var compiled = _.template(text, { 'imports': { 'jq': jq } });
compiled({ 'users': ['fred', 'barney'] });
// → '<li>fred</li><li>barney</li>'
Try It Yourself

How It Works

  1. Helper. jq is provided only through imports.
  2. Compile. { imports: { jq: jq } } wires the free variable.
  3. Call. The template uses jq.each, not _.forEach.
  4. Data. users still comes from the render argument.

Example 3 — Custom Formatter Helper

Import a small function and call it from an escape/interpolate tag.

Lodash
function shout(s) {
  return String(s).toUpperCase() + '!';
}
var compiled = _.template(
  'Hi <%- shout(name) %>',
  { imports: { shout: shout } }
);
compiled({ name: 'ada' });
// → 'Hi ADA!'
Try It Yourself

How It Works

  1. Define. shout is a normal JavaScript function.
  2. Import. It becomes a free name via options.imports.
  3. Call. The escape tag runs shout(name), then HTML-escapes the result.
  4. Data. Only name is passed at render time.

Example 4 — Import Inside Interpolate

Free variables work in interpolate tags too.

Lodash
var compiled = _.template(
  'max=<%= _.max(scores) %>'
);
compiled({ scores: [3, 9, 4] });
// → 'max=9'
Try It Yourself

How It Works

  1. Import. Default _ is available in the expression.
  2. Interpolate. <%= _.max(scores) %> inserts the number.
  3. Data. scores is the render-time array.
  4. Note. Interpolate is not HTML-escaped — fine for numbers here.

Example 5 — Inspect Default Import Keys

See what the settings object exposes before you customize it.

Lodash
_.keys(_.templateSettings.imports);
// → ['_']   (typical full build)

typeof _.templateSettings.imports._;
// → 'function'
Try It Yourself

How It Works

  1. Read. templateSettings.imports is a plain object.
  2. Keys. Full builds usually start with just _.
  3. Value. imports._ is the Lodash function/object.
  4. Extend. Add more keys carefully — they become free variables globally.

Browser & Runtime Support

_.templateSettings.imports ships with Lodash full builds (stable in 4.x). It configures _.template, which runs anywhere Lodash runs — modern browsers (CDN or bundle) and Node.js / Bun / Deno with npm install lodash.

✓ Stable · Lodash 4.x · Warning: template security

_.templateSettings.imports

Available on the [email protected] namespace. Works in evergreen browsers and current Node LTS when Lodash is installed. Treat _.template as legacy for untrusted template source.

100% With Lodash 4.x
Google Chrome Supported · Desktop & Mobile
Full support
Mozilla Firefox Supported · Desktop & Mobile
Full support
Apple Safari Supported · macOS & iOS
Full support
Microsoft Edge Supported · Chromium
Full support
Internet Explorer No native support · Use a polyfill
Polyfill
Opera Supported · Modern versions
Full support
Samsung Internet Supported · Android
Full support
Bun Supported · JavaScript runtime
Supported
Deno Supported · JavaScript runtime
Supported
Node.js Supported · Server runtime
Supported
Android WebView Supported · Modern WebView
Full support
.imports Lodash 4.x

Bottom line: Use imports for trusted free variables like _ and formatters. Prefer per-call { imports } for one-offs. Never compile untrusted template strings.

Frequently Asked Questions

It is an object of names and values imported into compiled templates as free variables. By default it includes _ so you can call Lodash helpers inside template tags.
imports._ is the property that holds the Lodash reference. It is why <\x25 _.forEach(...) \x25> works in templates without passing _ in the data object.
Yes. Assign keys on _.templateSettings.imports, or pass { imports: { helper: fn } } to _.template() for a one-off compile.
In evaluate, escape, and interpolate tags — anywhere the compiled template runs JavaScript expressions.
Options.imports are merged for that compile. Pass the helpers you need; keep _ available if your template uses Lodash methods.
No. Compiling untrusted templates can execute code. Import only trusted helpers. Lodash plans to remove _.template in v5.

Next: _.templateSettings.interpolate

Configure the RegExp for raw value-insertion tags.

.interpolate tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

10 people found this page helpful