Skip to main content

restrict-template-expressions

Enforce template literal expressions to be of string type.

✅

Extending "plugin:@typescript-eslint/recommended-type-checked" in an ESLint configuration enables this rule.

💭

This rule requires type information to run.

JavaScript automatically converts an object to a string in a string context, such as when concatenating it with a string using + or embedding it in a template literal using ${}. The default toString() method of objects returns "[object Object]", which is often not what was intended. This rule reports on values used in a template literal string that aren't strings, numbers, or BigInts, optionally allowing other data types that provide useful stringification results.

note

This rule intentionally does not allow objects with a custom toString() method to be used in template literals, because the stringification result may not be user-friendly.

For example, arrays have a custom toString() method, which only calls join() internally, which joins the array elements with commas. This means that (1) array elements are not necessarily stringified to useful results (2) the commas don't have spaces after them, making the result not user-friendly. The best way to format arrays is to use Intl.ListFormat, which even supports adding the "and" conjunction where necessary. You must explicitly call object.toString() if you want to use this object in a template literal. The no-base-to-string rule can be used to guard this case against producing "[object Object]" by accident.

.eslintrc.cjs
module.exports = {
  "rules": {
    "@typescript-eslint/restrict-template-expressions": "error"
  }
};
Try this rule in the playground ↗

Examples​

const arg1 = [1, 2];
const msg1 = `arg1 = ${arg1}`;

const arg2 = { name: 'Foo' };
const msg2 = `arg2 = ${arg2 || null}`;
Open in Playground

Options​

This rule accepts the following options

type Options = [
  {
    /** Whether to allow `any` typed values in template expressions. */
    allowAny?: boolean;
    /** Whether to allow `boolean` typed values in template expressions. */
    allowBoolean?: boolean;
    /** Whether to allow `never` typed values in template expressions. */
    allowNever?: boolean;
    /** Whether to allow `nullish` typed values in template expressions. */
    allowNullish?: boolean;
    /** Whether to allow `number` typed values in template expressions. */
    allowNumber?: boolean;
    /** Whether to allow `regexp` typed values in template expressions. */
    allowRegExp?: boolean;
  },
];

const defaultOptions: Options = [
  {
    allowAny: true,
    allowBoolean: true,
    allowNullish: true,
    allowNumber: true,
    allowRegExp: true,
  },
];

allowNumber​

Examples of additional correct code for this rule with { allowNumber: true }:

const arg = 123;
const msg1 = `arg = ${arg}`;
const msg2 = `arg = ${arg || 'zero'}`;
Open in Playground

This option controls both numbers and BigInts.

allowBoolean​

Examples of additional correct code for this rule with { allowBoolean: true }:

const arg = true;
const msg1 = `arg = ${arg}`;
const msg2 = `arg = ${arg || 'not truthy'}`;
Open in Playground

allowAny​

Examples of additional correct code for this rule with { allowAny: true }:

const user = JSON.parse('{ "name": "foo" }');
const msg1 = `arg = ${user.name}`;
const msg2 = `arg = ${user.name || 'the user with no name'}`;
Open in Playground

allowNullish​

Examples of additional correct code for this rule with { allowNullish: true }:

const arg = condition ? 'ok' : null;
const msg1 = `arg = ${arg}`;
Open in Playground

allowRegExp​

Examples of additional correct code for this rule with { allowRegExp: true }:

const arg = new RegExp('foo');
const msg1 = `arg = ${arg}`;
Open in Playground
const arg = /foo/;
const msg1 = `arg = ${arg}`;
Open in Playground

allowNever​

Examples of additional correct code for this rule with { allowNever: true }:

const arg = 'something';
const msg1 = typeof arg === 'string' ? arg : `arg = ${arg}`;
Open in Playground

Resources​