useState é um Hook do React que permite adicionar uma variável de estado ao seu componente.

const [state, setState] = useState(initialState)

Referência

useState(initialState)

Chame useState no nível superior do seu componente para declarar uma variável de estado.

import { useState } from 'react';

function MeuComponente() {
  const [idade, setIdade] = useState(28);
  const [nome, setNome] = useState('Taylor');
  const [tarefas, setTarefas] = useState(() => criarTarefas());
  // ...

A convenção é nomear variáveis de estado como [algo, setAlgo] usando desestruturação de array.

Veja mais exemplos abaixo.

Parâmetros

  • initialState: O valor que você quer que o estado tenha inicialmente. Pode ser um valor de qualquer tipo, mas há um comportamento especial para funções. Este argumento é ignorado após a renderização inicial.
    • Se você passar uma função como initialState, ela será tratada como uma função inicializadora. Ela deve ser pura, não deve receber argumentos e deve retornar um valor de qualquer tipo. O React chamará sua função inicializadora ao inicializar o componente e armazenará seu valor de retorno como o estado inicial. Veja um exemplo abaixo.

Retornos

useState retorna um array com exatamente dois valores:

  1. O estado atual. Durante a primeira renderização, ele corresponderá ao initialState que você passou.
  2. A função set que permite atualizar o estado para um valor diferente e acionar uma nova renderização.

Ressalvas

  • useState é um Hook, então você só pode chamá-lo no nível superior do seu componente ou em seus próprios Hooks. Você não pode chamá-lo dentro de loops ou condições. Se precisar disso, extraia um novo componente e mova o estado para ele.
  • No Modo Estrito, o React chamará sua função inicializadora duas vezes para ajudar você a encontrar impurezas acidentais. Este é um comportamento apenas de desenvolvimento e não afeta a produção. Se sua função inicializadora for pura (como deveria ser), isso não afetará o comportamento. O resultado de uma das chamadas será ignorado.

Funções set, como setAlgo(proximoEstado)

A função set retornada por useState permite atualizar o estado para um valor diferente e acionar uma nova renderização. Você pode passar o próximo estado diretamente ou uma função que o calcule a partir do estado anterior:

const [nome, setNome] = useState('Edward');

function handleClick() {
  setNome('Taylor');
  setIdade(i => i + 1);
  // ...

Parâmetros

  • proximoEstado: O valor que você quer que o estado seja. Pode ser um valor de qualquer tipo, mas há um comportamento especial para funções.
    • Se você passar uma função como proximoEstado, ela será tratada como uma função atualizadora. Ela deve ser pura, deve receber o estado pendente como seu único argumento e deve retornar o próximo estado. O React colocará sua função atualizadora em uma fila e renderizará novamente seu componente. Durante a próxima renderização, o React calculará o próximo estado aplicando todas as atualizações enfileiradas ao estado anterior. Veja um exemplo abaixo.

Retornos

As funções set não têm valor de retorno.

Ressalvas

  • A função set apenas atualiza a variável de estado para a próxima renderização. Se você ler a variável de estado após chamar a função set, você ainda obterá o valor antigo que estava na tela antes da sua chamada.

  • Se o novo valor que você fornecer for idêntico ao state atual, determinado por uma comparação Object.is, o React ignorará a renderização do componente e seus filhos. Esta é uma otimização. Embora em alguns casos o React ainda possa precisar chamar seu componente antes de ignorar os filhos, isso não deve afetar seu código.

  • O React agrupa atualizações de estado. Ele atualiza a tela depois que todos os manipuladores de eventos foram executados e chamaram suas funções set. Isso evita múltiplas renderizações durante um único evento. No raro caso em que você precise forçar o React a atualizar a tela mais cedo, por exemplo, para acessar o DOM, você pode usar flushSync.

  • Chamar a função set durante a renderização só é permitido dentro do componente atualmente em renderização. O React descartará sua saída e tentará imediatamente renderizá-lo novamente com o novo estado. Este padrão raramente é necessário, mas você pode usá-lo para armazenar informações das renderizações anteriores. Veja um exemplo abaixo.

  • No Modo Estrito, o React chamará sua função atualizadora duas vezes para ajudar você a encontrar impurezas acidentais. Este é um comportamento apenas de desenvolvimento e não afeta a produção. Se sua função atualizadora for pura (como deveria ser), isso não afetará o comportamento. O resultado de uma das chamadas será ignorado.

Uso

Adicionando estado a um componente

Chame useState no nível superior do seu componente para declarar uma ou mais variáveis de estado.

import { useState } from 'react';

function MeuComponente() {
  const [idade, setIdade] = useState(42);
  const [nome, setNome] = useState('Taylor');
  // ...

A convenção é nomear variáveis de estado como [algo, setAlgo] usando desestruturação de array.

useState retorna um array com exatamente dois itens:

  1. O estado atual desta variável de estado, inicialmente definido como o estado inicial que você forneceu.
  2. A função set que permite alterá-lo para qualquer outro valor em resposta à interação.

Para atualizar o que está na tela, chame a função set com algum estado seguinte:

function handleClick() {
  setNome('Robin');
}

O React armazenará o próximo estado, renderizará seu componente novamente com os novos valores e atualizará a UI.

Pitfall

Chamar a função set não altera o estado atual no código já em execução:

function handleClick() {
  setNome('Robin');
  console.log(nome); // Ainda "Taylor"!
}

Isso apenas afeta o que useState retornará a partir da próxima renderização.

Exemplos básicos de useState

Example 1 of 4:
Contador (número)

Neste exemplo, a variável de estado count contém um número. Clicar no botão o incrementa.

import { useState } from 'react';

export default function Contador() {
  const [count, setCount] = useState(0);

  function handleClick() {
    setCount(count + 1);
  }

  return (
    <button onClick={handleClick}>
      Você clicou {count} vezes
    </button>
  );
}

Atualizando o estado com base no estado anterior

Suponha que idade seja 42. Este manipulador chama setIdade(idade + 1) três vezes:

function handleClick() {
  setIdade(idade + 1); // setIdade(42 + 1)
  setIdade(idade + 1); // setIdade(42 + 1)
  setIdade(idade + 1); // setIdade(42 + 1)
}

No entanto, após um clique, idade será apenas 43 em vez de 45! Isso ocorre porque chamar a função set não atualiza a variável de estado idade no código já em execução. Então, cada chamada setIdade(idade + 1) se torna setIdade(43).

Para resolver esse problema, você pode passar uma função atualizadora para setIdade em vez do próximo estado:

function handleClick() {
  setIdade(a => a + 1); // setIdade(42 => 43)
  setIdade(a => a + 1); // setIdade(43 => 44)
  setIdade(a => a + 1); // setIdade(44 => 45)
}

Aqui, a => a + 1 é sua função atualizadora. Ela recebe o estado pendente e calcula o próximo estado a partir dele.

O React coloca suas funções atualizadoras em uma fila. Em seguida, durante a próxima renderização, ele as chamará na mesma ordem:

  1. a => a + 1 receberá 42 como o estado pendente e retornará 43 como o próximo estado.
  2. a => a + 1 receberá 43 como o estado pendente e retornará 44 como o próximo estado.
  3. a => a + 1 receberá 44 como o estado pendente e retornará 45 como o próximo estado.

Não há outras atualizações enfileiradas, então o React armazenará 45 como o estado atual no final.

Por convenção, é comum nomear o argumento do estado pendente com a primeira letra do nome da variável de estado, como a para idade. No entanto, você também pode chamá-lo de idadeAnterior ou algo que considere mais claro.

O React pode chamar suas atualizações duas vezes no desenvolvimento para verificar se são puras.

Deep Dive

Usar sempre uma função atualizadora é preferível?

Você pode ouvir uma recomendação para sempre escrever código como setIdade(a => a + 1) se o estado que você está definindo for calculado a partir do estado anterior. Não há problema nisso, mas nem sempre é necessário.

Na maioria dos casos, não há diferença entre essas duas abordagens. O React sempre garante que para ações intencionais do usuário, como cliques, a variável de estado idade seria atualizada antes do próximo clique. Isso significa que não há risco de um manipulador de cliques ver um valor “obsoleto” de idade no início do manipulador de eventos.

No entanto, se você fizer várias atualizações dentro do mesmo evento, as funções atualizadoras podem ser úteis. Elas também são úteis se acessar a própria variável de estado for inconveniente (você pode encontrar isso ao otimizar re-renderizações).

Se você preferir consistência em vez de uma sintaxe um pouco mais verbosa, é razoável sempre escrever uma função atualizadora se o estado que você está definindo for calculado a partir do estado anterior. Se for calculado a partir do estado anterior de alguma outra variável de estado, você pode querer combiná-las em um objeto e usar um reducer.

A diferença entre passar uma função atualizadora e passar o próximo estado diretamente

Example 1 of 2:
Passando a função atualizadora

Este exemplo passa a função atualizadora, então o botão “+3” funciona.

import { useState } from 'react';

export default function Contador() {
  const [idade, setIdade] = useState(42);

  function incrementar() {
    setIdade(a => a + 1);
  }

  return (
    <>
      <h1>Sua idade: {idade}</h1>
      <button onClick={() => {
        incrementar();
        incrementar();
        incrementar();
      }}>+3</button>
      <button onClick={() => {
        incrementar();
      }}>+1</button>
    </>
  );
}

Atualizando objetos e arrays no estado

Você pode colocar objetos e arrays no estado. No React, o estado é considerado somente leitura, então você deve substituí-lo em vez de mutar seus objetos existentes. Por exemplo, se você tem um objeto form no estado, não o mute:

// 🚩 Não mute um objeto no estado desta forma:
form.firstName = 'Taylor';

Em vez disso, substitua o objeto inteiro criando um novo:

// ✅ Substitua o estado com um novo objeto
setForm({
  ...form,
  firstName: 'Taylor'
});

Leia atualizando objetos no estado e atualizando arrays no estado para saber mais.

Exemplos de objetos e arrays no estado

Example 1 of 4:
Formulário (objeto)

Neste exemplo, a variável de estado form contém um objeto. Cada entrada tem um manipulador de alteração que chama setForm com o próximo estado de todo o formulário. A sintaxe de propagação { ...form } garante que o objeto de estado seja substituído em vez de mutado.

import { useState } from 'react';

export default function Form() {
  const [form, setForm] = useState({
    firstName: 'Barbara',
    lastName: 'Hepworth',
    email: 'bhepworth@sculpture.com',
  });

  return (
    <>
      <label>
        Primeiro nome:
        <input
          value={form.firstName}
          onChange={e => {
            setForm({
              ...form,
              firstName: e.target.value
            });
          }}
        />
      </label>
      <label>
        Sobrenome:
        <input
          value={form.lastName}
          onChange={e => {
            setForm({
              ...form,
              lastName: e.target.value
            });
          }}
        />
      </label>
      <label>
        Email:
        <input
          value={form.email}
          onChange={e => {
            setForm({
              ...form,
              email: e.target.value
            });
          }}
        />
      </label>
      <p>
        {form.firstName}{' '}
        {form.lastName}{' '}
        ({form.email})
      </p>
    </>
  );
}

Evitando recriar o estado inicial

O React salva o estado inicial uma vez e ignora-o nas renderizações subsequentes.

function TodoList() {
  const [todos, setTodos] = useState(createInitialTodos());
  // ...

Embora o resultado de createInitialTodos() seja usado apenas para a renderização inicial, você ainda está chamando essa função em toda renderização. Isso pode ser dispendioso se estiver criando grandes arrays ou realizando cálculos caros.

Para resolver isso, você pode passar uma função inicializadora para useState:

function TodoList() {
  const [todos, setTodos] = useState(createInitialTodos);
  // ...

Note que você está passando createInitialTodos, que é a função em si, e não createInitialTodos(), que é o resultado de chamá-la. Se você passar uma função para useState, o React só a chamará durante a inicialização.

O React pode chamar seus inicializadores duas vezes no modo de desenvolvimento para verificar se eles são puros.

A diferença entre passar uma função inicializadora e passar o estado inicial diretamente

Example 1 of 2:
Passando a função inicializadora

Este exemplo passa a função inicializadora, então a função createInitialTodos só é executada durante a inicialização. Ela não é executada quando o componente é re-renderizado, como quando você digita na entrada.

import { useState } from 'react';

function createInitialTodos() {
  const initialTodos = [];
  for (let i = 0; i < 50; i++) {
    initialTodos.push({
      id: i,
      text: 'Item ' + (i + 1)
    });
  }
  return initialTodos;
}

export default function TodoList() {
  const [todos, setTodos] = useState(createInitialTodos);
  const [text, setText] = useState('');

  return (
    <>
      <input
        value={text}
        onChange={e => setText(e.target.value)}
      />
      <button onClick={() => {
        setText('');
        setTodos([{
          id: todos.length,
          text: text
        }, ...todos]);
      }}>Adicionar</button>
      <ul>
        {todos.map(item => (
          <li key={item.id}>
            {item.text}
          </li>
        ))}
      </ul>
    </>
  );
}

Reiniciando o estado com uma chave

Você frequentemente encontrará o atributo key ao renderizar listas. No entanto, ele também serve a outro propósito.

Você pode reiniciar o estado de um componente passando uma key diferente para um componente. Neste exemplo, o botão Reset altera a variável de estado version, que passamos como uma key para o Form. Quando a key muda, o React recria o componente Form (e todos os seus filhos) do zero, então seu estado é reiniciado.

Leia preservando e reiniciando o estado para saber mais.

import { useState } from 'react';

export default function App() {
  const [version, setVersion] = useState(0);

  function handleReset() {
    setVersion(version + 1);
  }

  return (
    <>
      <button onClick={handleReset}>Reiniciar</button>
      <Form key={version} />
    </>
  );
}

function Form() {
  const [name, setName] = useState('Taylor');

  return (
    <>
      <input
        value={name}
        onChange={e => setName(e.target.value)}
      />
      <p>Olá, {name}.</p>
    </>
  );
}

Armazenando informações de renderizações anteriores

Normalmente, você atualizará o estado em manipuladores de eventos. No entanto, em casos raros, você pode querer ajustar o estado em resposta à renderização — por exemplo, você pode querer alterar uma variável de estado quando uma prop muda.

Na maioria dos casos, você não precisa disso:

No raro caso em que nenhuma dessas se aplica, há um padrão que você pode usar para atualizar o estado com base nos valores que foram renderizados até agora, chamando uma função set enquanto seu componente está renderizando.

Aqui está um exemplo. Este componente CountLabel exibe a prop count passada a ele:

export default function CountLabel({ count }) {
  return <h1>{count}</h1>
}

Digamos que você queira mostrar se o contador aumentou ou diminuiu desde a última alteração. A prop count não lhe diz isso — você precisa manter o controle de seu valor anterior. Adicione a variável de estado prevCount para rastreá-la. Adicione outra variável de estado chamada trend para manter se o count aumentou ou diminuiu. Compare prevCount com count, e se não forem iguais, atualize tanto prevCount quanto trend. Agora você pode mostrar tanto a prop count atual quanto como ela mudou desde a última renderização.

import { useState } from 'react';

export default function CountLabel({ count }) {
  const [prevCount, setPrevCount] = useState(count);
  const [trend, setTrend] = useState(null);
  if (prevCount !== count) {
    setPrevCount(count);
    setTrend(count > prevCount ? 'aumentando' : 'diminuindo');
  }
  return (
    <>
      <h1>{count}</h1>
      {trend && <p>O contador está {trend}</p>}
    </>
  );
}

Note que se você chamar uma função set durante a renderização, ela deve estar dentro de uma condição como prevCount !== count, e deve haver uma chamada como setPrevCount(count) dentro da condição. Caso contrário, seu componente renderizaria em um loop até travar. Além disso, você só pode atualizar o estado do componente atualmente renderizando desta forma. Chamar a função set de outro componente durante a renderização é um erro. Finalmente, sua chamada set ainda deve atualizar o estado sem mutação — isso não significa que você pode quebrar outras regras das funções puras.

Este padrão pode ser difícil de entender e geralmente é melhor evitá-lo. No entanto, é melhor do que atualizar o estado em um efeito. Quando você chama a função set durante a renderização, o React renderizará esse componente imediatamente após seu componente sair com uma instrução return, e antes de renderizar os filhos. Desta forma, os filhos não precisam renderizar duas vezes. O resto da função do seu componente ainda será executado (e o resultado será descartado). Se sua condição estiver abaixo de todas as chamadas de Hook, você pode adicionar um return; antecipado para reiniciar a renderização mais cedo.

Solução de problemas

Atualizei o estado, mas o log me dá o valor antigo

Chamar a função set não altera o estado no código em execução:

function handleClick() {
  console.log(count);  // 0

  setCount(count + 1); // Solicita uma nova renderização com 1
  console.log(count);  // Ainda 0!

  setTimeout(() => {
    console.log(count); // Também 0!
  }, 5000);
}

Isso ocorre porque o estado se comporta como um snapshot. Atualizar o estado solicita outra renderização com o novo valor de estado, mas não afeta a variável JavaScript count no seu manipulador de eventos já em execução.

Se você precisa usar o próximo estado, você pode salvá-lo em uma variável antes de passá-lo para a função set:

const nextCount = count + 1;
setCount(nextCount);

console.log(count);     // 0
console.log(nextCount); // 1

Atualizei o estado, mas a tela não atualiza

O React ignorará sua atualização se o próximo estado for igual ao estado anterior, determinado por uma comparação Object.is. Isso geralmente acontece quando você altera um objeto ou um array no estado diretamente:

obj.x = 10;  // 🚩 Errado: mutando um objeto existente
setObj(obj); // 🚩 Não faz nada

Você mutou um objeto obj existente e o passou de volta para setObj, então o React ignorou a atualização. Para corrigir isso, você precisa garantir que sempre está substituindo objetos e arrays no estado em vez de mutá-los:

// ✅ Correto: criando um novo objeto
setObj({
  ...obj,
  x: 10
});

Estou recebendo um erro: “Too many re-renders”

Você pode receber um erro que diz: Too many re-renders. React limits the number of renders to prevent an infinite loop. Tipicamente, isso significa que você está definindo o estado incondicionalmente durante a renderização, então o componente entra em um loop: renderiza, define o estado (o que causa uma renderização), renderiza, define o estado (o que causa uma renderização), e assim por diante. Muito frequentemente, isso é causado por um erro na especificação de um manipulador de eventos:

// 🚩 Errado: chama o manipulador durante a renderização
return <button onClick={handleClick()}>Clique aqui</button>

// ✅ Correto: passa o manipulador de eventos
return <button onClick={handleClick}>Clique aqui</button>

// ✅ Correto: passa uma função inline
return <button onClick={(e) => handleClick(e)}>Clique aqui</button>

Se você não consegue encontrar a causa deste erro, clique na seta ao lado do erro no console e olhe através da pilha JavaScript para encontrar a chamada específica da função set responsável pelo erro.

Minha função inicializadora ou atualizadora é executada duas vezes

No Modo Estrito, o React chamará algumas de suas funções duas vezes em vez de uma:

function TodoList() {
  // Esta função de componente será executada duas vezes para cada renderização.

  const [todos, setTodos] = useState(() => {
    // Esta função inicializadora será executada duas vezes durante a inicialização.
    return createTodos();
  });

  function handleClick() {
    setTodos(prevTodos => {
      // Esta função atualizadora será executada duas vezes para cada clique.
      return [...prevTodos, createTodo()];
    });
  }
  // ...

Isso é esperado e não deve quebrar seu código.

Este comportamento apenas de desenvolvimento ajuda você a manter os componentes puros. O React usa o resultado de uma das chamadas e ignora o resultado da outra chamada. Desde que suas funções de componente, inicializadoras e atualizadoras sejam puras, isso não deve afetar sua lógica. No entanto, se elas forem acidentalmente impuras, isso ajuda você a perceber os erros.

Por exemplo, esta função atualizadora impura muta um array no estado:

setTodos(prevTodos => {
  // 🚩 Erro: mutando o estado
  prevTodos.push(createTodo());
});

Como o React chama sua função atualizadora duas vezes, você verá que o todo foi adicionado duas vezes, então você saberá que há um erro. Neste exemplo, você pode corrigir o erro substituindo o array em vez de mutá-lo:

setTodos(prevTodos => {
  // ✅ Correto: substituindo por um novo estado
  return [...prevTodos, createTodo()];
});

Agora que esta função atualizadora é pura, chamá-la uma vez extra não faz diferença no comportamento. É por isso que o React chamar duas vezes ajuda você a encontrar erros. Apenas funções de componente, inicializadoras e atualizadoras precisam ser puras. Manipuladores de eventos não precisam ser puros, então o React nunca chamará seus manipuladores de eventos duas vezes.

Leia mantendo componentes puros para saber mais.

Estou tentando definir o estado para uma função, mas ela é chamada em vez disso

Você não pode colocar uma função no estado assim:

const [fn, setFn] = useState(someFunction);

function handleClick() {
  setFn(someOtherFunction);
}

Porque você está passando uma função, o React assume que someFunction é uma função inicializadora, e que someOtherFunction é uma função atualizadora, então tenta chamá-las e armazenar o resultado. Para realmente armazenar uma função, você precisa colocar () => antes delas em ambos os casos. Então o React armazenará as funções que você passa.

const [fn, setFn] = useState(() => someFunction);

function handleClick() {
  setFn(() => someOtherFunction);
}
PrevioususeRef
NextuseSyncExternalStore