JS: Tagged Template String

By Xah Lee. Date: . Last updated: .

New in ES2015.

First, see JS: Template String.

There's a special notation to call a function, called tagged template string. The syntax is:

function_name`…`

When function is called this way, the function is fed one or more arguments based on the template string the `…`.

The first argument is a array, and each elements are literal segment of the template string. That is, the template string is split into parts, separated by the pattern ${…}.

For example, `aa${3+4}bb` is separated into 2 parts, "aa" and "bb". The function will get ["aa","bb"] as first argument.

The rest arguments, are the embeded expressions of the template string. For example, in f`aa${33}bb${44}cc`, the function will get "33" as second argument, and "44" as 3rd argument. (they are evaluated.)

In the following example, we show what happens to the first argument.

// tagged template function calling.
// first arg is array, of literal parts of the template string

function f(x) { return x; };

console.log(
    f`a`
); // ['a']

console.log(
    f`a ${5} b`
); // ['a ', ' b']

console.log(
    f`a ${5}`
); // ['a ', '']


console.log(
    f`${5} b`
); // ['', ' b']

console.log(
    f`${5}`
); // ['', '']

In the following example, we show all received arguments.

// tagged template function call
// show args received

function f() { return arguments; };

console.log(
    f`a`
);
// prints
// { '0': [ 'a' ] }
// Because there's no embedded expression

console.log(
    f`a ${3}`
);
// prints
// { '0': [ 'a ', '' ], '1': 3 }

console.log(
    f`a ${3} b ${6}`
);
// prints
// { '0': [ 'a ', ' b ', '' ], '1': 3, '2': 6 }

console.log(
    f`a ${2+3} b`
);
// prints
// { '0': [ 'a ', ' b' ], '1': 5 }
// expression is evaluated

Recall that arguments is a builtin array-like object that contains all received arguments.

[see JS: Function's “arguments” Object]

[see JS: Array-Like Object]

Purpose of Tagged Template

Tagged template let you modify template in a flexible way.

instead of just printing a template string output = `…` you can modify it by adding a function output = f`…`.

Reconstruct Order

The original template string can be reconstructed by using the parts's indexes.

The literal parts can be accessed by arguments[0][i]. The first one is arguments[0][0]. The last one is arguments[0][arguments.length - 1].

The expression parts can be accessed by arguments[i]. The first one is arguments[1]. The last one is arguments[arguments.length - 1].

For each expression part arguments[i], there's always a literal string part arguments[0][i] following it (may be empty string).

// reconstruct template string
// showing order relation of literal parts and placeholder parts

function ff () {

    var result = arguments[0][0]; // first literal string part

    // go thru by expr index, starting from 1.
    for (var i = 1; i < arguments.length; i++) {
        result += arguments[i] + arguments[0][i];
    };

    return result;
};

console.log(
    `a ${1} b ${2} c ${3}`
); // a 1 b 2 c 3

console.log(
    ff`a ${1} b ${2} c ${3}`
); // a 1 b 2 c 3

console.log(
    `a ${1} b ${2} c ${3} d`
); // a 1 b 2 c 3 d

console.log(
    ff`a ${1} b ${2} c ${3} d`
); // a 1 b 2 c 3 d


// test degenerate cases

console.log(
    `a` === ff`a`
); // true

console.log(
    `${1}` === ff`${1}`
); // true

console.log(
    `a ${1}` === ff`a ${1}`
); // true

console.log(
    `${1} b` === ff`${1} b`
); // true

console.log(
    `a ${1}${2}` === ff`a ${1}${2}`
); // true

Browser Support

Works in Google Chrome and Firefox.

Reference

ECMAScript 2015 §ECMAScript Language: Expressions#sec-tagged-templates

JS String

  1. String Overview
  2. Template String
  3. Char, Code Unit, Code Point
  4. String Escape Sequence
  5. Unicode Escape Sequence
  6. String to Number
  7. Encode URL, Escape String
  8. Format Number
  9. Source Code Encoding
  10. Allowed Characters in Identifier
  11. String Object
  12. String.prototype
Liket it? Put $5 at patreon.

Or, Buy JavaScript in Depth

If you have a question, put $5 at patreon and message me.

Web Dev Tutorials

  1. HTML
  2. Visual CSS
  3. JS in Depth
  4. JS Reference
  5. DOM
  6. SVG
  7. Web Dev Blog