Object to primitive conversion

When an object must become a simple value

In the Type conversion lesson, you saw JavaScript turn values into strings and numbers. You also saw two puzzles. [] + [] gives an empty string. [] + gives the text "[object Object]". This lesson explains the step that was missing.

When JavaScript needs a simple value but has an object, it asks the object to give back one simple value.

A simple value is called a primitive. These are the primitives:

• a string, like "hi"
• a number, like 5
• a boolean: true or false
• a bigint, like 10n
• a symbol, a special unique key
• null and undefined

An object is different. It is a container that holds many named values. Some code can't work with a whole container. Here are four examples:

• +obj: a plus with nothing on its left. It turns a value into a number.
• obj * 2: multiplication.
• `$${obj}`: a template literal. It is text inside backticks, and ${...} puts a value into the text.
• obj == 1: loose equality, with two equals signs. It converts values before it compares them.

Each of these first asks the object for a primitive. Then it carries on with that primitive.

Start with a small example. The user object below has a toString() method. A toString() method returns the object as text.

1const user = {2  name: "Asha",3  toString() {4    return this.name;5  }6};7 8console.log(String(user));9console.log(`${user}`);

Line 8 prints Asha. String(user) asks the object for text, so JavaScript calls toString(). Line 9 prints Asha too, because the template literal also asks for text. The object didn't change. Only the code around it changed how JavaScript asked.

When JavaScript asks an object for a primitive, it also says what kind of answer it wants. This word is called the hint. There are three hints: "string", "number", and "default".

Two later lessons, Type coercion and Equality & sameness, use these rules inside bigger steps. Much later, A tour of the abstract operations shows the names that the specification, the official rulebook for JavaScript, gives them: ToPrimitive and OrdinaryToPrimitive. For now, you only need the rules in this lesson. You can run them and predict them.

JavaScript doesn't pick a method at random. Each time an object must become a primitive, it follows these steps in order:

1. Does the object have a method at the key Symbol.toPrimitive? If yes, JavaScript calls it and passes the hint: "string", "number", or "default".
2. If that method returns a primitive, JavaScript uses it. If it returns an object, JavaScript throws a TypeError. A TypeError is an error that means "this value is the wrong kind".
3. If there is no such method and the hint is "string", JavaScript tries toString() first, then valueOf(). It uses the first primitive it gets.
4. If there is no such method and the hint is "number" or "default", JavaScript tries valueOf() first, then toString(). It uses the first primitive it gets.
5. If none of these gives a primitive, JavaScript throws a TypeError.

The method at Symbol.toPrimitive must return a primitive. The example below breaks this rule on purpose, so you can spot the error if you meet it later.

1const box = {2  [Symbol.toPrimitive]() {3    return {};4  }5};6 7try {8  String(box);9} catch (error) {10  console.log(error.name);11}

• Line 3 returns {}, an empty object.
• Line 8 asks for a string, so JavaScript calls the method and gets an object back.
• JavaScript doesn't go on to try valueOf() or toString(). It throws a TypeError right away.
• The catch block on line 9 catches the error. Line 10 prints its name: TypeError.

This is the full error message from a real run of the same code: TypeError: Cannot convert object to primitive value.

A symbol is a special, unique kind of key. Symbol.toPrimitive is a symbol that JavaScript itself knows about. That is why it is called a well-known symbol. When you put a method at this key, the object gives its own answer each time JavaScript asks it for a primitive.

You write the key in square brackets, like [Symbol.toPrimitive](hint) { ... }. The method gets one argument, hint. It is the kind of answer JavaScript wants.

The price object below has a method at Symbol.toPrimitive. Step through it, and watch the same object give different answers for different hints.

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;

• Line 4: if the hint is "string", the method returns the text "₹12.99".
• Line 5: for any other hint, it returns this.cents / 100, which is the number 12.99.
• Line 9 asks with "string". Line 10 asks with "number". Line 11 asks with "default", so price + 1 is 13.99.

This is powerful, so use it rarely. A money object that works in sums can be handy. A user object that quietly turns into a number is confusing. If the result would surprise someone reading the code, use a named method instead, like price.toNumber().

Most objects don't have a method at Symbol.toPrimitive. Then JavaScript uses two older methods instead: valueOf() and toString(). This lesson calls them the backup methods. Every plain object already has both. It borrows them from Object.prototype, a built-in object that all plain objects share methods with.

Their names tell you their jobs:

• toString() should return the object as text.
• valueOf() should return the simple value inside the object, if it has one.

The table shows which backup method JavaScript tries first for each hint. Read each row as: "for this hint, try this method, then that one."

Now you can explain "[object Object]". A plain object's valueOf() returns the object itself. That is not a primitive, so JavaScript moves on to toString(). A plain object's toString() returns the text "[object Object]". Arrays have their own toString(), so they give different results. You'll see them later in this lesson.

You don't have to use these automatic conversions. When a value could mean more than one thing, named methods are easier to read and to test. In the example below, toFixed(2) turns a number into text with two digits after the dot.

1const price = {2  cents: 500,3  toLabel() {4    return `$${(this.cents / 100).toFixed(2)}`;5  },6  toNumber() {7    return this.cents / 100;8  }9};10 11console.log(price.toLabel());12console.log(price.toNumber() + 2);

Line 11 prints $5.00. Line 12 prints 7, because 5 + 2 is 7. The code calls toLabel() when it wants text, and toNumber() when it wants a number. A reader doesn't need to remember which code sends which hint.

Now try the backup methods yourself. Pick which methods the object has. Then step through three conversions and watch which method JavaScript calls. The calls array keeps a list of every method that ran.

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 says what kind of answer would help. It doesn't force the final type. The object can return any primitive. After that, the code may convert the primitive again. For example, obj * 2 asks with the "number" hint. If the object returns the text "5", multiplication still turns it into the number 5.

The table lists common code and the hint each one sends. Read each row as: "this code sends this hint, for this reason."

Try the code yourself. The object below prints the hint it gets. Then it returns a primitive that makes the result easy to read:

• "object-card" for the "string" hint
• 7 for the "number" hint
• 3 for the "default" hint

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 too. An array's toString() works like join(","). It puts the items together into one piece of text, with a comma between them. This one fact explains many JavaScript puzzles.

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;

In the arrays example, line by line:

• Line 1: String({}) is "[object Object]", from a plain object's toString().
• Line 2: String([]) is an empty string. An empty array has no items to join.
• Line 3: [1, 2] + "" becomes "1,2".
• Line 4: [5] * 2 first turns the array into "5". Multiplication then turns "5" into 5, so the result is 10.
• Line 5: [1, 2] + [3] becomes "1,2" + "3". Both sides are text, so + joins them into "1,23".
• Line 6: [] + {} becomes "" + "[object Object]", which is "[object Object]".
• Line 7: ({} + []) is also "[object Object]". The round brackets matter here. In the console, a line that starts with {} can be read as an empty block of code, not an object. Then only +[] is left, which is 0. The brackets make JavaScript read {} as an object.

Dates are different. They come with their own Symbol.toPrimitive method. In the date example, line by line:

• Line 2: String(date) gives the date as readable text.
• Line 3: +date asks with the "number" hint. It gives a timestamp: the number of milliseconds since 1 January 1970.
• Line 4: date + 1 asks with the "default" hint. A date treats "default" like "string", so it returns the date as text. Then + adds "1" to the end of that text.

Where you’ll use this

Most objects in an app don't need their own conversion. Named methods are usually clearer. But knowing how conversion works helps in three places:

1. Readable logs and messages. A good toString() means your logs show useful text, not "[object Object]".
2. Small value objects. A value object is a small object that stands for one value, such as an amount of money, a length, a temperature, or an ID. Some of these can have a simple, well-tested conversion.
3. Finding bugs. When +, ==, or > gives a strange result, ask "which hint did this send?" instead of guessing.

A conversion method is your own code, and JavaScript may call it when you don't expect it. For example, logging and template literals call it. So keep these methods short and safe:

• They should only build and return a value.
• They shouldn't change anything, such as the items in a cart.
• They shouldn't send requests over the network.
• They should give the same answer every time they are called.

A total shown on screen is a good place for automatic conversion. In the example below, the total turns into readable text inside a message. The number of cents stays in its own property, ready for math and for saving.

1const cartTotal = {2  cents: 1299,3  toString() {4    return `$${(this.cents / 100).toFixed(2)}`;5  }6};7 8console.log(`Total: ${cartTotal}`);9console.log(cartTotal.cents / 100);

Line 8 prints Total: $12.99. Line 9 prints 12.99. The toString() method only builds the label. The math on line 9 uses the cents property directly.

Not every piece of code asks for a primitive. This explains why a conversion method sometimes seems to be skipped. Here are two examples:

• Truthiness is whether a value counts as true in a check like if. Every object counts as true. JavaScript doesn't ask the object for a primitive to decide this.
• JSON.stringify() turns an object into JSON text. It reads the object's own properties. It doesn't call toString().

1const amount = {2  valueOf() {3    return 0;4  }5};6 7console.log(Boolean(amount));8console.log(amount == 0);

1const user = {2  name: "Asha",3  toString() {4    return "not used by JSON";5  }6};7 8console.log(JSON.stringify(user));

• Boolean example, line 7: Boolean(amount) prints true, because every object counts as true.
• Boolean example, line 8: amount == 0 asks the object for a primitive. valueOf() returns 0, and 0 equals 0, so it prints true.
• JSON example, line 8: it prints {"name":"Asha"}. JSON.stringify() read the name property and didn't call toString().

Common misconceptions

• "A plus sign asks for a string." Not at first. With an object, + sends the "default" hint. Only when both sides are primitives does it choose: if either side is text, it joins them; if not, it adds them.
• "The hint decides the final type." No. The object can return any primitive. The code may convert that primitive again afterward.
• "valueOf() always runs first." Only for the "number" and "default" hints. The "string" hint tries toString() first.
• "Plain objects can't become strings." They can. Their built-in toString() returns "[object Object]".
• "Dates work like plain objects." No. A date treats the "default" hint like "string". That is why date + 1 adds "1" to the end of the date text.
• "If Symbol.toPrimitive returns an object, JavaScript tries valueOf() next." No. It throws a TypeError. The method must return a primitive.
• "A conversion method can do any work." It shouldn't. It should only return a value. Don't change data inside it, such as the items in a cart.
• "Every value object needs Symbol.toPrimitive." No. Start with named methods. Add automatic conversion only when the meaning is obvious and won't change.

Key takeaways

• JavaScript checks for a method at Symbol.toPrimitive first, and passes it the hint.
• If that method returns an object, JavaScript throws a TypeError.
• Without that method, the "string" hint tries toString() before valueOf().
• Without that method, the "number" and "default" hints try valueOf() before toString().
• A plus between two values and == send "default". +obj, *, and > send "number". Template literals and String() send "string".
• Arrays turn into text by joining their items with commas. Dates treat the "default" hint like "string".

Object to primitive conversion is JavaScript asking an object for one primitive, using a hint, before the rest of the code goes on.

Up next: Array basics.