Lendo e escrevendo átomos com useAtom

useAtom(someAtom) retorna [value, setter], reproduzindo a API de useState. O valor é o estado atual do átomo; a função de atualização o modifica. Utilize-o quando um componente tanto lê quanto escreve no átomo.

A função de atualização aceita um novo valor ou uma função de atualização: setCount(c => c + 1).

useAtomValue(someAtom) retorna somente o valor atual, sem uma função de atualização. Utilize-o em componentes que apenas exibem dados, leem o estado, mas nunca o modificam.

Como o componente não mantém uma referência à função de atualização, a intenção fica claramente documentada no código: este componente é um leitor puro.

useSetAtom(someAtom) retorna somente a função de atualização. O mais importante é que ele não inscreve o componente no valor do átomo. O componente nunca é renderizado novamente quando o átomo muda.

Utilize-o em componentes que executam somente ações, como botões que despacham mudanças de estado, mas não exibem nenhuma interface derivada.

Um componente que chama useSetAtom(countAtom) para incrementar um contador nunca será renderizado novamente quando countAtom mudar, pois não tem uma assinatura do valor. Somente o componente que exibe a contagem é renderizado novamente.

Essa é uma otimização simples, mas poderosa: desacople quem escreve de quem lê para evitar novas renderizações em cascata.

Importe atomWithStorage de jotai/utils. Utilize-o exatamente como atom(), mas passe uma chave de armazenamento como primeiro argumento: atomWithStorage('theme', 'light'). O átomo é sincronizado automaticamente com localStorage.

Ao recarregar a página, o átomo é hidratado a partir de localStorage. Todos os componentes que leem o átomo obtêm imediatamente o valor persistido.

O símbolo RESET de jotai/utils pode ser passado à função de atualização de um átomo atomWithStorage: setter(RESET). Isso limpa a entrada em localStorage e redefine o átomo para seu valor inicial.

Isso é útil em fluxos de encerramento de sessão ou em botões de "redefinir para os padrões" nas páginas de configurações.

atomFamily de jotai/utils cria uma fábrica que retorna um átomo parametrizado. Por exemplo, atomFamily(id => atom(null)) cria um átomo separado para cada id exclusivo informado.

Isso é ideal para estados por item, como selectedAtom(itemId) ou expandedAtom(rowId), sem precisar gerenciar um único átomo com um mapa grande.

As famílias de átomos podem crescer sem limite se os IDs se acumularem. Utilize atomFamily.setShouldRemove((createdAt, param) => ...) para definir um predicado de limpeza que o Jotai chama ao decidir remover membros antigos da família.

Em listas nas quais itens são adicionados e removidos, sempre limpe as entradas da família de átomos quando os itens forem excluídos para evitar vazamentos de memória.

O pacote jotai-devtools fornece um painel visual que lista todos os átomos ativos e seus valores atuais. Instale-o, envolva sua aplicação com DevTools e inspecione o estado dos átomos em tempo real.

Cada atualização de átomo é registrada com o valor anterior e o próximo, tornando simples depurar interações complexas entre átomos.

Em uma lista grande, um componente ListContainer pode usar useSetAtom(selectedIdAtom) para atualizar a seleção sem assinar selectedIdAtom. Somente os componentes ListItem individuais que chamam useAtomValue(selectedIdAtom) são renderizados novamente quando a seleção muda.

Esse padrão escala bem: adicionar milhares de itens à lista não torna as atualizações de seleção mais lentas.

Escolha o gancho que corresponde à necessidade do seu componente: useAtomValue para exibição pura, useSetAtom para ações puras e useAtom quando precisar de ambos. Esse design intencional da API torna clara, de imediato, a responsabilidade do componente.

Um componente de campo de formulário normalmente usa useAtom; um botão de envio usa useSetAtom; um rótulo que exibe uma contagem usa useAtomValue.

Qual é a principal vantagem de usar useSetAtom em vez de useAtom?

useAtom fornece o valor e a função de atualização; useAtomValue fornece somente o valor (assinaturas de leitura); useSetAtom fornece somente a função de atualização (sem nova renderização quando o valor muda). atomWithStorage persiste os dados em localStorage com suporte a RESET, e atomFamily cria átomos por parâmetro para listas dinâmicas.

Escolher o gancho correto minimiza novas renderizações desnecessárias e torna explícita a intenção do componente.