The valueOf()
method of Object
instances converts the this
value to an object. This method is meant to be overridden by derived objects for custom type conversion logic.
The valueOf()
method of Object
instances converts the this
value to an object. This method is meant to be overridden by derived objects for custom type conversion logic.
valueOf()
None.
The this
value, converted to an object.
Note: In order for valueOf
to be useful during type conversion, it must return a primitive. Because all primitive types have their own valueOf()
methods, calling aPrimitiveValue.valueOf()
generally does not invoke Object.prototype.valueOf()
.
JavaScript calls the valueOf
method to convert an object to a primitive value. You rarely need to invoke the valueOf
method yourself; JavaScript automatically invokes it when encountering an object where a primitive value is expected.
This method is called in priority by numeric conversion and primitive conversion, but string conversion calls toString()
in priority, and toString()
is very likely to return a string value (even for the Object.prototype.toString()
base implementation), so valueOf()
is usually not called in this case.
All objects that inherit from Object.prototype
(that is, all except null
-prototype objects) inherit the toString()
method. The Object.prototype.valueOf()
base implementation is deliberately useless: by returning an object, its return value will never be used by any primitive conversion algorithm. Many built-in objects override this method to return an appropriate primitive value. When you create a custom object, you can override valueOf()
to call a custom method, so that your custom object can be converted to a primitive value. Generally, valueOf()
is used to return a value that is most meaningful for the object — unlike toString()
, it does not need to be a string. Alternatively, you can add a @@toPrimitive
method, which allows even more control over the conversion process, and will always be preferred over valueOf
or toString
for any type conversion.
The base valueOf()
method returns the this
value itself, converted to an object if it isn't already. Therefore its return value will never be used by any primitive conversion algorithm.
const obj = { foo: 1 }; console.log(obj.valueOf() === obj); // true console.log(Object.prototype.valueOf.call("primitive")); // [String: 'primitive'] (a wrapper object)
You can create a function to be called in place of the default valueOf
method. Your function should take no arguments, since it won't be passed any when called during type conversion.
For example, you can add a valueOf
method to your custom class Box
.
class Box { #value; constructor(value) { this.#value = value; } valueOf() { return this.#value; } }
With the preceding code in place, any time an object of type Box
is used in a context where it is to be represented as a primitive value (but not specifically a string), JavaScript automatically calls the function defined in the preceding code.
const box = new Box(123); console.log(box + 456); // 579 console.log(box == 123); // true
An object's valueOf
method is usually invoked by JavaScript, but you can invoke it yourself as follows:
box.valueOf();
Unary plus performs number coercion on its operand, which, for most objects without @@toPrimitive
, means calling its valueOf()
. However, if the object doesn't have a custom valueOf()
method, the base implementation will cause valueOf()
to be ignored and the return value of toString()
to be used instead.
+new Date(); // the current timestamp; same as new Date().getTime() +{}; // NaN (toString() returns "[object Object]") +[]; // 0 (toString() returns an empty string list) +[1]; // 1 (toString() returns "1") +[1, 2]; // NaN (toString() returns "1,2") +new Set([1]); // NaN (toString() returns "[object Set]") +{ valueOf: () => 42 }; // 42
Desktop | Mobile | Server | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | WebView Android | Deno | Node.js | ||
valueOf |
1 | 12 | 1 | 3 | 1 | 18 | 4 | 10.1 | 1 | 1.0 | 4.4 | 1.0 | 0.10.0 |
© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/valueOf