Object to primitive conversion

Objects meet primitive-only places

You already know from the Type conversion lesson that JavaScript can turn values into strings and numbers. You also saw puzzles such as [] + [] becoming an empty string and [] + becoming "[object Object]". This lesson explains the missing middle step: when an object is used where JavaScript needs a primitive, JavaScript asks the object to hand over one primitive value.

A primitive is a value such as a string, number, boolean, bigint, symbol, null, or undefined. Objects are containers. Operators like unary +, multiplication, template literal interpolation, loose equality, and many string APIs cannot work directly with the whole container, so they request a primitive first.

The deeper Type coercion and Equality & sameness lessons will revisit these rules inside larger algorithms. Much later, A tour of the abstract operations names the spec steps ToPrimitive and OrdinaryToPrimitive. For now, you only need the practical rule you can run and predict.

JavaScript does not randomly pick between methods. It follows this order every time an object needs to become a primitive:

1. If obj[Symbol.toPrimitive] exists, call it with one argument: the hint "string", "number", or "default".
2. If that method returns a primitive, use it. If it returns an object, throw TypeError.
3. If there is no symbol method and the hint is "string", try toString(), then valueOf(). Use the first primitive result.
4. If there is no symbol method and the hint is "number" or "default", try valueOf(), then toString(). Use the first primitive result.
5. If none of those calls produces a primitive, throw TypeError.

Here is the TypeError part proved by the same runtime that executes the tests for this lesson: a custom hook that returns an object produces TypeError: Cannot convert object to primitive value.

Symbol.toPrimitive is a well-known symbol: a symbol JavaScript itself looks for to customize built-in behavior. Put a method at that key and the object carries its own conversion answer sheet.

The money object below returns a formatted label for text, and a number for math. Step through it and notice that the same object can answer differently depending on the hint.

1const price = {Run2  cents: 1299,3  [Symbol.toPrimitive](hint) {4    if (hint === "string") return "₹12.99";5    return this.cents / 100;6  }7};8 9String(price);10+price;11price + 1;

This is powerful, so use it sparingly. A money object that behaves numerically in totals can be handy. A user profile object that secretly becomes a number is confusing. If the conversion surprises a teammate, prefer an explicit method such as price.toNumber().

Most objects do not define Symbol.toPrimitive. Then JavaScript uses the older methods valueOf() and toString(). Their names describe their intended jobs:

• toString() should return a text representation.
• valueOf() should return the underlying primitive value, when the object has one.

Plain objects inherit valueOf(), but it returns the object itself. That is not a primitive, so JavaScript keeps going and often lands on toString(), whose inherited result is "[object Object]". Arrays override toString(), which is why arrays have their own surprises.

1const calls = [];Run2const sample = {3  valueOf() {4    calls.push("valueOf");5    return 42;6  },7  toString() {8    calls.push("toString");9    return "forty-two";10  }11};12 13String(sample);14+sample;15sample + "!";

The hint is not the final type guarantee. It is JavaScript saying what kind of answer would be useful. After an object returns a primitive, the surrounding operation may still convert that primitive again. For example, multiplication asks for a number-like primitive, then converts it to a number for math.

Try the operations yourself. The object logs the real hint it received, then returns a primitive chosen to make the result obvious.

1const obj = {2  [Symbol.toPrimitive](hint) {3    console.log("hint:", hint);4    if (hint === "string") return "object-card";5    if (hint === "number") return 7;6    return 3;7  }8};9 10String(obj);11`${obj}`;12obj + "";13+obj;14obj * 2;15obj + 1;16obj == 1;17obj > 0;18[obj].join();

Arrays are objects, but their toString() method behaves like join(","). That one fact explains many early JavaScript surprises.

1String({});2String([]);3[1, 2] + "";4[5] * 2;5[1, 2] + [3];6[] + {};7({} + []);

1const date = new Date("2020-01-02T00:00:00.000Z");2String(date);3+date;4date + 1;

• String([]) is an empty string because joining no elements gives empty text.
• [1, 2] + "" becomes "1,2".
• [5] * 2 becomes "5" * 2, then numeric multiplication gives 10.
• [1, 2] + [3] becomes "1,2" + "3", which is "1,23".
• [] + as an expression becomes "[object Object]".
• ( + []) as an expression also becomes "[object Object]". In a console, + [] typed at the beginning of a statement can parse as a block, so the remaining +[] is 0. The parentheses prove the expression form.

Dates are special. String(date) gives a readable date string. +date asks for the number hint and gives the timestamp. But date + 1 uses the default hint, and Date treats default like string, so the 1 is appended to a date string.

Where you’ll use this

You do not need custom conversion on every object. Most application objects are clearer with named methods. But understanding conversion helps in three practical places:

1. Readable logging and templates. A useful toString() keeps debugging output from showing "[object Object]".
2. Value objects. Money, measurements, temperatures, and IDs sometimes deserve a small, well-tested primitive conversion.
3. Debugging coercion. When +, ==, or comparison surprises you, you can ask “which hint did this send?” instead of guessing.

Common misconceptions

• “Binary plus asks for string.” Not first. With objects it asks for the default hint, then decides between addition and concatenation after primitives are available.
• “The hint forces the final type.” No. The object can return any primitive. The operation may convert again afterward.
• “valueOf always wins.” Only for number and default ordinary fallback. The string hint tries toString() first.
• “Plain objects cannot become strings.” They can: inherited toString() returns "[object Object]".
• “Dates behave like ordinary objects.” Date treats the default hint as string-like, which is why date + 1 concatenates.
• “Returning an object from Symbol.toPrimitive falls back.” It throws TypeError. The custom hook must return a primitive.

Key takeaways

• Symbol.toPrimitive is checked first and receives the hint.
• If the custom hook returns an object, JavaScript throws TypeError.
• Without the symbol hook, string tries toString() before valueOf().
• Without the symbol hook, number and default try valueOf() before toString().
• Binary + and loose equality use the default hint; unary plus, multiplication, and relational comparison use number; templates and String() use string.
• Arrays stringify by joining, and Date treats the default hint as string-like.

Object to primitive conversion is JavaScript asking an object for one primitive value, guided by a hint, before the surrounding operation continues.

Up next: Array basics.