String.raw()
Returns a template literal's text with backslash escape sequences left uninterpreted.
String.raw(strings)
String.raw(strings, sub1)
String.raw(strings, sub1, sub2)
String.raw(strings, sub1, sub2, /* …, */ subN)
String.raw`templateString`- Added in JavaScript ES2015
Parameters
| Parameter | Type | Description |
|---|---|---|
$strings | { raw: ArrayLike<string> } | A well-formed template literal array object — an object with a raw property holding an array-like of strings. Supplied automatically when used as a template tag. |
$sub1, …, subNoptional | any | The substitution values interpolated between the raw string segments. Supplied automatically from the ${...} expressions when used as a template tag. |
Return value
stringThe raw string form of the given template literal, with substitutions interpolated but escape sequences left as literal characters.
Errors
Throws a TypeError if the first argument has no raw property, or if that property is undefined or null.
String.raw is a built-in template tag. Written as String.raw`...` it returns the literal's source text: ${...} substitutions are still evaluated and inserted, but escape sequences such as \n, \t and \u0041 stay as the two characters you typed rather than being interpreted.
When to reach for it
Two situations dominate. First, Windows paths and any other backslash-heavy text — String.raw`C:\Users\dev` beats doubling every backslash by hand. Second, building a RegExp from a string, where the pattern's backslashes would otherwise need escaping twice: new RegExp(String.raw`\d+\.\d+`) instead of new RegExp("\\d+\\.\\d+").
What trips people up
It is not a general escape hatch. Backticks and ${ are still template-literal syntax and must be escaped with a backslash — and that backslash then survives into the output. A trailing backslash immediately before the closing backtick is a syntax error for the same reason.
Calling it as a plain function requires the shape it expects: String.raw({ raw: ["a", "b"] }, 1). Passing an ordinary string throws a TypeError, because that argument has no raw property. If raw is empty or has no length, the result is "".
Example
When to use it
- Write a Windows file path without doubling every backslash
- Build a RegExp from a pattern string without double-escaping
- Emit LaTeX or other backslash-heavy markup from JavaScript
- Print a code sample that shows escape sequences literally
Frequently asked questions
How do I write a Windows file path in JavaScript without escaping backslashes?
Use String.raw with a template literal: String.raw`C:\Users\dev\file.txt` keeps every backslash as typed. The only limitation is that the path cannot end in a backslash immediately before the closing backtick.
What is the difference between String.raw and a normal template literal?
A normal template literal interprets escape sequences, turning \n into a newline, while String.raw leaves them as the literal characters. Both evaluate ${...} substitutions identically, so the only difference is escape handling.
Can String.raw be called as a regular function?
Yes, but the first argument must be an object with a raw property, such as String.raw({ raw: ["a", "b"] }, 1). Passing a plain string throws a TypeError, so the tagged-template form is what you want in practice.
More examples
Building regular expressions
Inside String.raw each backslash is a single literal character, so the pattern reads exactly as it would in a regex literal. The final comparison proves it is identical to the hand-doubled string, just far easier to read and to keep correct.
const version = String.raw`\d+\.\d+\.\d+`;
console.log(version);
const re = new RegExp(`^v${version}$`);
console.log(re.source);
console.log(re.test("v1.2.30"), re.test("v1.2"));
// The same pattern written without String.raw:
console.log("\\d+\\.\\d+\\.\\d+" === version);What raw actually receives
Every tag function gets both arrays: strings[0] is the cooked text with a real newline, strings.raw[0] keeps the two characters backslash and n. String.raw simply joins the raw array around the substitutions. Passing a plain string throws a TypeError because it has no raw property.
function inspect(strings, ...subs) {
console.log("cooked:", strings[0]);
console.log("raw: ", strings.raw[0]);
console.log("subs: ", subs);
return String.raw(strings, ...subs);
}
console.log("result:", inspect`line1\nvalue=${42}`);
try {
String.raw("not an object");
} catch (err) {
console.log(err.name);
}
Discussion