JavaScript String valueOf() Method

What You’ll Learn

String.prototype.valueOf() returns this string’s primitive text (same API as MDN String.prototype.valueOf()). Learn how it unwraps new String(...) objects, how it matches toString(), why it is often called by the engine, five examples, and try-it labs.

Introduction

Almost every string you write is already a primitive ("like this". valueOf() returns that primitive text — especially useful when you meet a String object from new String(...).

For String values, the result is equivalent to toString(). MDN notes this method is usually called internally by JavaScript during coercion, not typed out by hand.

This page is part of JavaScript String Methods. Related topics include toString() and localeCompare().

Understanding the valueOf() Method

str.valueOf() returns the underlying string primitive. On a String object it unwraps the wrapped text; on a literal it returns the same characters.

• Returns a string primitive.
• Equivalent to String.prototype.toString() for String values.
• Requires this to be a string primitive or String object.
• Throws TypeError for other this values (no coercion).

📝 Syntax

General form of String.prototype.valueOf:

str.valueOf()

Parameters

None.

Return value

A string representing the primitive value of a given String object (or the string itself).

Exceptions

TypeError if this is not a string primitive or a String object.

Common patterns

"hello".valueOf();                 // "hello"
new String("foo").valueOf();       // "foo"
new String("Hi").toString();       // "Hi" (same text)
typeof new String("x");            // "object"
typeof new String("x").valueOf();  // "string"

Examples Gallery

Examples follow MDN String.valueOf() patterns. Use View Output or Try It Yourself for each case.

const stringObj = new String("foo");

console.log(typeof stringObj);
// "object"

console.log(stringObj.valueOf());
// "foo"

object
foo

const x = new String("Hello world");
console.log(x.valueOf());
// 'Hello world'

Hello world

const literal = "hello";
const wrapped = new String("hello");

console.log(typeof literal);                // "string"
console.log(typeof literal.valueOf());      // "string"
console.log(typeof wrapped);                // "object"
console.log(typeof wrapped.valueOf());      // "string"
console.log(literal.valueOf() === wrapped.valueOf()); // true

string
string
object
string
true

const s = new String("CodeToFun");

console.log(s.valueOf());
console.log(s.toString());
console.log(s.valueOf() === s.toString());
// true

CodeToFun
CodeToFun
true

try {
  String.prototype.valueOf.call(42);
} catch (err) {
  console.log(err.name);
  // TypeError
}

console.log(String(42));
// "42" — general conversion still works

TypeError
42

🎯 Common Use Cases

• Unwrap String objects — turn new String(...) into a primitive.
• Explicit APIs — document that you need a string primitive.
• Understand coercion — engines often call valueOf for you.
• Not for general coercion — prefer String(value).
• Rare for literals — "hi".valueOf() is valid but usually unnecessary.

📝 Notes

• Equivalent to toString() for String values.
• Usually invoked by the language during coercion — not always written in app code.
• Avoid new String() in modern code unless you have a special reason.
• Wrappers and primitives are not equal with === until you unwrap.
• Do not confuse with Number/Boolean valueOf — those return other primitives.

💡 Best Practices