W3cubDocs

/JavaScript

String

The String object is used to represent and manipulate a sequence of characters.

Description

Strings are useful for holding data that can be represented in text form. Some of the most-used operations on strings are to check their length, to build and concatenate them using the + and += string operators, checking for the existence or location of substrings with the indexOf() method, or extracting substrings with the substring() method.

Creating strings

Strings can be created as primitives, from string literals, or as objects, using the String() constructor:

const string1 = "A string primitive";
const string2 = 'Also a string primitive';
const string3 = `Yet another string primitive`;
const string4 = new String("A String object");

String primitives and string objects can be used interchangeably in most situations. See "String primitives and String objects" below.

String literals can be specified using single or double quotes, which are treated identically, or using the backtick character `. This last form specifies a template literal: with this form you can interpolate expressions.

Character access

There are two ways to access an individual character in a string. The first is the charAt() method:

return 'cat'.charAt(1) // returns "a"

The other way (introduced in ECMAScript 5) is to treat the string as an array-like object, where individual characters correspond to a numerical index:

return 'cat'[1] // returns "a"

When using bracket notation for character access, attempting to delete or assign a value to these properties will not succeed. The properties involved are neither writable nor configurable. (See Object.defineProperty() for more information.)

Comparing strings

In C, the strcmp() function is used for comparing strings. In JavaScript, you just use the less-than and greater-than operators:

let a = 'a'
let b = 'b'
if (a < b) { // true
  console.log(a + ' is less than ' + b)
} else if (a > b) {
  console.log(a + ' is greater than ' + b)
} else {
  console.log(a + ' and ' + b + ' are equal.')
}

A similar result can be achieved using the localeCompare() method inherited by String instances.

Note that a == b compares the strings in a and b for being equal in the usual case-sensitive way. If you wish to compare without regard to upper or lower case characters, use a function similar to this:

function isEqual(str1, str2)
{
    return str1.toUpperCase() === str2.toUpperCase()
} // isEqual

Upper case is used instead of lower case in this function, due to problems with certain UTF-8 character conversions.

String primitives and String objects

Note that JavaScript distinguishes between String objects and primitive string values. (The same is true of Boolean and Numbers.)

String literals (denoted by double or single quotes) and strings returned from String calls in a non-constructor context (that is, called without using the new keyword) are primitive strings. JavaScript automatically converts primitives to String objects, so that it's possible to use String object methods for primitive strings. In contexts where a method is to be invoked on a primitive string or a property lookup occurs, JavaScript will automatically wrap the string primitive and call the method or perform the property lookup.

let s_prim = 'foo'
let s_obj = new String(s_prim)

console.log(typeof s_prim) // Logs "string"
console.log(typeof s_obj)  // Logs "object"

String primitives and String objects also give different results when using eval(). Primitives passed to eval are treated as source code; String objects are treated as all other objects are, by returning the object. For example:

let s1 = '2 + 2'              // creates a string primitive
let s2 = new String('2 + 2')  // creates a String object
console.log(eval(s1))         // returns the number 4
console.log(eval(s2))         // returns the string "2 + 2"

For these reasons, the code may break when it encounters String objects when it expects a primitive string instead, although generally, authors need not worry about the distinction.

A String object can always be converted to its primitive counterpart with the valueOf() method.

console.log(eval(s2.valueOf()))  // returns the number 4

Escape notation

Special characters can be encoded using escape notation:

Code Output
\XXX
(where XXX is 1–3 octal digits; range of 0377)
ISO-8859-1 character / Unicode code point between U+0000 and U+00FF
\' single quote
\" double quote
\\ backslash
\n new line
\r carriage return
\v vertical tab
\t tab
\b backspace
\f form feed
\uXXXX (where XXXX is 4 hex digits; range of 0x00000xFFFF) UTF-16 code unit / Unicode code point between U+0000 and U+FFFF
\u{X} ... \u{XXXXXX}
(where XXXXXXX is 1–6 hex digits; range of 0x00x10FFFF)
UTF-32 code unit / Unicode code point between U+0000 and U+10FFFF
\xXX
(where XX is 2 hex digits; range of 0x000xFF)
ISO-8859-1 character / Unicode code point between U+0000 and U+00FF

Long literal strings

Sometimes, your code will include strings which are very long. Rather than having lines that go on endlessly, or wrap at the whim of your editor, you may wish to specifically break the string into multiple lines in the source code without affecting the actual string contents. There are two ways you can do this.

Method 1

You can use the + operator to append multiple strings together, like this:

let longString = "This is a very long string which needs " +
                 "to wrap across multiple lines because " +
                 "otherwise my code is unreadable."

Method 2

You can use the backslash character (\) at the end of each line to indicate that the string will continue on the next line. Make sure there is no space or any other character after the backslash (except for a line break), or as an indent; otherwise it will not work.

That form looks like this:

let longString = "This is a very long string which needs \
to wrap across multiple lines because \
otherwise my code is unreadable."

Both of the above methods result in identical strings.

Constructor

String()
Creates a new String object. It performs type conversion when called as a function, rather than as a constructor, which is usually more useful.

Static methods

String.fromCharCode(num1 [, ...[, numN]])
Returns a string created by using the specified sequence of Unicode values.
String.fromCodePoint(num1 [, ...[, numN)
Returns a string created by using the specified sequence of code points.
String.raw()
Returns a string created from a raw template string.

Instance properties

String.prototype.length
Reflects the length of the string. Read-only.

Instance methods

String.prototype.charAt(index)
Returns the character (exactly one UTF-16 code unit) at the specified index.
String.prototype.charCodeAt(index)
Returns a number that is the UTF-16 code unit value at the given index.
String.prototype.codePointAt(pos)
Returns a nonnegative integer Number that is the code point value of the UTF-16 encoded code point starting at the specified pos.
String.prototype.concat(str [, ...strN ])
Combines the text of two (or more) strings and returns a new string.
String.prototype.includes(searchString [, position])
Determines whether the calling string contains searchString.
String.prototype.endsWith(searchString [, length])
Determines whether a string ends with the characters of the string searchString.
String.prototype.indexOf(searchValue [, fromIndex])
Returns the index within the calling String object of the first occurrence of searchValue, or -1 if not found.
String.prototype.lastIndexOf(searchValue [, fromIndex])
Returns the index within the calling String object of the last occurrence of searchValue, or -1 if not found.
String.prototype.localeCompare(compareString [, locales [, options]])
Returns a number indicating whether the reference string compareString comes before, after, or is equivalent to the given string in sort order.
String.prototype.match(regexp)
Used to match regular expression regexp against a string.
String.prototype.matchAll(regexp)
Returns an iterator of all regexp's matches.
String.prototype.normalize([form])
Returns the Unicode Normalization Form of the calling string value.
String.prototype.padEnd(targetLength [, padString])
Pads the current string from the end with a given string and returns a new string of the length targetLength.
String.prototype.padStart(targetLength [, padString])
Pads the current string from the start with a given string and returns a new string of the length targetLength.
String.prototype.repeat(count)
Returns a string consisting of the elements of the object repeated count times.
String.prototype.replace(searchFor, replaceWith)
Used to replace occurrences of searchFor using replaceWith. searchFor may be a string or Regular Expression, and replaceWith may be a string or function.
String.prototype.replaceAll(searchFor, replaceWith)
Used to replace all occurrences of searchFor using replaceWith. searchFor may be a string or Regular Expression, and replaceWith may be a string or function.
String.prototype.search(regexp)
Search for a match between a regular expression regexp and the calling string.
String.prototype.slice(beginIndex[, endIndex])
Extracts a section of a string and returns a new string.
String.prototype.split([sep [, limit] ])
Returns an array of strings populated by splitting the calling string at occurences of the substring sep.
String.prototype.startsWith(searchString [, length])
Determines whether the calling string begins with the characters of string searchString.
String.prototype.substr()
Returns the characters in a string beginning at the specified location through the specified number of characters.
String.prototype.substring(indexStart [, indexEnd])
Returns a new string containing characters of the calling string from (or between) the specified index (or indeces).
String.prototype.toLocaleLowerCase( [locale, ...locales])

The characters within a string are converted to lowercase while respecting the current locale.

For most languages, this will return the same as toLowerCase().

String.prototype.toLocaleUpperCase( [locale, ...locales])

The characters within a string are converted to uppercase while respecting the current locale.

For most languages, this will return the same as toUpperCase().

String.prototype.toLowerCase()
Returns the calling string value converted to lowercase.
String.prototype.toString()
Returns a string representing the specified object. Overrides the Object.prototype.toString() method.
String.prototype.toUpperCase()
Returns the calling string value converted to uppercase.
String.prototype.trim()
Trims whitespace from the beginning and end of the string. Part of the ECMAScript 5 standard.
String.prototype.trimStart()
Trims whitespace from the beginning of the string.
String.prototype.trimEnd()
Trims whitespace from the end of the string.
String.prototype.valueOf()
Returns the primitive value of the specified object. Overrides the Object.prototype.valueOf() method.
[email protected]@iterator()
Returns a new Iterator object that iterates over the code points of a String value, returning each code point as a String value.

HTML wrapper methods

Deprecated. Avoid these methods.

They are of limited use, as they provide only a subset of the available HTML tags and attributes.

String.prototype.anchor()
<a name="name"> (hypertext target)
String.prototype.big()
<big>
String.prototype.blink()
<blink>
String.prototype.bold()
<b>
String.prototype.fixed()
<tt>
String.prototype.fontcolor()
<font color="color">
String.prototype.fontsize()
<font size="size">
String.prototype.italics()
<i>
String.prototype.link()
<a href="url"> (link to URL)
String.prototype.small()
<small>
String.prototype.strike()
<strike>
String.prototype.sub()
<sub>
String.prototype.sup()
<sup>

Examples

String conversion

It's possible to use String as a more reliable toString() alternative, as it works when used on null, undefined, and on symbols. For example:

let outputStrings = []
for (let i = 0, n = inputValues.length; i < n; ++i) {
  outputStrings.push(String(inputValues[i]));
}

Specifications

Browser compatibilityUpdate compatibility data on GitHub

Desktop
Chrome Edge Firefox Internet Explorer Opera Safari
String 1 12 1 3 3 1
String() constructor 1 12 1 3 3 1
anchor 1 12 1
1
Starting with version 17, the quotation mark (") is replaced by its HTML reference character (") in strings supplied for the name parameter.
No 3 1
big 1 12 1 3 3 1
blink 1 12 1 3 3 1
bold 1 12 1 3 3 1
charAt 1 12 1 3 3 1
charCodeAt 1 12 1 4 4 1
codePointAt 41 12 29 No 28 10
concat 1 12 1 4 4 1
endsWith 41 12 17 No 28 9
fixed 1 12 1 3 3 1
fontcolor 1 12 1 3 3 1
fontsize 1 12 1 3 3 1
fromCharCode 1 12 1 4 4 1
fromCodePoint 41 12 29 No 28 10
includes 41 12 40
40
18 — 48
Uses the non-standard name: contains
No 28 9
indexOf 1 12 1 3 3 1
italics 1 12 1 3 3 1
lastIndexOf 1 12 1 6 3 1
length 1 12 1 3 3 1
link 1 12 1 3 3 1
localeCompare 1 12 1 5.5 7 3
match 1 12 1 4 4 1
matchAll 73 79 67 No 60 13
normalize 34 12 31 No 21 10
padEnd 57 15 48 No 44 10
padStart 57 15 48 No 44 10
raw 41 12 34 No No 10
repeat 41 12 24 No 28 9
replace 1 12 1 4 4 1
replaceAll 85 85 77 No 71 13.1
search 1 12 1 4 4 1
slice 1 12 1 4 4 1
small 1 12 1 3 3 1
split 1 12 1 4 3 1
startsWith 41 12 17 No 28 9
strike 1 12 1 3 3 1
sub 1 12 1 3 3 1
substr 1 12 1 4 4 1
substring 1 12 1 3 3 1
sup 1 12 1 3 3 1
toLocaleLowerCase 1 12 1 5.5 4 1.3
toLocaleUpperCase 1 12 1 5.5 4 1.3
toLowerCase 1 12 1 3 3 1
toSource No No 1 — 74
1 — 74
Starting in Firefox 74, toSource() is no longer available for use by web content. It is still allowed for internal and privileged code.
No No No
toString 1 12 1 3 3 1
toUpperCase 1 12 1 3 3 1
trim 4 12 3.5 9 10.5 5
trimEnd 66
66
4
Uses the non-standard name: trimRight
12
12
Uses the non-standard name: trimRight
61
61
3.5
Uses the non-standard name: trimRight
No 53
53
15
Uses the non-standard name: trimRight
12
trimStart 66
66
4
Uses the non-standard name: trimLeft
12
12
Uses the non-standard name: trimLeft
61
61
3.5
Uses the non-standard name: trimLeft
No 53
53
15
Uses the non-standard name: trimLeft
12
Unicode code point escapes \u{xxxxxx} 1 12 40 4 4 1
valueOf 1 12 1 4 3 1
@@iterator 38 12 36
36
27 — 36
A placeholder property named @@iterator is used.
Uses the non-standard name: @@iterator
17 — 27
A placeholder property named iterator is used.
Uses the non-standard name: iterator
No 25 9
Mobile
Android webview Chrome for Android Firefox for Android Opera for Android Safari on iOS Samsung Internet
String 1 18 4 10.1 1 1.0
String() constructor 1 18 4 10.1 1 1.0
anchor 1 18 4 10.1 1 1.0
big 1 18 4 10.1 1 1.0
blink 1 18 4 10.1 1 1.0
bold 1 18 4 10.1 1 1.0
charAt 1 18 4 10.1 1 1.0
charCodeAt 1 18 4 10.1 1 1.0
codePointAt 41 41 29 28 10 4.0
concat 1 18 4 10.1 1 1.0
endsWith ≤37 36 17 24 9 3.0
fixed 1 18 4 10.1 1 1.0
fontcolor 1 18 4 10.1 1 1.0
fontsize 1 18 4 10.1 1 1.0
fromCharCode 1 18 4 10.1 1 1.0
fromCodePoint 41 41 29 28 10 4.0
includes 41 41 40
40
18 — 48
Uses the non-standard name: contains
28 9 4.0
indexOf 1 18 4 10.1 1 1.0
italics 1 18 4 10.1 1 1.0
lastIndexOf 1 18 4 10.1 1 1.0
length 1 18 4 10.1 1 1.0
link 1 18 4 10.1 1 1.0
localeCompare 1 18 4 10.1 1 1.0
match 1 18 4 10.1 1 1.0
matchAll 73 73 67 52 13 No
normalize No 34 31 21 10 2.0
padEnd 57 57 48 43 10 7.0
padStart 57 57 48 43 10 7.0
raw No 41 34 No 10 4.0
repeat No 36 24 28 9 3.0
replace 1 18 4 10.1 1 1.0
replaceAll 85 85 79 60 13.4 No
search 1 18 4 10.1 1 1.0
slice 1 18 4 10.1 1 1.0
small 1 18 4 10.1 1 1.0
split 1 18 4 10.1 1 1.0
startsWith ≤37 36 17 24 9 3.0
strike 1 18 4 10.1 1 1.0
sub 1 18 4 10.1 1 1.0
substr 1 18 4 10.1 1 1.0
substring 1 18 4 10.1 1 1.0
sup 1 18 4 10.1 1 1.0
toLocaleLowerCase 1 18 4 10.1 1 1.0
toLocaleUpperCase 1 18 4 10.1 1 1.0
toLowerCase 1 18 4 10.1 1 1.0
toSource No No 4 No No No
toString 1 18 4 10.1 1 1.0
toUpperCase 1 18 4 10.1 1 1.0
trim ≤37 18 4 11 5 1.0
trimEnd 66
66
≤37
Uses the non-standard name: trimRight
66
66
18
Uses the non-standard name: trimRight
61
61
4
Uses the non-standard name: trimRight
47
47
14
Uses the non-standard name: trimRight
12 9.0
9.0
1.0
Uses the non-standard name: trimRight
trimStart 66
66
≤37
Uses the non-standard name: trimLeft
66
66
18
Uses the non-standard name: trimLeft
61
61
4
Uses the non-standard name: trimLeft
47
47
14
Uses the non-standard name: trimLeft
12 9.0
9.0
1.0
Uses the non-standard name: trimLeft
Unicode code point escapes \u{xxxxxx} 1 18 40 10.1 1 1.0
valueOf 1 18 4 10.1 1 1.0
@@iterator 38 38 36
36
27 — 36
A placeholder property named @@iterator is used.
Uses the non-standard name: @@iterator
17 — 27
A placeholder property named iterator is used.
Uses the non-standard name: iterator
25 9 3.0
Server
Node.js
String 0.1.100
String() constructor 0.1.100
anchor 0.1.100
big 0.1.100
blink 0.1.100
bold 0.1.100
charAt 0.1.100
charCodeAt 0.1.100
codePointAt 4.0.0
4.0.0
0.12
Disabled
Disabled From version 0.12: this feature is behind the --harmony runtime flag.
concat 0.1.100
endsWith 4.0.0
4.0.0
0.12
Disabled
Disabled From version 0.12: this feature is behind the --harmony runtime flag.
fixed 0.1.100
fontcolor 0.1.100
fontsize 0.1.100
fromCharCode 0.1.100
fromCodePoint 4.0.0
4.0.0
0.12
Disabled
Disabled From version 0.12: this feature is behind the --harmony runtime flag.
includes 4.0.0
indexOf 0.1.100
italics 0.1.100
lastIndexOf 0.1.100
length 0.1.100
link 0.1.100
localeCompare 0.1.100
match 0.1.100
matchAll 12.0.0
normalize 0.12
padEnd 8.0.0
8.0.0
7.0.0
Disabled
Disabled From version 7.0.0: this feature is behind the --harmony runtime flag.
padStart 8.0.0
8.0.0
7.0.0
Disabled
Disabled From version 7.0.0: this feature is behind the --harmony runtime flag.
raw 4.0.0
repeat 4.0.0
4.0.0
0.12
Disabled
Disabled From version 0.12: this feature is behind the --harmony runtime flag.
replace 0.1.100
replaceAll No
search 0.1.100
slice 0.1.100
small 0.1.100
split 0.1.100
startsWith 4.0.0
4.0.0
0.12
Disabled
Disabled From version 0.12: this feature is behind the --harmony runtime flag.
strike 0.1.100
sub 0.1.100
substr 0.1.100
substring 0.1.100
sup 0.1.100
toLocaleLowerCase 0.1.100
toLocaleUpperCase 0.1.100
toLowerCase 0.1.100
toSource No
toString 0.1.100
toUpperCase 0.1.100
trim 0.1.100
trimEnd 10.0.0
10.0.0
0.12
Uses the non-standard name: trimRight
trimStart 10.0.0
10.0.0
0.12
Uses the non-standard name: trimLeft
Unicode code point escapes \u{xxxxxx} 0.1.100
valueOf 0.1.100
@@iterator 0.12

See also

© 2005–2018 Mozilla Developer Network and individual contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String