String.raw()

The only built-in template tag. It is not a normal function call — it is written as a prefix on a backtick literal, which is why it looks unlike everything else in the String API.

String static methodES2015
Common call
String.raw`C:\Users\Alex`
Returns
the text with backslashes intact
Replaces
doubling every backslash by hand
Watch out
it cannot help a string that is already built
String.raw`template`
→ string

Parameters

NameTypeRequiredDescription
stringsobjectyesThe template strings object, supplied automatically when used as a tag. Its raw property holds the uncooked text.
...valuesanyno (none)The interpolated ${} expressions, also supplied automatically. These ARE evaluated and inserted normally.

Return value

string — The template literal with its escape sequences left UNPROCESSED — a backslash-n stays two characters instead of becoming a newline. Interpolated ${} values are still substituted normally.

Examples

1. Backslash-n stays literal
String.raw`a\nb`
Returns
'a\\nb' // two characters, not a newline
2. A normal template
`a\nb`
Returns
'a\nb' // an actual newline
3. Its length
String.raw`a\nb`.length
Returns
4
4. A Windows path
String.raw`C:\new\table`
Returns
'C:\\new\\table'
5. Interpolation still works
String.raw`a${1 + 1}b`
Returns
'a2b'
6. Called as a function
String.raw({raw: ['a', 'b']}, 1)
Returns
'a1b'

Pitfalls

1. It cannot fix a string you already have
The escapes are processed by the parser when the literal is read. String.raw works only because a tag sees the text BEFORE that happens — applying it to a variable is meaningless, since the damage is already done.
Too late
const p = "C:\new";
String.raw(p)
the \n is already a newline
Tag the literal
const p = String.raw`C:\new`;
'C:\\new'
2. It is a tag, not an ordinary call
String.raw(x) with parentheses does not do what you want — it expects a template strings object with a raw property. Written with parentheses and a plain string it returns undefined or throws, depending on what you passed.
Parentheses
String.raw("a\nb")
TypeError: Cannot read properties of undefined
Backticks
String.raw`a\nb`
'a\\nb'
3. A trailing backslash is still a syntax error
The tag changes how escapes are interpreted, not how the literal is terminated. A backslash immediately before the closing backtick escapes it, so the literal never closes.
Will not parse
String.raw`C:\`
SyntaxError: Unterminated template literal
Concatenate
String.raw`C:` + '\\'
'C:\\'
4. Not a substitute for proper escaping
It makes regex sources and paths readable; it does nothing for safety. Interpolated values are inserted verbatim, so String.raw around user input in a regex or a query is exactly as dangerous as a plain template literal.
Still unescaped
new RegExp(String.raw`${userInput}`)
user metacharacters are live
Escape the input
new RegExp(escapeRegExp(userInput))
literal

When to use

Use it
  • Windows file paths written as literals
  • Regular expression sources built as strings
  • LaTeX, or anything else dense in backslashes
  • Generating code or documentation that must show escape sequences
Reach for something else
  • The string already exists in a variable → too late, escape at the source
  • A regex you can write as a literal → /pattern/ needs no escaping of backslashes
  • Forward-slash paths → no backslashes, no need
  • Interpolating untrusted values → escape them explicitly

Notes

Complexity
O(n) in the length of the template
Return
A new string
CPython impl
V8: Builtins-string-raw
Memory
Allocates the result string
Thread-safe
Single-threaded

FAQ

Because String.raw only does anything when it prefixes a template literal in source code. Any string typed into an input box has already had its escapes processed — or never had any — so a demo could only show the tag doing nothing, which would misrepresent it. The examples above are run against a real runtime instead.

History

ES2015
String.raw added with template literals as the one built-in tag function.