JavaScript Tagged Template Literals

Tagged templates process template literals with custom functions. Here's how to use them.

Basic Syntax#

// Tag function receives strings and values separately
function tag(strings, ...values) {
  console.log('Strings:', strings);
  console.log('Values:', values);
  return 'processed';
}

const name = 'Alice';
const age = 30;

const result = tag`Hello, ${name}! You are ${age} years old.`;
// Strings: ['Hello, ', '! You are ', ' years old.']
// Values: ['Alice', 30]
// result: 'processed'

// strings.raw contains unprocessed strings
function showRaw(strings) {
  console.log(strings.raw[0]); // Shows \n literally
}

showRaw`Line1\nLine2`;

Building Custom Tags#

// Simple interpolation tag
function simple(strings, ...values) {
  let result = '';
  strings.forEach((str, i) => {
    result += str + (values[i] ?? '');
  });
  return result;
}

// Using reduce
function interpolate(strings, ...values) {
  return strings.reduce((result, str, i) => {
    return result + str + (values[i] ?? '');
  }, '');
}

// Same as untagged template literal
const name = 'Bob';
console.log(interpolate`Hello, ${name}!`);
// 'Hello, Bob!'

HTML Escaping#

// Escape HTML to prevent XSS
function escapeHtml(str) {
  return str
    .replace(/&/g, '&amp;')
    .replace(/</g, '&lt;')
    .replace(/>/g, '&gt;')
    .replace(/"/g, '&quot;')
    .replace(/'/g, '&#39;');
}

function html(strings, ...values) {
  return strings.reduce((result, str, i) => {
    const value = values[i];
    const escaped = value !== undefined
      ? escapeHtml(String(value))
      : '';
    return result + str + escaped;
  }, '');
}

// Usage
const userInput = '<script>alert("xss")</script>';
const safe = html`<div>${userInput}</div>`;
// '<div>&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;</div>'

// Allow raw HTML when needed
function rawHtml(value) {
  return { __html: value };
}

function html(strings, ...values) {
  return strings.reduce((result, str, i) => {
    const value = values[i];
    if (value?.__html) {
      return result + str + value.__html;
    }
    return result + str + (value !== undefined ? escapeHtml(String(value)) : '');
  }, '');
}

const trusted = rawHtml('<strong>Bold</strong>');
const output = html`<div>${trusted}</div>`;
// '<div><strong>Bold</strong></div>'

SQL Query Builder#

// Parameterized SQL queries
function sql(strings, ...values) {
  const params = [];
  const query = strings.reduce((result, str, i) => {
    if (i < values.length) {
      params.push(values[i]);
      return result + str + `$${params.length}`;
    }
    return result + str;
  }, '');

  return { query, params };
}

// Usage
const userId = 123;
const status = 'active';

const { query, params } = sql`
  SELECT * FROM users
  WHERE id = ${userId}
  AND status = ${status}
`;

// query: 'SELECT * FROM users WHERE id = $1 AND status = $2'
// params: [123, 'active']

// Execute safely
await db.query(query, params);

// With identifiers
function sqlWithIdentifiers(strings, ...values) {
  const params = [];
  const query = strings.reduce((result, str, i) => {
    const value = values[i];
    if (value === undefined) return result + str;

    if (value.__identifier) {
      // Escape identifier
      return result + str + `"${value.name.replace(/"/g, '""')}"`;
    }

    params.push(value);
    return result + str + `$${params.length}`;
  }, '');

  return { query, params };
}

function identifier(name) {
  return { __identifier: true, name };
}

const table = identifier('users');
const column = identifier('email');

CSS-in-JS#

// Styled components pattern
function css(strings, ...values) {
  return strings.reduce((result, str, i) => {
    const value = values[i];
    if (typeof value === 'function') {
      // Defer function evaluation
      return result + str + '__PLACEHOLDER__';
    }
    return result + str + (value ?? '');
  }, '');
}

// With units
function px(value) {
  return `${value}px`;
}

function cssWithUnits(strings, ...values) {
  return strings.reduce((result, str, i) => {
    let value = values[i];
    if (typeof value === 'number') {
      value = `${value}px`;
    }
    return result + str + (value ?? '');
  }, '');
}

const width = 200;
const styles = cssWithUnits`
  width: ${width};
  padding: ${16};
  margin: ${8};
`;
// 'width: 200px; padding: 16px; margin: 8px;'

Logging with Context#

// Debug logging with file/line info
function debug(strings, ...values) {
  const message = strings.reduce((result, str, i) => {
    const value = values[i];
    const formatted = typeof value === 'object'
      ? JSON.stringify(value, null, 2)
      : value;
    return result + str + (formatted ?? '');
  }, '');

  const stack = new Error().stack;
  const caller = stack?.split('\n')[2]?.trim();

  console.log(`[DEBUG] ${message}`);
  console.log(`        at ${caller}`);
}

const user = { name: 'Alice', id: 1 };
debug`User logged in: ${user}`;

// Colored logging
const colors = {
  reset: '\x1b[0m',
  red: '\x1b[31m',
  green: '\x1b[32m',
  yellow: '\x1b[33m',
  blue: '\x1b[34m',
};

function colorize(color) {
  return (strings, ...values) => {
    const message = strings.reduce((r, s, i) =>
      r + s + (values[i] ?? ''), '');
    return `${colors[color]}${message}${colors.reset}`;
  };
}

const red = colorize('red');
const green = colorize('green');

console.log(red`Error: Something went wrong`);
console.log(green`Success: Operation completed`);

i18n Translation#

// Translation tag
const translations = {
  'en': {
    'Hello, {0}!': 'Hello, {0}!',
    'You have {0} messages': 'You have {0} messages',
  },
  'es': {
    'Hello, {0}!': '¡Hola, {0}!',
    'You have {0} messages': 'Tienes {0} mensajes',
  },
};

let currentLocale = 'en';

function t(strings, ...values) {
  const key = strings.reduce((result, str, i) => {
    return result + str + (i < values.length ? `{${i}}` : '');
  }, '');

  let translated = translations[currentLocale]?.[key] ?? key;

  values.forEach((value, i) => {
    translated = translated.replace(`{${i}}`, String(value));
  });

  return translated;
}

// Usage
const name = 'Alice';
const count = 5;

currentLocale = 'en';
console.log(t`Hello, ${name}!`); // 'Hello, Alice!'

currentLocale = 'es';
console.log(t`Hello, ${name}!`); // '¡Hola, Alice!'
console.log(t`You have ${count} messages`); // 'Tienes 5 mensajes'

GraphQL Queries#

// GraphQL query builder
function gql(strings, ...values) {
  const query = strings.reduce((result, str, i) => {
    return result + str + (values[i] ?? '');
  }, '');

  // Parse and validate in development
  if (process.env.NODE_ENV === 'development') {
    validateGraphQL(query);
  }

  return { query, __graphql: true };
}

const UserFragment = gql`
  fragment UserFields on User {
    id
    name
    email
  }
`;

const GetUser = gql`
  ${UserFragment}

  query GetUser($id: ID!) {
    user(id: $id) {
      ...UserFields
    }
  }
`;

// Usage with client
const result = await graphqlClient.query(GetUser, { id: '123' });

Regular Expressions#

// Verbose regex with comments
function regex(strings, ...values) {
  const pattern = strings.reduce((result, str, i) => {
    // Remove comments and whitespace
    const cleaned = str
      .replace(/#.*/g, '')
      .replace(/\s+/g, '');
    return result + cleaned + (values[i] ?? '');
  }, '');

  return new RegExp(pattern);
}

const emailRegex = regex`
  ^                 # Start
  [^\s@]+           # Username (no spaces or @)
  @                 # @ symbol
  [^\s@]+           # Domain name
  \.                # Dot
  [^\s@]+           # TLD
  $                 # End
`;

// With flags
function regexWithFlags(flags) {
  return (strings, ...values) => {
    const pattern = strings.reduce((result, str, i) => {
      const cleaned = str.replace(/#.*/g, '').replace(/\s+/g, '');
      return result + cleaned + (values[i] ?? '');
    }, '');
    return new RegExp(pattern, flags);
  };
}

const caseInsensitive = regexWithFlags('i');

Best Practices#

Design:
✓ Return useful values
✓ Handle edge cases
✓ Document expected usage
✓ Consider raw strings

Security:
✓ Escape user input
✓ Use parameterized queries
✓ Validate interpolated values
✓ Mark trusted content explicitly

Performance:
✓ Cache expensive operations
✓ Avoid unnecessary processing
✓ Consider lazy evaluation
✓ Profile complex tags

Avoid:
✗ Mutating input arrays
✗ Side effects in tags
✗ Complex nested tags
✗ Ignoring raw strings

Tagged template literals enable powerful custom string processing for HTML escaping, SQL queries, CSS-in-JS, translations, and domain-specific languages. The tag function receives strings and values separately, allowing safe interpolation and custom transformations.