String.raw()
BaselineWidely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2015.
TheString.raw() static method is a tag function oftemplate literals. This is similar to ther prefix in Python, or the@ prefix in C# for string literals. It's used to get the raw string form of template literals — that is, substitutions (e.g.,${foo}) are processed, but escape sequences (e.g.,\n) are not.
Try it
// Create a variable that uses a Windows// path without escaping the backslashes:const filePath = String.raw`C:\Development\profile\about.html`;console.log(`The file was uploaded from: ${filePath}`);// Expected output: "The file was uploaded from: C:\Development\profile\about.html"Syntax
String.raw(strings)String.raw(strings, sub1)String.raw(strings, sub1, sub2)String.raw(strings, sub1, sub2, /* …, */ subN)String.raw`templateString`Parameters
stringsWell-formed template literal array object, like
{ raw: ['foo', 'bar', 'baz'] }. Should be an object with arawproperty whose value is an array-like object of strings.sub1, …,subNContains substitution values.
templateStringAtemplate literal, optionally with substitutions (
${...}).
Return value
The raw string form of a given template literal.
Exceptions
TypeErrorThrown if the first argument doesn't have a
rawproperty, or therawproperty isundefinedornull.
Description
In most cases,String.raw() is used with template literals. The first syntax mentioned above is only rarely used, because the JavaScript engine will call this with proper arguments for you, (just like with othertag functions).
String.raw() is the only built-in template literal tag. It has close semantics to an untagged literal since it concatenates all arguments and returns a string. You can even re-implement it with normal JavaScript code.
Warning:You should not useString.raw directly as an "identity" tag. SeeBuilding an identity tag for how to implement this.
IfString.raw() is called with an object whoseraw property doesn't have alength property or a non-positivelength, it returns an empty string"". Ifsubstitutions.length < strings.raw.length - 1 (i.e., there are not enough substitutions to fill the placeholders — which can't happen in a well-formed tagged template literal), the rest of the placeholders are filled with empty strings.
Examples
Using String.raw()
String.raw`Hi\n${2 + 3}!`;// 'Hi\\n5!', the character after 'Hi'// is not a newline character,// '\' and 'n' are two characters.String.raw`Hi\u000A!`;// 'Hi\\u000A!', same here, this time we will get the// \, u, 0, 0, 0, A, 6 characters.// All kinds of escape characters will be ineffective// and backslashes will be present in the output string.// You can confirm this by checking the .length property// of the string.const name = "Bob";String.raw`Hi\n${name}!`;// 'Hi\\nBob!', substitutions are processed.String.raw`Hi \${name}!`;// 'Hi \\${name}!', the dollar sign is escaped; there's no interpolation.Using String.raw with RegExp
Combining aString.raw template literal with theRegExp() constructor allows you tocreate regular expressions with dynamic parts (which is not possible with regex literals) without double-escaping (\\) regular expression escape sequences (which is not possible with normal string literals). This is also valuable in strings that contain a lot of slashes, such as file paths or URLs.
// A String.raw template allows a fairly readable regular expression matching a URL:const reRawTemplate = new RegExp( String.raw`https://developer\.mozilla\.org/en-US/docs/Web/JavaScript/Reference/`,);// The same thing with a regexp literal looks like this, with \/ for// each forward slash:const reRegexpLiteral = /https:\/\/developer\.mozilla\.org\/en-US\/docs\/Web\/JavaScript\/Reference\//;// And the same thing written with the RegExp constructor and a// traditional string literal, with \\. for each period:const reStringLiteral = new RegExp( "https://developer\\.mozilla\\.org/en-US/docs/Web/JavaScript/Reference/",);// String.raw also allows dynamic parts to be includedfunction makeURLRegExp(path) { return new RegExp(String.raw`https://developer\.mozilla\.org/${path}`);}const reDynamic = makeURLRegExp("en-US/docs/Web/JavaScript/Reference/");const reWildcard = makeURLRegExp(".*");Building an identity tag
Many tools give special treatment to literals tagged by a particular name.
// Some formatters will format this literal's content as HTMLconst doc = html`<!doctype html> <html lang="en-US"> <head> <title>Hello</title> </head> <body> <h1>Hello world!</h1> </body> </html>`;One might naïvely implement thehtml tag as:
const html = String.raw;This, in fact, works for the case above. However, becauseString.raw would concatenate theraw string literals instead of the "cooked" ones, escape sequences would not be processed.
const doc = html`<canvas>\n</canvas>`;// "<canvas>\\n</canvas>"This may not be what you want for a "true identity" tag, where the tag is purely for markup and doesn't change the literal's value. In this case, you can create a custom tag and pass the "cooked" (i.e., escape sequences are processed) literal array toString.raw, pretending they are raw strings.
const html = (strings, ...values) => String.raw({ raw: strings }, ...values);// Some formatters will format this literal's content as HTMLconst doc = html`<canvas>\n</canvas>`;// "<canvas>\n</canvas>"; the "\n" becomes a line breakNotice the first argument is an object with araw property, whose value is an array-like object (with alength property and integer indexes) representing the separated strings in the template literal. The rest of the arguments are the substitutions. Since theraw value can be any array-like object, it can even be a string! For example,'test' is treated as['t', 'e', 's', 't']. The following is equivalent to`t${0}e${1}s${2}t`:
String.raw({ raw: "test" }, 0, 1, 2); // 't0e1s2t'Specifications
| Specification |
|---|
| ECMAScript® 2026 Language Specification # sec-string.raw |