Template literals (Template strings)

Syntax

Parameters

string text

The string text that will become part of the template literal. Almost all characters are allowed literally, including line breaks and other whitespace characters. However, invalid escape sequences will cause a syntax error, unless a tag function is used.

expression

An expression to be inserted in the current position, whose value is converted to a string or passed to tagFunction.

tagFunction

If specified, it will be called with the template strings array and substitution expressions, and the return value becomes the value of the template literal. See tagged templates.

Description

Template literals are enclosed by backtick (`) characters instead of double or single quotes.

Along with having normal strings, template literals can also contain other parts called placeholders, which are embedded expressions delimited by a dollar sign and curly braces: ${expression}. The strings and placeholders get passed to a function — either a default function, or a function you supply. The default function (when you don't supply your own) just performs string interpolation to do substitution of the placeholders and then concatenate the parts into a single string.

To supply a function of your own, precede the template literal with a function name; the result is called a tagged template. In that case, the template literal is passed to your tag function, where you can then perform whatever operations you want on the different parts of the template literal.

To escape a backtick in a template literal, put a backslash (\) before the backtick.

Dollar signs can be escaped as well to prevent interpolation.

Multi-line strings

Any newline characters inserted in the source are part of the template literal.

Using normal strings, you would have to use the following syntax in order to get multi-line strings:

Using template literals, you can do the same with this:

Like normal string literals, you can write a single-line string across multiple lines for source code readability, by escaping the newline with a backslash (\):

String interpolation

Without template literals, when you want to combine output from expressions with strings, you'd concatenate them using the addition operator +:

That can be hard to read – especially when you have multiple expressions.

With template literals, you can avoid the concatenation operator — and improve the readability of your code — by using placeholders of the form ${expression} to perform substitutions for embedded expressions:

Note that there's a mild difference between the two syntaxes. Template literals coerce their expressions directly to strings, while addition coerces its operands to primitives first. For more information, see the reference page for the + operator.

Nesting templates

In certain cases, nesting a template is the easiest (and perhaps more readable) way to have configurable strings. Within a backtick-delimited template, it is simple to allow inner backticks by using them inside an ${expression} placeholder within the template.

For example, without template literals, if you wanted to return a certain value based on a particular condition, you could do something like the following:

With a template literal but without nesting, you could do this:

With nesting of template literals, you can do this:

Tagged templates

A more advanced form of template literals are tagged templates.

Tags allow you to parse template literals with a function. The first argument of a tag function contains an array of string values. The remaining arguments are related to the expressions.

The tag function can then perform whatever operations on these arguments you wish, and return the manipulated string. (Alternatively, it can return something completely different, as described in one of the following examples.)

The name of the function used for the tag can be whatever you want.

The tag does not have to be a plain identifier. You can use any expression with precedence greater than 16, which includes property access, function call, new expression, or even another tagged template literal.

While technically permitted by the syntax, untagged template literals are strings and will throw a TypeError when chained.

The only exception is optional chaining, which will throw a syntax error.

Note that these two expressions are still parsable. This means they would not be subject to automatic semicolon insertion, which will only insert semicolons to fix code that's otherwise unparsable.

Tag functions don't even need to return a string!

The first argument received by the tag function is an array of strings. For any template literal, its length is equal to the number of substitutions (occurrences of ${…}) plus one, and is therefore always non-empty.

For any particular tagged template literal expression, the tag function will always be called with the exact same literal array, no matter how many times the literal is evaluated.

This allows the tag to cache the result based on the identity of its first argument. To further ensure the array value's stability, the first argument and its raw property are both frozen, so you can't mutate them in any way.

Raw strings

The special raw property, available on the first argument to the tag function, allows you to access the raw strings as they were entered, without processing escape sequences.

In addition, the String.raw() method exists to create raw strings just like the default template function and string concatenation would create.

String.raw functions like an "identity" tag if the literal doesn't contain any escape sequences. In case you want an actual identity tag that always works as if the literal is untagged, you can make a custom function that passes the "cooked" (i.e., escape sequences are processed) literal array to String.raw, pretending they are raw strings.

This is useful for many tools which give special treatment to literals tagged by a particular name.

Tagged templates and escape sequences

In normal template literals, the escape sequences in string literals are all allowed. Any other non-well-formed escape sequence is a syntax error. This includes:

• \ followed by any decimal digit other than 0, or \0 followed by a decimal digit; for example \9 and \07 (which is a deprecated syntax)
• \x followed by fewer than two hex digits (including none); for example \xz
• \u not followed by { and followed by fewer than four hex digits (including none); for example \uz
• \u{} enclosing an invalid Unicode code point — it contains a non-hex digit, or its value is greater than 10FFFF; for example \u{110000} and \u{z}

However, this is problematic for tagged templates, which, in addition to the "cooked" literal, also have access to the raw literals (escape sequences are preserved as-is).

Tagged templates enable the embedding of arbitrary string content, where escape sequences may follow a different syntax. Consider for an example where we embed LaTeX source text in JavaScript via String.raw. We want to still be able to use LaTeX macros that start with u or x without following JavaScript syntax restrictions. Therefore, the syntax restriction of well-formed escape sequences is removed from tagged templates. The example below uses MathJax to render LaTeX in one element:

However, illegal escape sequences must still be represented in the "cooked" representation. They will show up as undefined element in the "cooked" array:

Note that the escape-sequence restriction is only dropped from tagged templates, but not from untagged template literals:

Specifications

Browser compatibility

See also

• Numbers and strings guide
• String
• String.raw()
• Lexical grammar
• ES6 in Depth: Template strings on hacks.mozilla.org (2015)