Blog

Por que atualizar um objeto no useState exige cuidado?

Modificar um objeto não significa criar um novo estado.

7 min de leiturapor Leonardo Padilha
Capa do artigo Por que atualizar um objeto no useState exige cuidado?

Imagine que você está desenvolvendo um aplicativo de compras.

O usuário adiciona produtos ao carrinho, altera quantidades e remove itens. Tudo parece funcionar normalmente, até que você percebe algo estranho: a quantidade de um produto mudou no código, mas a tela continua mostrando o valor antigo.

Você olha para o código, não encontra nenhum erro e começa a se perguntar: se o valor foi alterado, por que o React não atualizou a interface?

A resposta está em um detalhe importante sobre como o React trabalha com objetos e referências.

O problema de modificar diretamente um objeto

Vamos começar com um exemplo simples de um carrinho de compras:

type CartItem = {
  id: number;
  name: string;
  price: number;
  quantity: number;
};

const initialCart: CartItem[] = [
  {
    id: 1,
    name: "Teclado",
    price: 150,
    quantity: 1
  },
  {
    id: 2,
    name: "Mouse",
    price: 80,
    quantity: 2
  }
];

Temos dois produtos no carrinho: um teclado e um mouse.

Agora imagine que queremos criar uma função para aumentar a quantidade de um produto.

Uma primeira tentativa poderia ser:

function increaseQuantity(productId: number) {
  const item = cart.find(
    product => product.id === productId
  );

  if (item) {
    item.quantity += 1;
    setCart(cart);
  }
}

À primeira vista, parece correto.

Encontramos o produto, aumentamos sua quantidade e enviamos o carrinho atualizado para o React.

Mas existe um problema nessa abordagem.

O que significa modificar diretamente?

Quando trabalhamos com objetos em JavaScript, uma variável não guarda necessariamente o objeto inteiro. Ela guarda uma referência para aquele objeto na memória.

Pense em uma caixa identificada como cart.

Dentro dela estão os produtos do nosso carrinho.

Quando executamos:

item.quantity += 1;

Estamos alterando diretamente uma informação que já pertence àquela caixa.

O conteúdo mudou, mas continuamos utilizando a mesma caixa.

É justamente aqui que está o problema.

O React utiliza Object.is() para comparar o estado anterior com o novo valor recebido. Quando recebe a mesma referência, pode entender que não existe uma nova atualização a realizar.

Por exemplo:

const cart = [{ name: "Teclado", quantity: 1 }];

const sameCart = cart;

console.log(Object.is(cart, sameCart)); // true

Mesmo que você altere uma propriedade dentro desse array, a referência continua sendo a mesma.

Por isso, modificar um objeto diretamente não é uma maneira segura de atualizar o estado no React.

A solução: criar uma nova versão do objeto

Em vez de modificar o objeto existente, precisamos criar uma nova versão com as alterações desejadas.

Esse conceito é conhecido como imutabilidade.

Na prática, significa preservar os dados originais e criar novas estruturas quando precisamos modificá-los.

Vamos entender primeiro como isso funciona em um exemplo pequeno:

const produto = {
  nome: "Teclado",
  quantidade: 1
};

const produtoAtualizado = {
  ...produto,
  quantidade: 2
};

Mas o que está acontecendo aqui?

  • ...produto copia as propriedades do objeto original.

  • quantidade: 2 substitui o valor anterior.

  • produtoAtualizado recebe um novo objeto.

  • O objeto produto continua com a quantidade original.

Agora podemos aplicar essa ideia ao nosso carrinho.

function increaseQuantity(productId: number) {
  setCart(currentCart =>
    currentCart.map(item =>
      item.id === productId
        ? {
            ...item,
            quantity: item.quantity + 1
          }
        : item
    )
  );
}

Vamos entender essa função por partes.

Primeiro: map()

O método map() percorre uma lista e cria um novo array com os resultados dessa operação.

Imagine que temos três produtos e queremos alterar apenas o segundo. O map() passa por todos eles, mas podemos decidir qual precisa receber uma nova versão.

Segundo: a condição

item.id === productId

Aqui verificamos se o produto atual é aquele que queremos atualizar.

Se for, criamos um novo objeto com a quantidade aumentada.

Se não for, mantemos o objeto como está.

Terceiro: o operador spread

{
  ...item,
  quantity: item.quantity + 1
}

Copiamos as propriedades do produto e alteramos somente a quantidade.

O resultado é um novo array contendo uma nova referência para o produto atualizado.

Assim, o React consegue identificar a mudança no estado.

Mas por que utilizar uma função dentro do setState?

Talvez você tenha percebido que escrevemos:

setCart(currentCart => {
  // atualização
});

Em vez de passar diretamente um novo valor, estamos passando uma função.

Isso é chamado de atualização funcional do estado.

Ela é especialmente útil quando o novo valor depende do valor anterior.

Vamos imaginar uma situação.

Um usuário está em uma página de compras e clica rapidamente três vezes no botão de aumentar quantidade.

Uma implementação como esta pode produzir resultados inesperados:

setQuantity(quantity + 1);
setQuantity(quantity + 1);
setQuantity(quantity + 1);

Isso acontece porque as três chamadas utilizam o valor de quantity disponível naquele mesmo contexto de renderização.

Se a quantidade inicial era 1, podemos acabar com 2 em vez de 4.

Agora veja outra abordagem:

setQuantity(current => current + 1);
setQuantity(current => current + 1);
setQuantity(current => current + 1);

Nesse caso, o React processa as atualizações funcionais em sequência:

  1. A quantidade passa de 1 para 2.

  2. Depois passa de 2 para 3.

  3. Finalmente passa de 3 para 4.

O resultado é exatamente o esperado.

Sempre que uma atualização depender do valor anterior do estado, utilizar a atualização funcional é uma boa prática.

E quando temos objetos dentro de objetos?

Até aqui, trabalhamos com um objeto relativamente simples.

Mas imagine que nosso produto também tenha informações adicionais:

type CartItem = {
  id: number;
  quantity: number;
  product: {
    name: string;
    category: string;
  };
};

Agora queremos alterar o nome de um produto.

Poderíamos pensar em fazer algo assim:

setCart(currentCart =>
  currentCart.map(item =>
    item.id === productId
      ? {
          ...item,
          product: {
            name: "Novo nome"
          }
        }
      : item
  )
);

Parece correto, mas existe um detalhe: perdemos a propriedade category do produto.

Isso acontece porque criamos um novo objeto product contendo apenas o nome.

Para preservar as demais informações, precisamos copiar também as propriedades internas:

setCart(currentCart =>
  currentCart.map(item =>
    item.id === productId
      ? {
          ...item,
          product: {
            ...item.product,
            name: "Novo nome"
          }
        }
      : item
  )
);

Perceba que agora criamos uma nova referência para três níveis:

  • O array do carrinho.

  • O objeto do produto no carrinho.

  • O objeto interno product.

Isso acontece porque o operador spread faz uma cópia superficial. Ele copia as propriedades do primeiro nível, mas não cria automaticamente novas cópias dos objetos que estão dentro dele.

A regra é simples: precisamos criar novas referências em todos os níveis que pretendemos modificar.

Precisamos copiar tudo sempre?

Não.

Imutabilidade não significa duplicar toda a aplicação a cada atualização.

No nosso exemplo, somente o array e o produto alterado recebem novas referências. Os demais produtos continuam sendo reutilizados.

Também não precisamos utilizar structuredClone() para qualquer alteração.

Fazer cópias profundas indiscriminadamente pode gerar trabalho desnecessário e não substitui uma boa organização do estado.

Para estruturas muito complexas, ferramentas como Immer podem facilitar esse processo, mas não são obrigatórias.

O importante é entender o que está sendo alterado e preservar os dados que não precisam mudar.

Para finalizar

Atualizar um estado no React não significa simplesmente modificar uma informação e esperar que a tela acompanhe a mudança.

Precisamos criar as novas referências necessárias para que o React consiga identificar a atualização.

Entender referências, imutabilidade e atualização funcional ajuda a evitar comportamentos inesperados, principalmente quando trabalhamos com listas, formulários, carrinhos de compras e estruturas de dados mais complexas.

Se existe uma ideia importante para guardar deste artigo, é esta:

Não modifique diretamente os objetos que pertencem ao estado. Crie novas versões com as alterações necessárias.

Pode parecer um detalhe pequeno, mas compreender esse funcionamento faz bastante diferença na hora de desenvolver aplicações React mais previsíveis e fáceis de manter.

Projetos

Precisa desenvolver ou melhorar uma aplicação?

Conheça meus projetos ou entre em contato para conversar sobre sua necessidade.