Objects & references

One object can have many names

The Data types lesson said two things. When you copy a number or a string, you copy the value itself. When you copy an object, you copy a reference to it. This lesson shows what that means in real code.

A reference is how JavaScript finds an object. Think of it as the object's address. You never see the reference itself. You only see the object it leads to.

const cart = { item: "tea" };
const checkoutCart = cart;
checkoutCart.item = "coffee";
console.log(cart.item); // coffee

Line 1 makes one cart object with the item "tea". Line 2 copies the reference into checkoutCart. It does not make a second cart. Line 3 changes the item to "coffee" through checkoutCart. Line 4 reads the item through cart and prints coffee, because there is only one cart.

This rule shows up all the time in real code:

• arrays, which are objects too
• settings objects passed around a program
• objects passed to functions
• code that must not change data by accident

Later lessons go deeper: Memory: primitives vs objects, Freezing, sealing & immutability, Immutability, and Messaging & structured cloning. This lesson covers the everyday rules.

Primitives are the simple values: numbers, strings, booleans, null, and undefined. When you copy a primitive, you get your own copy of the value. Changing one variable later does not change the other. Objects work differently. When you copy an object variable, you copy the reference, so both variables point at the same object.

let x = 1;
let y = x;
y = 2;
console.log(x); // 1

const a = { score: 1 };
const b = a;
b.score = 2;
console.log(a.score); // 2

Lines 1 to 4 copy a number. y gets its own 1, so line 3 changes only y, and line 4 prints 1. Lines 6 to 9 copy an object variable. b points at the same object as a. Line 8 changes score through b, so line 9 prints 2.

The playground below runs real code step by step. For each step it shows two lists:

• on the left, each variable and the object it points at
• on the right, each object, with a number like #1 so you can tell them apart

The numbers are only labels for this lesson. They are not real memory addresses.

1const a = { score: 1 };2const b = a;3b.score = 2;4const c = { ...a };5c.score = 3;6a.stats = { level: "bronze" };7const d = { ...a };8d.stats.level = "silver";

Ask two questions at each step. First: do two variables point at the same object? Second: if there is a copy, does it still share an object stored inside it? Step 5 shows the second case. The section on shallow copies explains it.

Function parameters follow the same rule. When you pass an object to a function, the parameter gets a copy of the reference. So the parameter and your variable point at the same object. This means:

• If the function changes a property of the object, you see that change after the call.
• If the function gives the parameter a whole new value, like user = { ... }, only the parameter points somewhere new. Your variable does not change.

This rule is called call by sharing: the function shares your object, but not your variable. Some people call it "pass by reference". That name is not quite right. With true pass by reference, a function could make your variable point at a different object, and JavaScript can't do that.

function markDone(todo) {
  todo.done = true;
}

const todo = { done: false };
markDone(todo);
console.log(todo.done); // true

Lines 1 to 3 make a function, markDone. Line 2 sets the done property of the object it gets. Line 5 makes a todo object with done: false. Line 6 passes it to the function, so the parameter points at the same object. Line 7 prints true, because the function changed that one object.

In the replay below, you can switch the function body. Compare the two versions:

• Change a property: line 2 adds badge to the shared object, so ada.badge is "mentor".
• Give the parameter a new object: line 2 points user at a different object, so ada.badge stays undefined.

1function addBadge(user) {2  user.badge = "mentor";3}4 5const ada = { name: "Ada" };Run6addBadge(ada);7console.log(ada.badge);

The Comparisons lesson taught ===, strict equality. For objects, === asks one question: "Do both sides point at the very same object?" This is called checking identity. It does not look at the keys and values inside.

const first = { score: 1 };
const second = { score: 1 };
console.log(first === second); // false

Line 1 makes an object with score: 1. Line 2 makes another object with score: 1. Each pair of curly braces { } makes a brand-new object. So these are two objects that look alike. Line 3 prints false, because they are not the same object.

1const a = { score: 1 };Run2const b = a;3const c = { score: 1 };4 5console.log(a === b);6console.log(a === c);7console.log({ score: 1 } === { score: 1 });

Sometimes you do want to know if two objects hold the same things. The table shows three ways to compare. Read each row as: "to answer this question, write this, and watch out for this."

For a flat object, one with no objects stored inside it, you can compare contents yourself. Check that both objects have the same keys, and that each key has the same value. You have to write that check. === never does it for you.

A shallow copy makes a new outer object and copies each top-level property into it. If a property holds another object, only the reference to that inner object is copied. There are three common ways to make one:

• { ...obj }, called spread, for objects
• Object.assign(, obj), which copies the properties of obj into a new empty object
• [...array], spread for arrays

1const user = {2  name: "Asha",3  delivery: { note: "Leave at door" },4};5 6const shallow = { ...user };7shallow.delivery.note = "Ring bell";8 9const deep = structuredClone(user);10deep.delivery.note = "Call first";11 12console.log(user.delivery.note);13console.log(deep.delivery.note);

Lines 1 to 4 make a user object. Its delivery property holds a second object, with a note. Line 6 makes shallow, a new outer object. But shallow.delivery and user.delivery point at the same inner object. Line 7 changes the note through shallow, so user sees the new note too. Line 12 prints Ring bell.

Lines 9 and 10 use structuredClone, which copies the inner object too. The next section explains it. Line 13 prints Call first, and the note in user stays Ring bell.

const drinks = ["tea"];
const nextDrinks = [...drinks];
nextDrinks.push("coffee");
console.log(drinks.length); // 1
console.log(nextDrinks.length); // 2

Line 2 makes a new array, nextDrinks, with the same items. Line 3 adds "coffee" to the new array only. So line 4 prints 1 and line 5 prints 2. If the array held objects, both arrays would still share those objects.

Good to know: push, sort, and reverse change the array you call them on. To keep the old array as it was, copy it first with [...drinks]. If you only need a sorted result, use toSorted(). It gives back a new sorted array and leaves the old one alone.

Deep copies with structuredClone

A deep copy copies the objects stored inside too, at every level. Nothing is shared with the original. The built-in function structuredClone(value) makes a deep copy. It works in modern browsers and in recent versions of Node.

It can copy most kinds of data:

• plain objects and arrays
• dates (Date), and the collections Map and Set
• many other built-in data types

It cannot copy functions or page elements (DOM nodes). If you try to copy a function, it throws an error called DataCloneError.

const settings = { theme: { color: "blue" } };
const copy = structuredClone(settings);
copy.theme.color = "green";
console.log(settings.theme.color); // blue
console.log(copy.theme.color); // green

Line 1 makes settings, with a theme object inside. Line 2 makes a deep copy, so the copy gets its own theme object. Line 3 changes the color in the copy only. Line 4 prints blue and line 5 prints green.

The table compares five ways to copy an object. Read each row as: "this way copies this much, and watch out for this."

Use structuredClone only when you really need a fully separate copy. Don't use it for every change:

• A deep copy takes more work, because it copies everything.
• Some objects, like a page element, should not be copied at all.
• If you change only one part, you can copy just the objects on the way to that part. The "Where you'll use this" section shows how.

const doesn’t freeze an object

The Variables lesson introduced const. It means you can't give the variable a new value later. It does not lock the object. You can still change the properties of a const object, because the variable keeps pointing at the same object.

1const user = { name: "Ada" };2user.name = "Grace";     // allowed3// user = { name: "Lin" }; // TypeError if you run it4console.log(user.name);   // "Grace"

Line 1 makes a user object. Line 2 changes its name, and that is allowed. Line 3 is turned off with //. If you ran it, it would throw a TypeError, because it tries to point user at a new object. Line 4 prints "Grace".

To stop changes to the object itself, there is a separate tool: Object.freeze(user). It only locks the outer object, not the objects stored inside it. The Freezing, sealing & immutability lesson covers it later.

Where you’ll use this

References matter whenever two parts of a program use the same data. Some everyday examples:

• A function gets a settings object. If it changes settings.theme, the object you passed in changes too.
• Many page frameworks only notice a change when they get a new object. So code often makes a shallow copy with the change, instead of changing the old object.
• Tests usually compare what is inside two objects, not whether they are the same object. Two correct functions can return objects that look alike but are different objects.
• Sending data between browser windows or workers copies it with the same rules as structuredClone. The Messaging & structured cloning lesson covers this later.

Take care when you change something deep inside an object. Say a cart has an item object inside it. If you copy only the cart, the old cart and the new cart still share that item. So make a new object at each level you change, and put the new value in.

1const cart = {2  item: { name: "tea", quantity: 1 },3};4 5const nextCart = {6  ...cart,7  item: { ...cart.item, quantity: 2 },8};9 10console.log(cart.item.quantity);11console.log(nextCart.item.quantity);

Lines 1 to 3 make a cart with one item, tea, with quantity 1. Line 5 starts a new object, nextCart. Line 6 copies the cart's properties into it. Line 7 replaces item with a new item object: it copies the old item's properties, then sets quantity to 2. Line 10 prints 1 and line 11 prints 2. The old item never changed.

Common mistakes

Before each one, picture the arrows: which variables point at which object? Then ask what each line does. Does it change something inside an object, point a variable at a new value, or make a copy?

const a = { score: 1 };
const b = a;
b.score = 5;
console.log(a.score);

function renameUser(user, name) {
  user.name = name;
  return user;
}

function renameUser(user, name) {
  return { ...user, name };
}

const copy = structuredClone(settings);
copy.theme.color = "blue";

const copy = structuredClone(settings);
copy.theme.color = "blue";

function sameFlatObject(left, right) {
  const leftKeys = Object.keys(left);
  const rightKeys = Object.keys(right);
  return leftKeys.length === rightKeys.length &&
    leftKeys.every((key) => Object.hasOwn(right, key) && Object.is(left[key], right[key]));
}

function sameFlatObject(left, right) {
  const leftKeys = Object.keys(left);
  const rightKeys = Object.keys(right);
  return leftKeys.length === rightKeys.length &&
    leftKeys.every((key) => Object.hasOwn(right, key) && Object.is(left[key], right[key]));
}

const pet = { name: "Momo" };
pet.name = "Pip";
console.log(pet.name);

function setQuantity(cart, quantity) {
  return {
    ...cart,
    item: { ...cart.item, quantity },
  };
}

function setQuantity(cart, quantity) {
  return {
    ...cart,
    item: { ...cart.item, quantity },
  };
}

Pick an answer, then read the explanation for every choice. The wrong choices show common mistakes. For copy questions, ask first: is the changed property at the top level, or inside an object stored inside?

Key takeaways

A variable that holds an object holds a reference to it. Copies, function calls, comparisons, and const all follow from that one rule.

• A variable that holds an object holds a reference: a way to find the object.
• Copying that variable copies the reference. It does not make a new object.
• A function can change the properties of an object you pass in. Giving its parameter a new object changes only the parameter.
• For objects, === checks whether both sides are the same object. It does not compare what is inside.
• Spread and Object.assign make shallow copies: objects stored inside are still shared. structuredClone makes a deep copy.
• const stops the variable from getting a new value. It does not stop changes inside the object.

Up next: Methods & this. Objects can hold functions too, and you'll learn how a function knows which object it belongs to.