String

string · String

Text in JavaScript is a string: an immutable sequence of UTF-16 code units. The lowercase string is the primitive you use every day; the capitalized Stringis its wrapper object and the home of the static helpers. Everything below — every method, every overload — lives on String.prototype.

Usage

Three ways to hold text. Reach for the first two; the third is a historical footgun kept for compatibility.

const name = "ada";               // literal — this one, always
const hi = "hello, " + name;      // or a template literal — interpolation + multiline
const boxed = new String("ada");  // avoid — an object, not a primitive

typeof name;   // "string"
typeof boxed;  // "object" — === against literals fails

How it works

A string is a primitive, yet you call methods on it. When you write "ada".toUpperCase(), the engine briefly wraps the primitive in a String object, runs the prototype method, and discards the wrapper. You never see the box.

Strings are immutable. No method edits in place; each returns a new string. Chaining like s.trim().toLowerCase() is the normal style, and each step allocates.

Underneath, text is UTF-16: length, indexing, charAt, and slice count 16-bit code units. Most characters fit in one unit, but emoji and some scripts need two (a surrogate pair), so "🦀".length === 2. For real characters, use the astral-aware tools: codePointAt, at, and the [Symbol.iterator], which yields whole code points.

Instance API

Everything on String.prototype, grouped by job. Signatures are the TypeScript 7.0 standard library types.

35 methods

length: number: Property. Counts UTF-16 code units, not visible characters.
at(index: number): string | undefined: Character at the index. Negatives count back from the end.
charAt(index: number): string: Character at the index, or an empty string when out of range.
charCodeAt(index: number): number: UTF-16 code unit at the index, or NaN when out of range.
codePointAt(pos: number): number | undefined: Full code point at the index. Astral-plane aware.

includes(searchString: string, position?: number): boolean: Whether the string contains the search.
startsWith(searchString: string, position?: number): boolean: Whether the string opens with the search.
endsWith(searchString: string, endPosition?: number): boolean: Whether the string closes with the search.
indexOf(searchString: string, position?: number): number: First index of the search, or -1.
lastIndexOf(searchString: string, position?: number): number: Last index of the search, or -1.
search(regexp: string | RegExp): number: Index of the first regex match, or -1.

slice(start?: number, end?: number): string: Section between indices. Negatives count back from the end.
substring(start: number, end?: number): string: Like slice, but clamps negatives to 0 and swaps when start > end.
split(separator: string | RegExp, limit?: number): string[]: Divides the string around each separator.

toLowerCase(): string: Lowercases every character. Locale-insensitive.
toUpperCase(): string: Uppercases every character. Locale-insensitive.
toLocaleLowerCase(locales?: Intl.LocalesArgument): string: Lowercases following locale rules, e.g. Turkish dotted I.
toLocaleUpperCase(locales?: Intl.LocalesArgument): string: Uppercases following locale rules.

trim(): string: Strips whitespace from both ends.
trimStart(): string: Strips leading whitespace. Alias: trimLeft.
trimEnd(): string: Strips trailing whitespace. Alias: trimRight.
padStart(maxLength: number, fillString?: string): string: Pads from the left until the target length.
padEnd(maxLength: number, fillString?: string): string: Pads from the right until the target length.
repeat(count: number): string: Repeats the string count times.

concat(...strings: string[]): string: Joins strings. Prefer + or a template literal.

replace(searchValue: string | RegExp, replaceValue: string): string: Replaces the first occurrence.
replace(searchValue: string | RegExp, replacer: (substring: string, ...args: any[]) => string): string: Replaces each match with the callback's return.
replaceAll(searchValue: string | RegExp, replaceValue: string): string: Replaces every occurrence. A regex must use the /g flag.
match(regexp: string | RegExp): RegExpMatchArray | null: First match with captures, or null.
matchAll(regexp: RegExp): IterableIterator<RegExpMatchArray>: Iterator over every match with captures. The regex must use /g.
normalize(form?: string): string: Returns the Unicode normalization form (NFC, NFD, NFKC, NFKD).
localeCompare(that: string): number: Sort order against another string: negative, 0, or positive.

toString(): string: The primitive value itself.
valueOf(): string: The primitive value itself.
[Symbol.iterator](): IterableIterator<string>: Iterates by code point, so for...of is emoji-safe.

Static API

Called on String itself. For building strings from codes rather than transforming them.

String.fromCharCode(...codes: number[]): string: Builds a string from UTF-16 code units.
String.fromCodePoint(...codePoints: number[]): string: Builds a string from code points. Astral-plane safe.
String.raw(template: { raw: readonly string[] }, ...substitutions: any[]): string: Raw template text. Backslashes pass through untouched.