React Update Arrays and Objects in State (Immutably)

In React you update an array or an object in state by making a new one and passing it to the setter. Never change the existing value in place: use spread (...), map, filter or slice to build a copy with your change, then call setItems(copy).

import { useState } from 'react';

let nextId = 3;

export default function App() {
    const [items, setItems] = useState([
        { id: 1, name: 'Milk' },
        { id: 2, name: 'Bread' },
    ]);
    const [name, setName] = useState('Eggs');

    function add() {
        setItems([...items, { id: nextId++, name }]);
        setName('');
    }

    function remove(id) {
        setItems(items.filter((item) => item.id !== id));
    }

    return (
        <div>
            <input value={name} onChange={(e) => setName(e.target.value)} />
            <button onClick={add}>Add</button>
            <ul>
                {items.map((item) => (
                    <li key={item.id}>
                        {item.name} <button onClick={() => remove(item.id)}>x</button>
                    </li>
                ))}
            </ul>
        </div>
    );
}

[...items, { ... }] is a new array with one more item, and filter returns a new array without the removed one. Both leave the old array alone.

Why mutation does not render

When you call a setter, React compares the new value with the old one using Object.is. For arrays and objects that compares references, not contents. If you change an array with push and pass the same array back, React sees the same reference, decides nothing changed, and skips the render.

import { useState } from 'react';

export default function App() {
    const [items, setItems] = useState(['a']);

    function addByMutating() {
        items.push('mutated');
        setItems(items);
        console.log('pushed, length is now', items.length);
    }

    function addByCopying() {
        const next = [...items, 'copied'];
        setItems(next);
        console.log('spread: same array?', Object.is(items, next));
    }

    console.log('render', items.join(', '));

    return (
        <div>
            <button onClick={addByMutating}>push (mutates)</button>
            <button onClick={addByCopying}>spread (copies)</button>
            <p>{items.join(', ')}</p>
        </div>
    );
}

Click "push" a few times. The console shows the array growing, but no new render line appears and the text stays a. Then click "spread": one render happens and every pushed item shows up at once, because they were in the array all along. Mutation does not throw an error, it just leaves the screen out of date until something else triggers a render. Click "push" once more after that and this time it may render: React cannot always skip the work up front, so a mutation shows up sometimes and not other times. That unpredictability is the reason not to mutate state.

Arrays: methods to use and to avoid

The rule is simple: use methods that return a new array, avoid methods that change the array they are called on.

toSorted, toReversed, toSpliced and with are newer array methods (ES2023), supported in all current major browsers since 2023. They do the same job as their mutating cousins on a copy.

Updating one item with map

To change one item, map over the array and return a new object for the item you want, and the original object for every other one.

import { useState } from 'react';

export default function App() {
    const [todos, setTodos] = useState([
        { id: 1, text: 'Learn useState', done: true },
        { id: 2, text: 'Learn map', done: false },
        { id: 3, text: 'Build an app', done: false },
    ]);

    function toggle(id) {
        setTodos(
            todos.map((todo) =>
                todo.id === id ? { ...todo, done: !todo.done } : todo
            )
        );
    }

    return (
        <ul>
            {todos.map((todo) => (
                <li key={todo.id}>
                    <button onClick={() => toggle(todo.id)}>
                        {todo.done ? 'Undo' : 'Done'}
                    </button>{' '}
                    <span style={{ textDecoration: todo.done ? 'line-through' : 'none' }}>
                        {todo.text}
                    </span>
                </li>
            ))}
        </ul>
    );
}

The { ...todo, done: !todo.done } part matters. A common bug is to copy the array but change the object inside it:

const next = [...todos];
next[0].done = true; // next is new, but next[0] is the same object as todos[0]
setTodos(next);

This renders, so it looks fine, but the old array and the new array now share a changed object. Anything that compares the old item with the new one (a React.memo child, an effect that depends on the item) sees no difference. Copy the item you change.

Inserting at an index

There is no non-mutating insert, so slice the array in two and put the new item between the halves. toSpliced(index, 0, item) does the same in one call.

import { useState } from 'react';

export default function App() {
    const [letters, setLetters] = useState(['A', 'B', 'D', 'E']);
    const [index, setIndex] = useState(2);

    function insert() {
        const next = [
            ...letters.slice(0, index),
            'C',
            ...letters.slice(index),
        ];
        console.log('before:', letters.join(''), 'after:', next.join(''));
        setLetters(next);
    }

    return (
        <div>
            <label>
                Index{' '}
                <input
                    type="number"
                    value={index}
                    onChange={(e) => setIndex(Number(e.target.value))}
                    style={{ width: 50 }}
                />
            </label>{' '}
            <button onClick={insert}>Insert C</button>
            <p style={{ fontSize: 24, letterSpacing: 4 }}>{letters.join('')}</p>
        </div>
    );
}

Set the index to 0 and insert again: the new C goes to the front. Replace the next expression with letters.toSpliced(index, 0, 'C') and the result is the same.

Sorting and reversing

sort and reverse change the array they are called on, even though they also return it. That makes setItems(items.sort()) a mutation followed by a set with the same reference, which is the bug from the start of this page. Sort a copy instead.

import { useState } from 'react';

export default function App() {
    const [scores, setScores] = useState([42, 7, 19, 88, 3]);

    function sortAscending() {
        const sorted = scores.toSorted((a, b) => a - b);
        console.log('original still', scores.join(' '));
        setScores(sorted);
    }

    function reverse() {
        setScores([...scores].reverse());
    }

    return (
        <div>
            <button onClick={sortAscending}>Sort</button>
            <button onClick={reverse}>Reverse</button>
            <p>{scores.join(' ')}</p>
        </div>
    );
}

[...scores].reverse() works because the spread makes the copy first and reverse then changes only that copy.

Updating objects and nested objects

Objects follow the same rule. Spread the old object into a new one and override the fields that change. For a nested object, spread at every level on the way down to the field: a single spread copies only the top level, so the inner object would still be the old one.

import { useState } from 'react';

export default function App() {
    const [user, setUser] = useState({
        name: 'Ada',
        address: { city: 'London', country: 'UK' },
    });

    function moveTo(city, country) {
        const next = {
            ...user,
            address: { ...user.address, city, country },
        };
        console.log('user copied:', next !== user);
        console.log('address copied:', next.address !== user.address);
        setUser(next);
    }

    return (
        <div>
            <input
                value={user.name}
                onChange={(e) => setUser({ ...user, name: e.target.value })}
            />
            <p>
                {user.name} lives in {user.address.city}, {user.address.country}.
            </p>
            <button onClick={() => moveTo('Oslo', 'Norway')}>Move to Oslo</button>
        </div>
    );
}

Each level you copy is a new object; every level you do not touch stays the same object. That is what makes spread cheap: if the state also held a long list of orders, { ...user } would copy the reference to the list, not the list itself.

If an object in state is nested three or four levels deep and you keep writing long chains of spreads, that is often a sign the state could be flatter. Storing items in a lookup by id, or splitting one big object into a few useState calls, keeps each update short. When many events change one structure, a reducer also helps (see useReducer).

structuredClone vs spread

structuredClone(user) makes a deep copy in one call, so you can then change the copy freely:

const next = structuredClone(user);
next.address.city = 'Oslo';
setUser(next);

It is correct, but it copies the whole object every time, including the parts you did not change. That costs time on large state, and it means every nested object gets a new reference, so a memoized child that receives user.orders renders again even though the orders did not change. structuredClone also throws on functions, and class instances come back as plain objects. Spread copies only the path you change, so it is the usual choice; keep structuredClone for the rare update that really rewrites most of the object.

Writing mutations with Immer

Immer is a small library that lets you write code that looks like mutation. It hands you a draft, records what you change, and produces a new immutable value with only the changed parts copied. The use-immer package wraps it in a hook:

import { useImmer } from 'use-immer';

function Profile() {
    const [user, updateUser] = useImmer({
        name: 'Ada',
        address: { city: 'London' },
    });

    function moveTo(city) {
        updateUser((draft) => {
            draft.address.city = city;
        });
    }
    // ...
}

Immer is not available in the editors on this page, which only load React. It is worth adding when your state is deeply nested and the spreads get hard to read. For flat state, plain spread and map are enough, and they are what you will see in most React code.