Immutability

Foundational

React relies on immutable updates to detect changes. Like pottery that's been fired — you can't reshape it, you make a new one.

💡 React uses Object.is() to detect changes. Without immutable updates, your state changes become invisible to React.

Value vs Reference

Primitives are copied by value (like mixing a new glaze). Objects are shared by reference (like pointing to the same pot).

Why Mutation Breaks React

React uses Object.is() to detect changes. Mutating an object keeps the same reference — React sees no change.

Spreading 101

The spread operator creates shallow copies. Learn the pattern — and the nested-object pitfall.

Array Operations

Immutable add, remove, and update patterns that replace push, splice, and direct index assignment.

These are the patterns that trip up developers most often. Switch between Wrong and Fixed to compare the code side by side.

Mutating arrays with push/splice

Using push(), splice(), or sort() directly on state arrays

Don't do this

list.tsx

function TodoList() {
  const [items, setItems] = useState(["Buy milk"]);

  function addItem(text) {
    items.push(text);       // mutates the existing array!
    setItems(items);        // same reference — React skips re-render
  }

  function removeFirst() {
    items.splice(0, 1);    // mutates in place!
    setItems(items);
  }
}

Methods like push(), pop(), splice(), sort(), and reverse() mutate the original array. When you mutate a state array and call setState with the same reference, React's shallow comparison sees the same object and skips re-rendering. Always create a new array with spread, filter, or map.

Mutating objects directly

Modifying a property on a state object instead of creating a new one

Don't do this

profile.tsx

function Profile() {
  const [user, setUser] = useState({ name: "Alice", age: 25 });

  function handleBirthday() {
    user.age += 1;    // mutates existing object
    setUser(user);    // same reference — no re-render!
  }
}

Directly modifying a property on a state object changes the existing object without creating a new reference. React uses Object.is() to detect changes — same reference means no change detected, no re-render. Always create a new object with the spread operator.

Shallow copy pitfall with nested objects

Spread only copies the top level — nested objects are still shared references

Don't do this

settings.tsx

function Settings() {
  const [user, setUser] = useState({
    name: "Alice",
    address: { city: "NYC", zip: "10001" },
  });

  function updateCity(city) {
    const newUser = { ...user };
    newUser.address.city = city; // MUTATES user.address too!
    setUser(newUser);
  }
}

The spread operator only creates a shallow copy. Top-level properties get new values, but nested objects are still shared references. Modifying a nested property on the 'copy' also modifies the original. Spread at every level of nesting, or use structuredClone() for deep copies.

function TodoList() { const [items, setItems] = useState(["Buy milk"]); function addItem(text) { items.push(text); // mutates the existing array! setItems(items); // same reference — React skips re-render } function removeFirst() { items.splice(0, 1); // mutates in place! setItems(items); } }

function Profile() { const [user, setUser] = useState({ name: "Alice", age: 25 }); function handleBirthday() { user.age += 1; // mutates existing object setUser(user); // same reference — no re-render! } }

function Settings() { const [user, setUser] = useState({ name: "Alice", address: { city: "NYC", zip: "10001" }, }); function updateCity(city) { const newUser = { ...user }; newUser.address.city = city; // MUTATES user.address too! setUser(newUser); } }

Immutability

Common Mistakes

Immutability

Common Mistakes